Guide · Open source

How to use testify: assertions, mocks and suites in Go

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Testify is a Go toolkit of packages that make tests easier to write and read. It provides assertions with clear failure messages, a way to stop a test on failure, mock objects for stand-in dependencies, and a suite structure for grouping related tests. This guide shows how to install it and use each part, so you can write tests that run with the standard go test command.

testifystretchr/testify · ★ 26.2k · MIT Install options & downloads

Quick start

1Install Go. Make sure Go is installed, since testify is a Go library and needs a Go project to run in.
2Add testify to your project. Run go get github.com/stretchr/testify from your project directory.
3Import the assert package. Import github.com/stretchr/testify/assert in your _test.go file and call its functions with the testing.T value.
4Use require for critical checks. Switch to the require package when a failed check should stop the test before later lines run.
5Create a mock for a dependency. Embed mock.Mock in a stand-in type, set expectations with On and Return, and call AssertExpectations at the end.
6Group tests in a suite. Embed suite.Suite in a struct, add SetupTest and Test methods, then run them with go test.

Install testify in your Go project

Testify is a Go-only library, so you need Go installed before you start. Install it with the package command from the project README.

go get github.com/stretchr/testify

Write readable checks with the assert package

The assert package provides helper functions that print friendly, easy-to-read failure descriptions. Every assert function takes the testing.T value as its first argument, which is how it reports errors through normal go test output. You can also add an optional message to any assertion.

Each assert function returns a bool showing whether the check passed. You can use that result to decide whether to keep making assertions under certain conditions. If you make many assertions in one test, you can create an assert object once with assert.New(t) and drop the repeated t argument.

assert.Equal and assert.NotEqual compare values
assert.Nil and assert.NotNil check for nil, which is useful for errors
Pass a final string argument to explain what an assertion should prove

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

Stop a test on failure with the require package

The require package has the same functions as assert, but instead of returning a boolean it ends the current test when a check fails. Use it when later lines depend on the earlier check, such as confirming an error is nil before using a value.

The README notes that require functions must be called from the goroutine running the test or benchmark. Calling them from other goroutines created during the test may cause race conditions.

Create mock objects with the mock package

The mock package helps you write stand-in objects to use in place of real dependencies, such as an external interface your code relies on. Embed mock.Mock in your type, have each method call m.Called, and then set expectations in your test with On and Return.

Use mock.Anything as a placeholder when an argument is generated dynamically and cannot be predicted, such as time-sensitive hashes. Call AssertExpectations at the end of the test to confirm the expected calls happened. Use the Unset method on a call to remove its handler so you can add a new one that takes precedence.

The README also mentions the mockery tool, which can autogenerate mock code from an interface.

On(...).Return(...) sets an expected call and its return values
mock.Anything matches any argument
AssertExpectations(t) checks that expected calls were made
Unset() removes a previously set expectation

testObj := new(MyMockedObject)
testObj.On("DoSomething", 123).Return(true, nil)
targetFuncThatDoesSomethingWithObj(testObj)
testObj.AssertExpectations(t)

The suite package lets you build a test suite as a struct, with setup and teardown methods and test methods on that struct. Embed suite.Suite in your struct, and any method whose name begins with Test runs as a test. Use suite.T() to get the current testing context for assertions.

Suites do not support parallel tests, according to the README (see issue #934). Also, the suite must be run through a normal Go test function, which the README shows as part of its example.

SetupTest runs before each test method in the suite
Methods beginning with Test are run as tests
Run the suite with go test like any other test

type ExampleTestSuite struct {
	suite.Suite
	VariableThatShouldStartAtFive int
}

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

func (suite *ExampleTestSuite) TestExample() {
	assert.Equal(suite.T(), 5, suite.VariableThatShouldStartAtFive)
}

What people use it for

Replacing plain if-and-t.Error checks with readable assert.Equal calls in unit tests
Testing code that calls an external interface by substituting a mock object
Organizing related tests for one component with shared setup in SetupTest
Stopping a test early with require when a nil error would make later assertions panic

Frequently asked questions

How do I install testify in Go?

Run go get github.com/stretchr/testify from your project. The README lists this as the one-line install command, and Go must already be installed.

Is testify free to use?

Yes. Testify is licensed under the MIT license, according to the project's listing.

What is the difference between assert and require in testify?

Both packages provide the same functions. assert returns a boolean and lets the test continue, while require ends the current test when a check fails.

Can I run testify suites in parallel?

No. The README warns that the suite package does not support parallel tests and links to issue #934 for details.

Does testify work with the standard go test command?

Yes. The README says testify plugs into go test, and assertions write their errors through normal go test output.

What are good alternatives to testify?

The project lists gocheck, ginkgo, gomega and goconvey as comparable projects. Choose based on whether you want the standard test style with extra assertions or a different testing style altogether.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Testify suits Go developers who want more readable assertions than the standard library offers, teams that need mock objects for external interfaces, and anyone who wants setup and teardown in grouped tests. Skip it if your project is not in Go, if you need a standalone end-user tool, or if you depend on parallel suite tests, which the README says are not supported.

Install options & downloads