Testify: assertions and mocks for Go testing
Testify turns testing.T's manual comparisons into one-line assert and require calls, and its mock package saves you from hand-writing mock structs for every interface you touch. It earns its place in nearly any Go project past a handful of tests. The catch: this repo stays frozen at v1, so expect fixes and compatibility work, not new features.
What is Testify?
Testify is a Go toolkit that bundles common assertions and mock objects, built to work alongside the standard testing package rather than replace it. It ships as separate packages — assert, require, mock, and suite — imported individually based on what a given test file needs. assert returns a bool and lets a test keep running after a failed check, while require stops it immediately through t.FailNow.
What packages does Testify provide?
- ✓assert package — one-line comparison assertions (Equal, Nil, NotNil, and more) that print readable failure messages and return a bool instead of stopping the test.
- ✓require package — the same assertion functions as assert, but each one calls t.FailNow on failure so the test halts right there; must be called from the test's own goroutine.
- ✓mock package — build mock objects by embedding mock.Mock, declare expectations with On/Return, and verify them afterward with AssertExpectations.
- ✓suite package — group related tests as a struct with SetupTest-style hooks, run through go test via suite.Run; it does not support parallel tests.
- ✓Assertion-object mode — wrap the testing.T once with assert.New(t) or require.New(t) so you can drop the t argument on every subsequent call.
- ✓testify/http package — included in the module but marked deprecated in the README.
When to reach for Testify
- •Writing Go tests where you want readable pass/fail output instead of raw testing.T comparisons and manual t.Errorf messages.
- •Testing code that depends on an interface (an HTTP client, a repository) you'd rather mock than call for real in a unit test.
- •Grouping related tests into a suite with shared setup, when a struct-based structure fits the test file better than plain functions.
- •Enforcing fail-fast checks with require for preconditions where continuing the test after a failed assertion wouldn't make sense.
Installing Testify
Run go get github.com/stretchr/testify to add Testify to your module. That single install makes github.com/stretchr/testify/assert, /require, /mock, /suite, and the deprecated /http package all available — import only the ones a given test file uses. To move to the latest release later, run go get -u github.com/stretchr/testify. The README states Testify supports the most recent major Go versions from 1.19 onward.
Writing tests with assertions
A typical test imports github.com/stretchr/testify/assert and calls functions like assert.Equal(t, want, got, "message") or assert.NotNil(t, object) directly inside a normal func TestX(t *testing.T) body. If a test file makes many assertions, wrapping the testing.T once with a := assert.New(t) lets you drop the t argument on every later call. For mocks, embed mock.Mock in a struct, implement the interface method by calling m.Called(args...) and reading back args.Bool(0) or args.Error(1), then set expectations elsewhere with testObj.On("MethodName", value).Return(returnValue) and check them with testObj.AssertExpectations(t). Suites look different again: define a struct that embeds suite.Suite, add a SetupTest method for per-test setup, write test methods prefixed with Test, and hand the whole thing to suite.Run(t, new(YourSuite)) from one ordinary go test function.
Strengths
- ✓assert/require cut test code down to single-line calls with consistent, readable failure output instead of hand-rolled if/t.Errorf blocks.
- ✓The mock package handles expectation tracking (On, Return, AssertExpectations) so you don't reimplement that bookkeeping for every mocked interface.
- ✓v1 is explicitly frozen against breaking changes, so upgrading within the same import path won't break an existing test suite.
- ✓Four packages — assert, require, mock, suite — cover comparisons, fail-fast checks, mocking, and struct-based suites without pulling in separate libraries for each.
Known limitations
- △The suite package doesn't support parallel tests — the README links directly to open issue #934 on this.
- △Testify is being maintained at v1 only; the README says no breaking changes will be accepted in this repo, so anything you'd want from a v2 stays confined to a GitHub discussion for now.
- △require functions are to be invoked by the goroutine running the test or benchmark itself — calling them from another goroutine can produce race conditions, per the README.
- △The bundled http package is marked deprecated in the README, so new projects shouldn't build on it.
Alternatives to consider
Frequently asked questions
Testify supports the most recent major Go versions starting from Go 1.19 onward, per the README's supported-versions section. In practice that means running on a fairly recent, actively updated Go toolchain rather than an old one keeps your project covered going forward.
Testify's assert package returns a bool and lets a test keep running after a failed check, so you can chain further assertions safely. require calls the same style of assertions but immediately stops the test via t.FailNow the moment one fails, instead of continuing on.
Testify's suite package does not support parallel tests, which matters if your test suite leans on t.Parallel() for speed. The README flags this directly with a warning and links to open GitHub issue #934, where the limitation is tracked and discussed.
Testify is maintained, but deliberately kept at v1 — the README states no breaking changes will be accepted in this repo. That means updates focus on fixes, compatibility, and generated-code upkeep rather than shipping new features or a new major version.
Testify is licensed under the MIT license, which permits commercial use, modification, and redistribution of the code, as long as the license text is included with any copies you distribute or ship inside your own commercial Go project, whether used internally or sold to customers.
Testify v2 hasn't shipped yet. The README points to GitHub discussion #1560 about it, and until that discussion resolves into an actual release, the v1 packages already in this repo are what you install, import, and build your tests on.
The problem it solves
Plain Go testing.T gives you Errorf and Fatalf, but every comparison you write by hand turns into a repetitive if-block with a manually formatted failure message, and there's no built-in way to describe expected calls on a dependency you're not ready to run for real. Testify closes both gaps. assert and require turn common checks into single function calls with consistent output, and the mock package gives you a way to declare what a fake dependency should return without writing a bespoke struct for every interface you test against.
Who should try it — and who should skip
Any Go developer writing more than a handful of tests should add Testify — the assert/require packages pay for themselves the first time you compare two structs by hand. Teams that lean on mocked dependencies benefit most, since the mock package removes a lot of repetitive boilerplate. Skip it, or use it sparingly, if you specifically want parallel subtests organized through suite — that package doesn't support t.Parallel(), so a suite-heavy test file can't use Go's parallel test runner. Anyone hoping for v2 features shouldn't wait around either; this repo is staying at v1.
Related repositories
Want a second opinion on testify?
Ask an AI that can read this page — one click and you get its take on testify.
