Package: gotest.tools/v3/assert

package assert Import Path gotest.tools/v3/assert (on go.dev) Dependency Relation imports 3 packages, and imported by 0 packages

Involved Source Files #d assert.go Package assert provides assertions for comparing expected values to actual values in tests. When an assertion fails a helpful error message is printed. # Example usage All the assertions in this package use testing.T.Helper to mark themselves as test helpers. This allows the testing package to print the filename and line number of the file function that failed. assert.NilError(t, err) // filename_test.go:212: assertion failed: error is not nil: file not found If any assertion is called from a helper function, make sure to call t.Helper from the helper function so that the filename and line number remain correct. The examples below show assert used with some common types and the failure messages it produces. The filename and line number portion of the failure message is omitted from these examples for brevity. // booleans assert.Assert(t, ok) // assertion failed: ok is false assert.Assert(t, !missing) // assertion failed: missing is true // primitives assert.Equal(t, count, 1) // assertion failed: 0 (count int) != 1 (int) assert.Equal(t, msg, "the message") // assertion failed: my message (msg string) != the message (string) assert.Assert(t, total != 10) // use Assert for NotEqual // assertion failed: total is 10 assert.Assert(t, count > 20, "count=%v", count) // assertion failed: count is <= 20: count=1 // errors assert.NilError(t, closer.Close()) // assertion failed: error is not nil: close /file: errno 11 assert.Error(t, err, "the exact error message") // assertion failed: expected error "the exact error message", got "oops" assert.ErrorContains(t, err, "includes this") // assertion failed: expected error to contain "includes this", got "oops" assert.ErrorIs(t, err, os.ErrNotExist) // assertion failed: error is "oops", not "file does not exist" (os.ErrNotExist) // complex types assert.DeepEqual(t, result, myStruct{Name: "title"}) // assertion failed: ... (diff of the two structs) assert.Assert(t, is.Len(items, 3)) // assertion failed: expected [] (length 0) to have length 3 assert.Assert(t, len(sequence) != 0) // use Assert for NotEmpty // assertion failed: len(sequence) is 0 assert.Assert(t, is.Contains(mapping, "key")) // assertion failed: map[other:1] does not contain key // pointers and interface assert.Assert(t, ref == nil) // assertion failed: ref is not nil assert.Assert(t, ref != nil) // use Assert for NotNil // assertion failed: ref is nil # Assert and Check Assert and Check are very similar, they both accept a Comparison, and fail the test when the comparison fails. The one difference is that Assert uses testing.T.FailNow to fail the test, which will end the test execution immediately. Check uses testing.T.Fail to fail the test, which allows it to return the result of the comparison, then proceed with the rest of the test case. Like testing.T.FailNow, Assert must be called from the goroutine running the test, not from other goroutines created during the test. Check is safe to use from any goroutine. # Comparisons Package http://pkg.go.dev/gotest.tools/v3/assert/cmp provides many common comparisons. Additional comparisons can be written to compare values in other ways. See the example Assert (CustomComparison). # Automated migration from testify gty-migrate-from-testify is a command which translates Go source code from testify assertions to the assertions provided by this package. See http://pkg.go.dev/gotest.tools/v3/assert/cmd/gty-migrate-from-testify.

Code Examples Assert_customComparison 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`)) }

Package-Level Type Names (total 3, in which 2 are exported)

/* sort exporteds by: alphabet | popularity */

type BoolOrComparison (interface) BoolOrComparison can be a bool, cmp.Comparison, or error. See Assert for details about how this type is used. As Inputs Of (at least 2, both are exported) func Assert(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) func Check(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) bool

type TestingT (interface) TestingT is the subset of testing.T used by the assert package. Methods (total 3, all are exported) ( TestingT) Fail() ( TestingT) FailNow() ( TestingT) Log(args ...interface{}) Implemented By (at least 5, in which 4 are exported) *testing.B *testing.F *testing.T testing.TB (interface) /* at least one unexported ... *//* at least one unexported: */ Implements (at least one exported) TestingT : gotest.tools/v3/internal/assert.LogT As Inputs Of (at least 9, all are exported) func Assert(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) func Check(t TestingT, comparison BoolOrComparison, msgAndArgs ...interface{}) bool func DeepEqual(t TestingT, x, y interface{}, opts ...gocmp.Option) func Equal(t TestingT, x, y interface{}, msgAndArgs ...interface{}) func Error(t TestingT, err error, expected string, msgAndArgs ...interface{}) func ErrorContains(t TestingT, err error, substring string, msgAndArgs ...interface{}) func ErrorIs(t TestingT, err error, expected error, msgAndArgs ...interface{}) func ErrorType(t TestingT, err error, expected interface{}, msgAndArgs ...interface{}) func NilError(t TestingT, err error, msgAndArgs ...interface{})

/* one unexported ... *//* one unexported: */

Package-Level Functions (total 9, all are exported)

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 t.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.

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(t TestingT, x, y interface{}, opts ...gocmp.Option) DeepEqual uses google/go-cmp (https://godoc.org/github.com/google/go-cmp/cmp) to assert two values are equal and fails the test if they are not equal. Package http://pkg.go.dev/gotest.tools/v3/assert/opt provides some additional commonly used Options. DeepEqual uses 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(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 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(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 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(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 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(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 https://golang.org/pkg/errors/#Is for accepted arguments. ErrorIs uses 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 ErrorType(t TestingT, err error, expected interface{}, msgAndArgs ...interface{}) ErrorType fails the test if err is nil, or err is not the expected type. Most new code should use ErrorIs instead. ErrorType may be deprecated in the future. Expected can be one of: func(error) bool The function should return true if the error is the expected type. struct{} or *struct{} A struct or a pointer to a struct. The assertion fails if the error is not of the same type. *interface{} A pointer to an interface type. The assertion fails if err does not implement the interface. reflect.Type The assertion fails if err does not implement the reflect.Type. ErrorType uses t.FailNow to fail the test. Like t.FailNow, ErrorType must be called from the goroutine running the test function, not from other goroutines created during the test. Use Check with cmp.ErrorType from other goroutines.

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 t.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.