Testify: Go Testing Toolkit with Assert, Require, Mock, and Suite Packages

What Testify Adds to Go's Standard Testing Package

Go's standard testing package provides t.Error(), t.Errorf(), t.Fatal(), and t.Fatalf() for reporting test failures. These functions print whatever message the developer writes but do not produce structured output about what was expected versus what was received. A test that checks whether two values are equal using reflect.DeepEqual must also write a custom message explaining what went wrong.

Testify's assert package replaces this pattern with named assertion functions that automatically produce readable failure descriptions. An assertion like assert.Equal(t, 123, 456) produces output that states the expected value, the actual value, and the file and line number without requiring the developer to write that message manually.

Every assertion function in the assert package takes testing.T as its first argument and returns a bool indicating whether the assertion passed. This means tests continue running after a failed assertion, allowing a single test run to report multiple failures at once. The require package uses the same function signatures but terminates the test immediately on failure rather than continuing.

The difference between assert and require matters for test design. Use assert when a failure is informative but the remaining assertions can still run. Use require when a failed assertion means the subsequent code would panic or produce misleading results, such as when testing that an error is nil before accessing the returned value.

Installing Testify and Writing a First Test

Testify is imported as a Go module. The go.mod file in the repository shows the module path is github.com/stretchr/testify. The README states the library can be installed with one line of code and references an installation section, though the specific command is documented in the linked API documentation at pkg.go.dev/github.com/stretchr/testify.

Once imported, a test using the assert package looks like this:

package yours

import (
	"testing"

	"github.com/stretchr/testify/assert"
)

func TestSomething(t *testing.T) {
	assert.Equal(t, 123, 123, "they should be equal")
	assert.NotEqual(t, 123, 456, "they should not be equal")
	assert.Nil(t, object)
	if assert.NotNil(t, object) {
		assert.Equal(t, "Something", object.Value)
	}
}

The third argument to each assertion is an optional message that appears in the failure output. When a single test calls assert many times, an alternative pattern avoids passing t on every call:

func TestSomething(t *testing.T) {
	assert := assert.New(t)
	assert.Equal(123, 123, "they should be equal")
	assert.NotEqual(123, 456, "they should not be equal")
}

This creates an assert object that holds the testing.T reference internally. The function signatures drop the t parameter, making the test body slightly less verbose. Both styles produce the same output on failure.

The README also mentions testifylint, a linter available via golangci-lint, which catches common mistakes in Testify usage. Adding it to a project's lint configuration helps prevent patterns like using assert.Equal instead of assert.NoError for error checks.

The mock Package: Stubbing Dependencies Without External Codegen

The mock package lets developers create mock objects that implement interfaces and track which methods were called and with which arguments. A mock struct embeds mock.Mock and defines methods that call mock.Called(), which records the call and returns whatever the test configured the mock to return.

The README documents the interface for setting expectations: testObj.On("DoSomething", 123).Return(true, nil) configures the mock to return true and nil when DoSomething is called with the argument 123. After the test runs, testObj.AssertExpectations(t) verifies that all configured expectations were actually called.

For projects with many interfaces, the README mentions mockery as an external tool that can auto-generate the mock struct code against an interface definition. This avoids writing the mock implementation by hand, which is repetitive for interfaces with many methods.

The mock package requires that mock methods are called from the goroutine that owns the test. The README documents this as a constraint shared with the require package: functions that call t.FailNow() (which includes require and the assertion methods on mock structs that verify expectations) must not be called from goroutines spawned during the test.

The suite Package and Its Parallel Test Constraint

The suite package provides a test organization pattern familiar from object-oriented testing frameworks. A test suite is a struct that embeds suite.Suite, and test methods are methods on that struct that begin with the word Test. Setup and teardown logic goes in SetupTest() and TearDownTest() methods rather than at the top of every test function.

A typical suite looks like this:

type ExampleTestSuite struct {
	suite.Suite
	VariableThatShouldStartAtFive int
}

func (suite *ExampleTestSuite) SetupTest() {
	suite.VariableThatShouldStartAtFive = 5
}

Suites are run with the standard go test command through a single entry-point test function that calls suite.Run(t, new(ExampleTestSuite)).

The README includes a warning that the suite package does not support parallel tests, with a reference to issue number 934. This is a meaningful constraint: if a test suite calls t.Parallel() or if individual test methods attempt to run in parallel, the behavior is undefined and tests may produce incorrect results. Teams using the suite package should not mix it with t.Parallel() calls.

The suite.Suite struct exposes assertion methods directly (suite.Equal(), suite.Nil(), etc.) so that test methods do not need to import the assert package separately. These methods delegate to the embedded testing.T.

The require Package and Goroutine Boundary Rules

The require package provides the same assertion functions as the assert package with one difference: instead of returning false on failure, require functions call t.FailNow(), which terminates the test immediately. This is useful when a test cannot meaningfully continue after a specific assertion fails.

The README documents an important constraint: require functions must be called from the goroutine that is running the test or benchmark function. Calling require.Equal() or any other require function from a goroutine spawned inside the test (for example, from a goroutine passed to a background worker) causes a race condition because t.FailNow() is not safe to call from a non-test goroutine.

The same constraint applies to mock assertion methods like AssertExpectations. If a mock's methods are called from background goroutines during the test, the expectation assertions must still be made from the test goroutine after those goroutines have finished.

For concurrent code, the assert package is safer because assert functions return false on failure rather than calling t.FailNow(). The test can collect failures from goroutines and report them after synchronization, rather than calling require from inside the goroutine.

Maintenance at v1, v2 Discussion, and License

The README opens with a note that Testify is maintained at v1 and no breaking changes will be accepted. A link to a GitHub discussion at issue 1560 points to ongoing community conversation about what a v2 release would look like. As of the most recent repository information, v2 had not been released.

The most recent release is v1.12.1, published on 2026-08-19. The release before it, v1.12.0, was published on 2026-08-17. The release cadence for 2026 shows v1.11.1 was published on 2025-08-27, indicating roughly annual minor releases. The last push to the repository was on 2026-09-02.

Testify is released under the MIT license. The go.mod file specifies a minimum Go version of 1.17, meaning it is compatible with older Go toolchains as well as current ones. The repository's module is github.com/stretchr/testify, and each package is imported separately by its subdirectory path: github.com/stretchr/testify/assert, github.com/stretchr/testify/mock, and so on.

The README also lists testifylint as a companion tool. Running testifylint via golangci-lint catches patterns like using assert.Equal(t, err, nil) instead of assert.NoError(t, err), and using assert.Equal for boolean checks instead of assert.True or assert.False. These are not errors but they reduce the quality of failure output.

Editorial conclusion

Go developers who want readable assertion output and a mock framework without leaving the standard testing.T model will find Testify a practical fit. Teams that run parallel tests extensively should read the suite package's documented limitation before using it: the suite package does not support parallel tests, and this is an open issue. The MIT license permits use in any project. The most recent release is v1.12.1, published on 2026-08-19, and the project is maintained at v1 with no planned breaking changes.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stretchr/testify on GitHub