assert

func Assert ¶

func Assert(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{})

Assert performs a comparison. If the comparison fails, the test is marked as failed, a failure message is logged, and execution is stopped immediately.

The comparison argument may be one of three types:

bool
  True is success. False is a failure. The failure message will contain
  the literal source code of the expression.

cmp.Comparison
  Uses cmp.Result.Success() to check for success or failure.
  The comparison is responsible for producing a helpful failure message.
  http://pkg.go.dev/gotest.tools/v3/assert/cmp provides many common comparisons.

error
  A nil value is considered success, and a non-nil error is a failure.
  The return value of error.Error is used as the failure message.

Extra details can be added to the failure message using msgAndArgs. msgAndArgs may be either a single string, or a format string and args that will be passed to fmt.Sprintf.

Assert uses testing.TB.FailNow to fail the test. Like t.FailNow, Assert must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check from other goroutines.

package main

import (
	"fmt"
	"regexp"
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/assert/cmp"
)

var t = &testing.T{}

func main() {
	regexPattern := func(value string, pattern string) cmp.Comparison {
		return func() cmp.Result {
			re := regexp.MustCompile(pattern)
			if re.MatchString(value) {
				return cmp.ResultSuccess
			}
			return cmp.ResultFailure(
				fmt.Sprintf("%q did not match pattern %q", value, pattern))
		}
	}
	assert.Assert(t, regexPattern("12345.34", `\d+.\d\d`))
}

Output:

func Check ¶

func Check(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) bool

Check performs a comparison. If the comparison fails the test is marked as failed, a failure message is printed, and Check returns false. If the comparison is successful Check returns true. Check may be called from any goroutine.

See Assert for details about the comparison arg and failure messages.

func DeepEqual ¶

func DeepEqual(t TestingT, x, y interface{}, opts ...gocmp.Option)

DeepEqual uses github.com/google/go-cmp/cmp to assert two values are equal and fails the test if they are not equal.

Package gotest.tools/v3/assert/opt provides some additional commonly used Options.

DeepEqual uses testing.T.FailNow to fail the test. Like t.FailNow, DeepEqual must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check with cmp.DeepEqual from other goroutines.

func Equal ¶

func Equal(t TestingT, x, y interface{}, msgAndArgs ...interface{})

Equal uses the == operator to assert two values are equal and fails the test if they are not equal.

If the comparison fails Equal will use the variable names and types of x and y as part of the failure message to identify the actual and expected values.

assert.Equal(t, actual, expected)
// main_test.go:41: assertion failed: 1 (actual int) != 21 (expected int32)

If either x or y are a multi-line string the failure message will include a unified diff of the two values. If the values only differ by whitespace the unified diff will be augmented by replacing whitespace characters with visible characters to identify the whitespace difference.

Equal uses testing.T.FailNow to fail the test. Like t.FailNow, Equal must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check with cmp.Equal from other goroutines.

func Error ¶

func Error(t TestingT, err error, expected string, msgAndArgs ...interface{})

Error fails the test if err is nil, or if err.Error is not equal to expected. Both err.Error and expected will be included in the failure message. Error performs an exact match of the error text. Use ErrorContains if only part of the error message is relevant. Use ErrorType or ErrorIs to compare errors by type.

Error uses testing.T.FailNow to fail the test. Like t.FailNow, Error must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check with cmp.Error from other goroutines.

func ErrorContains ¶

func ErrorContains(t TestingT, err error, substring string, msgAndArgs ...interface{})

ErrorContains fails the test if err is nil, or if err.Error does not contain the expected substring. Both err.Error and the expected substring will be included in the failure message.

ErrorContains uses testing.T.FailNow to fail the test. Like t.FailNow, ErrorContains must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check with cmp.ErrorContains from other goroutines.

func ErrorIs ¶ added in v3.1.0

func ErrorIs(t TestingT, err error, expected error, msgAndArgs ...interface{})

ErrorIs fails the test if err is nil, or the error does not match expected when compared using errors.Is. See errors.Is for accepted arguments.

ErrorIs uses testing.T.FailNow to fail the test. Like t.FailNow, ErrorIs must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check with cmp.ErrorIs from other goroutines.

func NilError ¶

func NilError(t TestingT, err error, msgAndArgs ...interface{})

NilError fails the test immediately if err is not nil, and includes err.Error in the failure message.

NilError uses testing.TB.FailNow to fail the test. Like t.FailNow, NilError must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check from other goroutines.