alecthomas / assert

A simple assertion library using Go generics

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()

assert's Issues

fail to equal time.Time

Given two times that are equal using their .Equal() method, they fail using assert.Equal().

Proposed solution

Instead of using reflect.DeepEqual(), first check if we are asserting times, and then use their .Equal() method.

Make`assert.Zero` harder to misuse

Firstly, thank you for this excellent library! I'm slowly migrating my projects from stretchr/testify to alecthomas/assert.

What's wrong with this code?

    assert.Zero(t, 0, len(foo), "foo should have length zero")

Spoiler alert: this test always passes, no matter how big len(foo) is.

Is there a way to make this API harder to misuse?

Package test fail

• go test github.com/alecthomas/assert/

github.com/alecthomas/assert

../../BUILDROOT/golang-github-alecthomas-assert-0-0.1.20170911git561411b.el7.centos.x86_64/usr/share/gocode/src/github.com/alecthomas/assert/assertions.go:311: not enough arguments in call to repr.OmitEmpty
../../BUILDROOT/golang-github-alecthomas-assert-0-0.1.20170911git561411b.el7.centos.x86_64/usr/share/gocode/src/github.com/alecthomas/assert/assertions.go:458: not enough arguments in call to repr.OmitEmpty
../../BUILDROOT/golang-github-alecthomas-assert-0-0.1.20170911git561411b.el7.centos.x86_64/usr/share/gocode/src/github.com/alecthomas/assert/diff.go:15: not enough arguments in call to repr.OmitEmpty
../../BUILDROOT/golang-github-alecthomas-assert-0-0.1.20170911git561411b.el7.centos.x86_64/usr/share/gocode/src/github.com/alecthomas/assert/diff.go:16: not enough arguments in call to repr.OmitEmpty

Installed:
golang.x86_64 0:1.7.4-1.el7
golang-github-alecthomas-colour-devel.x86_64 0:0-0.3.20170912git60882d9.el7.centos
golang-github-alecthomas-repr-devel.x86_64 0:0-0.1.20170912gitcf65cb4.el7.centos
golang-github-sergi-go-diff-devel.x86_64 0:0-0.2.20170911gitfeef008.el7.centos

Dependency Installed:
golang-bin.x86_64 0:1.7.4-1.el7 golang-github-mattn-go-isatty-devel.x86_64 0:0.0.2-1.el7.centos golang-src.noarch 0:1.7.4-1.el7

assert.True and assert.False should print the given msgAndArgs

My code:

assert.True(t, req.Tariff.PercentPerScheme.Other == nil, "other percent should be nil")

Expected output:

mapping_test.go:60: other percent should be nil

Actual output:

mapping_test.go:60: Expected expression to be true

Area of code that would need changing:

// True asserts that an expression is true.
func True(t testing.TB, ok bool, msgAndArgs ...interface{}) {
	if ok {
		return
	}
	t.Helper()
	t.Fatal("Expected expression to be true")
}

// False asserts that an expression is false.
func False(t testing.TB, ok bool, msgAndArgs ...interface{}) {
	if !ok {
		return
	}
	t.Helper()
	t.Fatal("Expected expression to be false")
}

Happy to submit a PR in a little bit

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update dependency go to v1.22.4
• chore(deps): update actions/checkout action to v4

Detected dependencies

github-actions

.github/workflows/ci.yml

• actions/checkout v2
• actions/checkout v2

gomod

go.mod

• go 1.18
• github.com/alecthomas/repr v0.4.0
• github.com/hexops/gotextdiff v1.0.3

hermit

bin/hermit

• go 1.22.3

---

• Check this box to trigger a request for Renovate to run again on this repository

Crash with checks on large protocol buffers

I just updated to the latest version of assert and it seems to be causing havoc on our CI/CD system. The problem is that we have several checks on large protocol buffers. The private state member is then rendered through the repr reflection system and it can be hundreds of thousands (millions?) of lines.

• Did the default behavior of printing private members change recently?
• Is there some way that I can globally disable showing private members in the assert library without having to pass extra arguments to every assert call?

assert.Equal: "No newline at end of file" can be misleading

hello,
consider a test comparing two strings that _do not end with a newline:

func TestNoNewline(t *testing.T) {
	want := "banana"
	have := "mango"
	assert.Equal(t, want, have)
}

the output will be:

    foo_test.go:156: Expected values to be equal:
        -banana
        \ No newline at end of file
        +mango
        \ No newline at end of file

which is quite confusing: sure, there is no newline at the end of the "file", but it is on purpose :-)

I would expect simply:

    foo_test.go:156: Expected values to be equal:
        -banana
        +mango

If I change diff() as follows:

diff --git a/assert.go b/assert.go
index d2df971a5f..1692e38afd 100644
--- a/assert.go
+++ b/assert.go
@@ -194,8 +194,8 @@ func diff[T any](lhs, rhs T) string {
    var lhss, rhss string
    // Special case strings so we get nice diffs.
    if l, ok := any(lhs).(string); ok {
-       lhss = l
-       rhss = any(rhs).(string)
+       lhss = l + "\n"
+       rhss = any(rhs).(string) + "\n"
    } else {
        lhss = repr.String(lhs, repr.Indent("  ")) + "\n"
        rhss = repr.String(rhs, repr.Indent("  ")) + "\n"

I get the following 4 cases, which seem reasonable to me:

Case 1

func TestNoNewline(t *testing.T) {
	want := "banana"
	have := "mango"
	assert.Equal(t, want, have)
}

gives:

    marco_test.go:12: Expected values to be equal:
        -banana
        +mango
--- FAIL: TestNoNewline (0.00s)

Case 2

func TestWithNewline1(t *testing.T) {
	want := "banana\n"
	have := "mango"
	assert.Equal(t, want, have)
}

gives:

    marco_test.go:18: Expected values to be equal:
        -banana
        -
        +mango
--- FAIL: TestWithNewline1 (0.00s)

Case 3

func TestWithNewline2(t *testing.T) {
	want := "banana"
	have := "mango\n"
	assert.Equal(t, want, have)
}

gives

    marco_test.go:24: Expected values to be equal:
        -banana
        +mango
        +
--- FAIL: TestWithNewline2 (0.00s)

Case 4

func TestWithNewline(t *testing.T) {
	want := "banana\n"
	have := "mango\n"
	assert.Equal(t, want, have)
}

gives:

    marco_test.go:18: Expected values to be equal:
        -banana
        +mango
                                        <-- blank like, but doesn't seem to be a problem
--- FAIL: TestWithNewline (0.00s)

If you see value, I will be happy to provide a PR.

Colored diffs on test failures

Hello,

Is there an option to see colored diffs when a test fails? I didn't notice one when looking at the code.

If not, would you accept a PR to add colors to diffs?

Comparing zero length byte array fails

This currently fails:

assert.Equal(t, []byte(""), []byte(nil))

Consider using bytes.Equal, or special casing length zero.