README
¶
Assert
An assertion package with a minimal API, yet powerful enough to cover most use cases.
The assert package is designed to provide a more configurable and type-safe alternative to the popular testify/assert package.
Motivation
Have you ever struggled with comparing complex structs in your tests? One that use decimal.Decimal, time.Time, or uuid.UUID types? Or perhaps you wanted to ignore automatically generated fields, such as ID or CreatedAt, in your struct comparisons?
assert allows for more flexible assertions, such as ignoring unexported fields or skipping empty fields in struct comparisons.
Usage
package main
import (
"errors"
"fmt"
"io"
"io/fs"
"testing"
"github.com/krhubert/assert"
)
func TestXYZ(t *testing.T) {
// assert checks if value implements Equal() bool method
// and uses it to compare values. This makes it possible
// to compare e.g. time.Time values.
now := time.Now()
assert.Equal(t, now, now)
// assert is type safe, so this will not compile
// assert.Equal(t, 1, "1")
// assert do not compare pointers, but values they point to
a, b := 1, 1
assert.Equal(t, &a, &b)
// assert checks for errors
assert.Error(t, errors.New("error"))
assert.NoError(t, nil)
// assert checks if error contains a target value
// like string, error or struct
err := fmt.Errorf(
"closed socket: %w %w",
io.EOF,
&fs.PathError{Op: "read", Path: "socket", Err: io.ErrClosedPipe},
)
assert.ErrorContains(t, err, "closed socket")
assert.ErrorContains(t, err, io.EOF)
var pathError *fs.PathError
assert.ErrorContains(atb, err, &pathError)
// assert checks if function panics or not
assert.Panic(t, func() { panic(0) })
assert.NotPanic(t, func() { })
// assert can be used to check errors in defer functions
defer assert.Defer(t, func() error { return file.Close() })()
// assert can be used to check if a value is of a specific type
gs := TypeAssert[fmt.GoStringer](t, time.Time{})
}
Suite
package main
import (
"errors"
"fmt"
"io"
"io/fs"
"testing"
_ "github.com/mattn/go-sqlite3"
"go.uber.org/mock/gomock"
"github.com/krhubert/assert"
)
type ExampleTestSuite struct {
assert.Suite
i int
ctrl *gomock.Controller
db *sql.DB
}
func (s *ExampleTestSuite) Setup(t *testing.T) {
s.i = 4
s.ctrl = gomock.NewController(t)
db, err := sql.Open("sqlite3", ":memory:")
assert.NoError(t, err)
s.db = db
}
func (s *ExampleTestSuite) Teardown(t *testing.T) {
s.i = 0
assert.NoError(t, s.db.Close())
}
func TestExample(t *testing.T) {
ts := assert.Setup[ExampleTestSuite](t)
row := ts.db.QueryRow("select date()")
var date string
assert.NoError(ts, row.Scan(&date))
assert.NoError(ts, row.Err())
}
Assert vs testify
package assert
import (
"testing"
"time"
"github.com/google/uuid"
"github.com/shopspring/decimal"
"github.com/stretchr/testify/require"
)
func TestExampleEqual(t *testing.T) {
type User struct {
Id uuid.UUID
Email string
CreatedAt time.Time
Balance decimal.Decimal
active bool
}
loc, _ := time.LoadLocation("Europe/Warsaw")
// db.CreateUser("test@example.com")
createdAt := time.Now()
user := User{
Id: uuid.New(),
Email: "test@example.com",
CreatedAt: createdAt,
Balance: decimal.NewFromFloat(1),
active: true,
}
want := User{
Email: "test@example.com",
CreatedAt: createdAt.In(loc),
Balance: decimal.RequireFromString("1"),
}
}
Running go test on:
| Assert | Testify |
|---|---|
|
|
Documentation
¶
Overview ¶
Copyright 2017, The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
Index ¶
- func Defer(t testing.TB, fn func() error) func()
- func Empty(t testing.TB, got any)
- func Equal[V any](t testing.TB, got V, want V, opts ...EqualOption)
- func Error(t testing.TB, err error)
- func ErrorContains(t testing.TB, err error, target any)
- func ErrorWant(t testing.TB, want bool, err error)
- func False(t testing.TB, got bool)
- func Len[V any](t testing.TB, got V, want int)
- func Must[P1 any](p1 P1, err error) P1
- func Must2[P1 any, P2 any](p1 P1, p2 P2, err error) (P1, P2)
- func Must3[P1 any, P2 any, P3 any](p1 P1, p2 P2, p3 P3, err error) (P1, P2, P3)
- func Nil(t testing.TB, got any)
- func NoError(t testing.TB, err error)
- func NotEmpty(t testing.TB, got any)
- func NotEqual[V any](t testing.TB, got V, want V, opts ...EqualOption)
- func NotNil(t testing.TB, got any)
- func NotPanic(t testing.TB, f func())
- func NotZero[T any](t testing.TB, got T)
- func Panic(t testing.TB, f func())
- func Setup[V any, S interface{ ... }](t *testing.T) S
- func True(t testing.TB, got bool)
- func TypeAssert[V any](t testing.TB, got any) V
- func Zero[T any](t testing.TB, got T)
- type EqualOption
- type Suite
- type Suiter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Equal ¶
func Equal[V any](t testing.TB, got V, want V, opts ...EqualOption)
Equal checks if two values are equal with the given options.
This functions uses [go-cmp](https://pkg.go.dev/github.com/google/go-cmp) to determine equality.
func ErrorContains ¶
ErrorContains checks if an error is not nil and contains the target.
Target can be:
1. string
The string is compiled as a regexp, and the error is matched against it. If it is not a valid regexp, it is used as a string to check if the error contains it.
2. error
The error is checked if it is equal to the target using errors.Is.
3. type
The error is checked if it can be converted to the target type using errors.As.
func ErrorWant ¶
ErrorWant checks if an error is expected for the test. A common usage in tests is:
type tests struct {
name string
// other fields
wantErr bool
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := fn()
assert.ErrorWant(t, tt.wantErr, err)
})
}
func Len ¶
Len checks if the length of got is l. got can be any go type accepted by builtin len function.
func NotEqual ¶
func NotEqual[V any](t testing.TB, got V, want V, opts ...EqualOption)
NotEqual checks if two values are not equal. See Equal for rules used to determine equality.
func NotZero ¶
NotZero checks if got is not zero value. If value implements IsZero() bool method, it will be used to determine if the value is zero.
func Setup ¶
Setup allocates, initializes, and returns a test suite of type S.
It performs the following steps:
- Allocates a new instance of the suite (S)
- Calls the suite's Setup(t *testing.T) method.
- Registers the suite's Teardown method using t.Cleanup.
This ensures that test lifecycle hooks are consistently applied and automatically cleaned up, even on test failures.
func TypeAssert ¶
TypeAssert checks if got is of type V and returns it.
Types ¶
type EqualOption ¶
type EqualOption func(o *equaler)
EqualOption configures the equality check behavior.
func IgnoreUnexported ¶
func IgnoreUnexported() EqualOption
IgnoreUnexported returns an EqualOption that ignores unexported fields of structs.
func SkipEmptyFields ¶
func SkipEmptyFields() EqualOption
SkipEmptyFields returns an EqualOption that ignores struct fields that are empty. see Empty for details on how empty is determined.
func SkipFieldNames ¶
func SkipFieldNames(names ...string) EqualOption
SkipFieldNames returns an EqualOption that ignores a specific field names in the struct.
The name may be a dot-delimited string (e.g., "Foo.Bar") to ignore a specific sub-field that is embedded or nested within the parent struct.
This option can be only used for structs, otherwise it will panic.
func SkipZeroFields ¶
func SkipZeroFields() EqualOption
SkipZeroFields returns an EqualOption that ignores struct fields that are zero. see Zero for details on how zero is determined.
type Suite ¶
type Suite struct{}
Suite is a noop implementation of a test suite.
It provides Setup and Teardown methods that can be overridden by specific test suites. This struct is designed to be embedded in custom test suite types, allowing you to inherit the basic suite behavior and override only the methods you need.
Suite can be used if you don't want to define both Setup and Teardown methods in your test suite - you can embed Suite and override only the methods you actually need.
Example:
type DatabaseTestSuite struct {
assert.Suite // Embed to inherit noop implementations
db *sql.DB
}
// Only override Setup, Teardown inherited as noop
func (s *DatabaseTestSuite) Setup(t *testing.T) {
s.db = setupTestDB(t)
}
type Suiter ¶
type Suiter interface {
// Setup initializes the test suite before a test runs.
// It receives a *testing.T which can be used for logging, assertions,
// or controlling test execution (e.g., t.Skip(), t.Fatal()).
Setup(t *testing.T)
// Teardown cleans up the test suite after a test completes.
// It receives a *testing.T which can be used for logging cleanup
// operations or reporting cleanup failures.
Teardown(t *testing.T)
}
Suiter defines the interface that all test suites must implement.
This interface establishes the contract for test suite lifecycle management, providing hooks for initialization and cleanup operations. Any type that implements these two methods can be used as a test suite with the Setup function.
Source Files