attest

Type-safe assertion functions for Go tests.

Installation

go get github.com/cboone/attest

Requires Go 1.21+.

Quick Start

package example_test

import (
    "testing"

    "github.com/cboone/attest"
)

func TestExample(t *testing.T) {
    attest.Equal(t, 42, computeAnswer())
    attest.NoError(t, err)
    attest.Must(t).NotNil(conn)
}

Assertion Functions

Function	Description
Equal	Asserts expected == actual using ==
NotEqual	Asserts expected != actual using !=
DeepEqual	Asserts deep equality using go-cmp
NotDeepEqual	Asserts deep inequality using go-cmp
Nil	Asserts value is nil (handles typed nils)
NotNil	Asserts value is not nil
True	Asserts value is true
False	Asserts value is false
GreaterThan	Asserts actual > threshold
LessThan	Asserts actual < threshold
GreaterOrEqual	Asserts actual >= threshold
LessOrEqual	Asserts actual <= threshold
Contains	Asserts string contains substring
NotContains	Asserts string does not contain substring
HasPrefix	Asserts string starts with prefix
HasSuffix	Asserts string ends with suffix
EqualFold	Asserts case-insensitive string equality
Matches	Asserts string matches regexp pattern
Len	Asserts collection has expected length
Empty	Asserts collection is empty
NotEmpty	Asserts collection is not empty
ContainsElement	Asserts slice contains element
HasKey	Asserts map contains key
NoError	Asserts error is nil
IsError	Asserts error is not nil
ErrorIs	Asserts errors.Is(err, target)
ErrorAs	Asserts errors.As(err, target)
ErrorContains	Asserts error message contains substring
Golden	Compares string against golden file
GoldenBytes	Compares bytes against golden file

Fatal Assertions

For assertions that should stop the test on failure, use Must(t) for non-generic assertions or MustXxx functions for generic assertions:

// Non-generic: method syntax
attest.Must(t).NoError(err)
attest.Must(t).NotNil(conn)

// Generic: package-level function
attest.MustEqual(t, 42, result)
attest.MustErrorAs(t, err, &typedErr)

DeepEqual Options

DeepEqual and NotDeepEqual support functional options:

attest.DeepEqual(t, want, got,
    attest.WithCmpOpts(cmpopts.IgnoreFields(Config{}, "Timestamp")),
    attest.WithMessage("comparing configs for %s", env),
)

Golden File Testing

Compare test output against golden files stored in testdata/golden/:

func TestOutput(t *testing.T) {
    result := generateReport()
    attest.Golden(t, result)
}

Update golden files by running tests with the -attest.update flag:

go test ./... -attest.update

Options: WithPath, WithExtension, WithScrubber.

Documentation

Full API documentation is available via go doc:

go doc github.com/cboone/attest

License

MIT