Testify require and assert

External

• https://pkg.go.dev/github.com/stretchr/testify#readme-assert-package

Internal

• Testify

Overview

require and assert packages provide functions to evaluate arguments and establish whether the test passes or fails.

Experience shows that it's a good idea to use the "f" form of the functions (Equalf(), Nilf(), Containsf(), etc.) to provide messages that serve as documentation for the code and also explicit messages on failure.

result, err := DoSomething(model)
require.NotNilf(err, "failed to DoSomething() on model %v, error: ", model, err)

Calling assert and require from Goroutines

The major difference between require and assert is that assert means continue on error. If an assertion fails, the test reports it and the goroutine the asserting failure happened on continues execution. In the end, the overall test is counted as "failed", but while executing, the test keeps going on failed assertions. This is different from the behavior of assert in other languages and frameworks, where the first failed assertion stops the current test. This does not make too much sense - if an assertion is broken, I am not that interested in what comes after that, they are likely to be broken too, or at least, not to be trusted. assert exit behavior is internally implemented by calling Fail().

If you want the test to exit the current goroutine after the first failed assertion, use require. require means exit the goroutine on failed assertion. However, require does not exit the test. If the test is multi-threaded, you need to account for what other goroutines are doing. For example, if you use require from a goroutine that is supposed to release a semaphore, and require fails, the test might get deadlocked. require exit behavior is internally implemented by calling FailNow().

and require calling FailNow().

What happens when an assert fails? How is the test state impacted? Debug and find out.

Equality and Non-Equality

In case the result is failure, Equal() and NotEqual() delegate to Fail().

It works with structs.

package somepkg

import (
	"testing"

	testifyassert "github.com/stretchr/testify/assert"
    testifyrequire "github.com/stretchr/testify/require"
)

func TestSomething(t *testing.T) {
	assert := testifyassert.New(t)
    require := testifyrequire.New(t)
    assert.Equal(123, 123, "this message is displayed when the assertion fails, but the test continues %s", "because of inequality")
    require.Equal(123, 123, "this message is displayed when the test fails and exists %s", "because of inequality") 
	assert.NotEqual(123, 321, "this message is displayed when the test fails %s", "because of equality")
    require.NotEqual(123, 321, "this message is displayed when the test fails and exists %s", "because of inequality") 
}

Nil and Non-Nil

In case the result is failure, Nil() and NotNil() delegate to Fail().

package somepkg

import (
	"testing"

	testifyassert "github.com/stretchr/testify/assert"
    testifyrequire "github.com/stretchr/testify/require"
)

func TestSomething(t *testing.T) {
	assert := testifyassert.New(t)
    require := testifyrequire.New(t)
	someObj := &struct{}{}
	assert.NotNil(someObj, "someObj should not have been nil but it is %v, and the test continues", someObj)
	require.NotNil(someObj, "someObj should not have been nil but it is %v, and the test exits", someObj)
	someObj = nil
	assert.Nil(someObj, "someObj should have been nil but it is %v, and the test continues", someObj)
    require.Nil(someObj, "someObj should have been nil but it is %v, and the test exits", someObj)
}

Other Test Functions

Contains()

Applies to strings, slices and maps.

Contains(whole, fragment)

ErrorContains()

err := fmt.Error("something")
require.ErrorContains(err, "something")

Failing the Test

Fail()

Does not exit the current goroutine, so it does not stop the test. It annotates its internal state that there was a failure, and let the test continue. require.Fail() and assert.Fail() behavior is identical.

Failf()

Same as Fail(), but provide additional message features.

FailNow()

Annotate the test with failure and exit the current goroutine. This does not necessarily mean the test exits, if there are other goroutine going. require.FailNow() and assert.FailNow() behavior is identical.

FailNowf()

Same as FailNow(), but provide additional message features.

Checking that an Error Has Expected Message

err := ...
assert.NotNil(err)
assert.Equal(err.Error(), "expected message")