assert

README

A simple assertion library using Go generics

This library is inspired by testify/require, but with a significantly reduced API surface based on empirical use of that package.

It also provides much nicer diff output, eg.

=== RUN   TestFail
    assert_test.go:14: Expected values to be equal:
         assert.Data{
        -  Str: "foo",
        +  Str: "far",
           Num: 10,
         }
--- FAIL: TestFail (0.00s)

API

Import then use as assert:

import "github.com/alecthomas/assert/v2"

This library has the following API. For all functions, msgAndArgs is used to format error messages using the fmt package.

// Equal asserts that "expected" and "actual" are equal using google/go-cmp.
//
// If they are not, a diff of the Go representation of the values will be displayed.
func Equal[T comparable](t testing.TB, expected, actual T, msgAndArgs ...interface{})

// NotEqual asserts that "expected" is not equal to "actual" using google/go-cmp.
//
// If they are equal the expected value will be displayed.
func NotEqual[T comparable](t testing.TB, expected, actual T, msgAndArgs ...interface{})

// Zero asserts that a value is its zero value.
func Zero[T comparable](t testing.TB, value T, msgAndArgs ...interface{})

// NotZero asserts that a value is not its zero value.
func NotZero[T comparable](t testing.TB, value T, msgAndArgs ...interface{})

// Contains asserts that "haystack" contains "needle".
func Contains(t testing.TB, haystack string, needle string, msgAndArgs ...interface{})

// NotContains asserts that "haystack" does not contain "needle".
func NotContains(t testing.TB, haystack string, needle string, msgAndArgs ...interface{})

// EqualError asserts that either an error is non-nil and that its message is what is expected,
// or that error is nil if the expected message is empty.
func EqualError(t testing.TB, err error, errString string, msgAndArgs...interface{})

// Error asserts that an error is not nil.
func Error(t testing.TB, err error, msgAndArgs ...interface{})

// NoError asserts that an error is nil.
func NoError(t testing.TB, err error, msgAndArgs ...interface{})

// IsError asserts than any error in "err"'s tree matches "target".
func IsError(t testing.TB, err, target error, msgAndArgs ...interface{})

// NotIsError asserts than no error in "err"'s tree matches "target".
func NotIsError(t testing.TB, err, target error, msgAndArgs ...interface{})

// Panics asserts that the given function panics.
func Panics(t testing.TB, fn func(), msgAndArgs ...interface{})

// NotPanics asserts that the given function does not panic.
func NotPanics(t testing.TB, fn func(), msgAndArgs ...interface{})

// Compare two values for equality and return true or false.
func Compare[T any](t testing.TB, x, y T) bool

// True asserts that an expression is true.
func True(t testing.TB, ok bool, msgAndArgs ...interface{})

// False asserts that an expression is false.
func False(t testing.TB, ok bool, msgAndArgs ...interface{})

Evaluation process

Our empircal data of testify usage comes from a monorepo with around 50K lines of tests.

These are the usage counts for all testify functions, normalised to the base (not Printf()) non-negative(not No(t)?) case for each core function.

2240 Error
1314 Equal
 219 True
 210 Nil
 167 Empty
 107 Contains
  79 Len
  61 False
  24 EqualValues
  20 EqualError
  17 Zero
  15 Fail
  15 ElementsMatch
   9 Panics
   7 IsType
   6 FileExists
   4 JSONEq
   3 PanicsWithValue
   3 Eventually

The decision for each function was:

Keep

• Error(t, err) -> frequently used, keep
• Equal(t, expected, actual) -> frequently used, keep but make type safe
• True(t, expr) -> frequently used, keep
• False(t, expr) -> frequently used, keep
• Empty(t, thing) -> require.Equal(t, len(thing), 0)
• Contains(t, haystack string, needle string) - the only variant used in our codebase, keep as concrete type
• Zero(t, value) -> make type safe, keep
• Panics(t, f) -> useful, keep
• EqualError(t, a, b) -> useful, keep
• Nil(t, value) -> frequently used, keep

Not keeping, replace with ...

• ElementsMatch(t, a, b) - use peterrk/slices or stdlib sort support once it lands.
• IsType(t, a, b) -> require.Equal(t, reflect.TypeOf(a).String(), reflect.TypeOf(b).String())
• FileExists() -> very little use, drop
• JSONEq() -> very little use, drop
• PanicsWithValue() -> very little use, drop
• Eventually() -> very little use, drop
• Contains(t, haystack []T, needle T) - very little use, replace with
• Contains(t, haystack map[K]V, needle K) - very little use, drop
• Len(t, v, n) -> cannot be implemented as a single function with genericsEqual(t, len(v), n)
• EqualValues() - Equal(t, TYPE(a), TYPE(b))
• Fail() -> t.Fatal()

Documentation

Overview

Package assert provides type-safe assertions with clean error messages.

Index

• func Compare[T any](t testing.TB, x, y T, options ...CompareOption) bool
• func Contains(t testing.TB, haystack string, needle string, msgAndArgs ...any)
• func Equal[T any](t testing.TB, expected, actual T, msgArgsAndCompareOptions ...any)
• func EqualError(t testing.TB, err error, errString string, msgAndArgs ...any)
• func Error(t testing.TB, err error, msgAndArgs ...any)
• func False(t testing.TB, ok bool, msgAndArgs ...any)
• func HasPrefix(t testing.TB, s, prefix string, msgAndArgs ...any)
• func HasSuffix(t testing.TB, s, suffix string, msgAndArgs ...any)
• func IsError(t testing.TB, err, target error, msgAndArgs ...any)
• func NoError(t testing.TB, err error, msgAndArgs ...any)
• func NotContains(t testing.TB, haystack string, needle string, msgAndArgs ...any)
• func NotEqual[T any](t testing.TB, expected, actual T, msgArgsAndCompareOptions ...any)
• func NotIsError(t testing.TB, err, target error, msgAndArgs ...any)
• func NotPanics(t testing.TB, fn func(), msgAndArgs ...any)
• func NotZero[T any](t testing.TB, value T, msgAndArgs ...any)
• func Panics(t testing.TB, fn func(), msgAndArgs ...any)
• func True(t testing.TB, ok bool, msgAndArgs ...any)
• func Zero[T any](t testing.TB, value T, msgAndArgs ...any)
• type CompareOption
  • func Exclude[T any]() CompareOption
  • func IgnoreGoStringer() CompareOption
  • func OmitEmpty() CompareOption

Functions

func Compare

func Compare[T any](t testing.TB, x, y T, options ...CompareOption) bool

Compare two values for equality and return true or false.

func Contains

func Contains(t testing.TB, haystack string, needle string, msgAndArgs ...any)

Contains asserts that "haystack" contains "needle".

func Equal

func Equal[T any](t testing.TB, expected, actual T, msgArgsAndCompareOptions ...any)

Equal asserts that "expected" and "actual" are equal.

If they are not, a diff of the Go representation of the values will be displayed.

func EqualError

func EqualError(t testing.TB, err error, errString string, msgAndArgs ...any)

EqualError asserts that either an error is non-nil and that its message is what is expected, or that error is nil if the expected message is empty.

func Error

func Error(t testing.TB, err error, msgAndArgs ...any)

Error asserts that an error is not nil.

func False

func False(t testing.TB, ok bool, msgAndArgs ...any)

False asserts that an expression is false.

func HasPrefix

func HasPrefix(t testing.TB, s, prefix string, msgAndArgs ...any)

HasPrefix asserts that the string s starts with prefix.

func HasSuffix

func HasSuffix(t testing.TB, s, suffix string, msgAndArgs ...any)

HasSuffix asserts that the string s ends with suffix.

func IsError

func IsError(t testing.TB, err, target error, msgAndArgs ...any)

IsError asserts than any error in "err"'s tree matches "target".

func NoError

func NoError(t testing.TB, err error, msgAndArgs ...any)

NoError asserts that an error is nil.

func NotContains

func NotContains(t testing.TB, haystack string, needle string, msgAndArgs ...any)

NotContains asserts that "haystack" does not contain "needle".

func NotEqual

func NotEqual[T any](t testing.TB, expected, actual T, msgArgsAndCompareOptions ...any)

NotEqual asserts that "expected" is not equal to "actual".

If they are equal the expected value will be displayed.

func NotIsError

func NotIsError(t testing.TB, err, target error, msgAndArgs ...any)

NotIsError asserts than no error in "err"'s tree matches "target".

func NotPanics

func NotPanics(t testing.TB, fn func(), msgAndArgs ...any)

NotPanics asserts that the given function does not panic.

func NotZero

func NotZero[T any](t testing.TB, value T, msgAndArgs ...any)

NotZero asserts that a value is not its zero value.

func Panics

func Panics(t testing.TB, fn func(), msgAndArgs ...any)

Panics asserts that the given function panics.

func True

func True(t testing.TB, ok bool, msgAndArgs ...any)

True asserts that an expression is true.

func Zero

func Zero[T any](t testing.TB, value T, msgAndArgs ...any)

Zero asserts that a value is its zero value.

Types

type CompareOption

type CompareOption func() []repr.Option

A CompareOption modifies how object comparisons behave.

func Exclude

func Exclude[T any]() CompareOption

Exclude fields of the given type from comparison.

func IgnoreGoStringer

func IgnoreGoStringer() CompareOption

IgnoreGoStringer ignores GoStringer implementations when comparing.

func OmitEmpty

func OmitEmpty() CompareOption

OmitEmpty fields from comparison.