Go test assertion library.

• Test assertion (equal, comparison, nil, empty, length, error, etc...)
• No reflection (uses generics)
• Customization (print and compare values)
• Auto-updating assertions (snapshot testing)

A simple assertion:

assert.Equal(t, value, 1)

By default, assertions fail with Fatal(). It can be changed with the Report() option:

assert.Equal(t, value, 1, assert.ReportError())

The report message can be customized:

assert.Equal(t, value, 1, assert.MessageWrap("test"))

This assertion library is an experiment to see if it is possible to do better than github.com/stretchr/testify, by using generics.

Here is an example of an issue with github.com/stretchr/testify:

func Test(t *testing.T) {
    value := getValue()
    require.Equal(t, 1, value)
}

func getValue() int64 {
    return 1
}

Surprisingly, this test fails with this error:

Error: Not equal:
expected: int(1)
actual  : int64(1)

This issue is caused by the types, which are not identical (the 1 constant is an int and not an int64), and it's possible to fix it:

Convert the value to int64:

require.Equal(t, int64(1), value)

Use EqualValues() which converts the values to the same type:

require.EqualValues(t, 1, value)

But the internal implementation is not simple: it requires heavy usage of reflection, and the code is quite complex.

What if we could simply use the == operator? This is the solution chosen by this library. It uses generics to do the comparison, and it works with any comparable type:

func Equal[T comparable](tb testing.TB, v1, v2 T, opts ...Option) bool {
    tb.Helper()
    ok := v1 == v2
    if !ok {
        Fail(...)
    }
    return ok
}

assert.Equal(t, 1, value)

The constant 1 is automatically converted to the type of the value variable without using reflection.

However, this approach has a limitation: it requires writing a different assertion function for each "kind" (map, slice, etc...).

The default behavior can be customized:

• DeepEqualer allows customizing how values are compared with DeepEqual().
• ValueStringer allows customizing how values (including errors) are printed.

The assertauto sub-package provides assertions that automatically update their expected values. It compares actual values against expected values stored in files, and is useful for snapshot testing.

Unlike assert.Equal(), the expected value is not passed to the function but stored in a file:

assertauto.Equal(t, value)

To generate or update the expected values, run the tests with the environment variable ASSERTAUTO_UPDATE=true:

ASSERTAUTO_UPDATE=true go test ./...

The expected values are stored in the _assertauto directory, relative to the tested package. Each test creates a file named after the test, with the .txt extension. Values from the same test are stored sequentially in the same file. The storage directory can be changed with the environment variable ASSERTAUTO_DIRECTORY.

It also provides AllocsPerRun() to assert the number of allocations of a function.

The value stringer and the assert options can be customized with ValueStringer() and AssertOptions().

I think it's a great library, but I wanted to try something different. I also wanted to try generics, and to see if it was possible to make an assertion library without reflection.

• For slices use SliceNil() and SliceNotNil()
• For maps use MapNil() and MapNotNil()
• For comparable types use Zero() and NotZero()