testify and the libraries around it
The standard library gives a test t.Errorf and a comparison the author writes by hand. testify adds assert and require: functions that take t, compare two values and print a readable diff when they differ. It is the most widely used test helper in Go, and the testing lesson showed what it replaces. It is a module, not part of the toolchain, so a project adds it to go.mod and every developer gets it from the module cache.
assert and require
Both packages have the same functions and differ in what happens on failure: assert records the failure and returns false, so the test continues; require records the failure and calls t.FailNow, so the rest of the function does not run. The order of arguments is expected first, actual second, which is the opposite of some other languages and the first thing a reader has to check.
package calc
import (
"errors"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestSum(t *testing.T) {
assert.Equal(t, 6, Sum(1, 2, 3))
assert.Equal(t, 0, Sum(), "an empty sum is zero")
assert.NotEqual(t, 5, Sum(1, 2))
}
func TestRequireStops(t *testing.T) {
got := Sum(1, 2)
require.Equal(t, 3, got, "the rest of this test needs the sum")
assert.Positive(t, got)
}
func TestErrorHelpers(t *testing.T) {
err := errors.New("boom")
assert.Error(t, err)
assert.NoError(t, error(nil))
assert.ErrorContains(t, err, "boom")
}
go test -v .
=== RUN TestSum
--- PASS: TestSum (0.00s)
=== RUN TestRequireStops
--- PASS: TestRequireStops (0.00s)
=== RUN TestErrorHelpers
--- PASS: TestErrorHelpers (0.00s)
PASS
ok example.com/calc 0.005s
The three tests passed, and the failure messages would have named the values and the line. require.Equal in the middle test is there because the next assertion is meaningless when the sum is wrong, while the assert.Positive after it can still say something useful. That split is the usual reason to import both packages.
What a failure looks like
A failing assert.Equal prints a diff with the expected and actual values, the file and line and the test name; require prints the same and stops. The output is longer than a hand-written message and it is uniform across a project, which is what a large codebase wants from a helper library.
package calc
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestFailureStyle(t *testing.T) {
assert.Equal(t, 6, Sum(1, 2, 4), "the sum of three numbers")
require.Equal(t, 10, Sum(1, 2), "this stops the test")
t.Log("this line does not run")
}
func TestSecondStillRuns(t *testing.T) {
assert.Greater(t, Sum(2, 2), 3)
}
go test -v .
=== RUN TestFailureStyle
style_test.go:11:
Error Trace: style_test.go:11
Error: Not equal:
expected: 6
actual : 7
Test: TestFailureStyle
Messages: the sum of three numbers
style_test.go:13:
Error Trace: style_test.go:13
Error: Not equal:
expected: 10
actual : 3
Test: TestFailureStyle
Messages: this stops the test
--- FAIL: TestFailureStyle (0.00s)
=== RUN TestSecondStillRuns
--- PASS: TestSecondStillRuns (0.00s)
FAIL
FAIL example.com/calc 0.008s
FAIL
The first test failed at the equality and then stopped at the require, so its t.Log line never ran; the second test still ran and passed, because assert does not end the test. A run that stops the whole package at the first failure needs -failfast, which is a separate switch.
Suites and mocks
The suite package groups tests into a struct with SetupTest and TearDownTest hooks, which is useful when every test needs the same fixture. The mock package records expectations on a generated double; the mocks lesson shows the hand-written form and where the generated one fits. Neither package is required to write good tests: a project that uses only the standard library is not worse, only more explicit.
package calc
import (
"testing"
"github.com/stretchr/testify/suite"
)
type StoreSuite struct {
suite.Suite
store *Store
}
func (s *StoreSuite) SetupTest() {
s.store = &Store{}
}
func (s *StoreSuite) TestAdd() {
s.store.Add(1)
s.Require().Len(s.store.items, 1)
}
func (s *StoreSuite) TestEmpty() {
s.Empty(s.store.items)
}
func TestStoreSuite(t *testing.T) {
suite.Run(t, new(StoreSuite))
}
go test -v .
=== RUN TestStoreSuite
=== RUN TestStoreSuite/TestAdd
=== RUN TestStoreSuite/TestEmpty
--- PASS: TestStoreSuite (0.00s)
--- PASS: TestStoreSuite/TestAdd (0.00s)
--- PASS: TestStoreSuite/TestEmpty (0.00s)
PASS
ok example.com/calc 0.006s
The runner called SetupTest before each method and each method's name inside the suite is reported under TestStoreSuite. The setup runs before every test method, which is what keeps one test from seeing another test's state, and a failing method does not stop the rest of the suite.
testify or the standard library
A project that already uses testify should keep using it consistently; a small project can stay with the standard library and lose nothing but a few lines per test. The arguments for testify are the diff output, the one-line assertions and the habit of an ecosystem; the arguments against are an extra dependency in the build, a second way to write the same check, and helpers that hide which assertions stop a test.
Exercises
- Take the table test from the previous lesson and rewrite its assertions with testify. How many lines does the comparison lose?
- Write a suite with a shared temporary directory created in SetupTest and removed in TearDownTest, and two test methods that use it.
- Find a project on your machine that imports testify and count how often require stops a test compared with assert. Is the split deliberate?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is the argument order of assert.Equal?
Answer
Expected first, actual second
The expected value comes first in testify, as in most Go assertion helpers.
-
What does require do when an assertion fails?
Answer
Records the failure and stops the test
require calls t.FailNow, so the rest of the function does not run.
-
What does assert return?
Answer
A bool that says whether the assertion held
The bool lets a test branch without repeating the comparison.
-
Which package does testify add for assertions without stopping?
Answer
assert
require stops; assert continues and the test can report more.
-
What does a failing assert.Equal print?
Answer
The expected and actual values with the file, line and test name
The diff and the position are the reason to use the helper.
-
Where does testify come from?
Answer
A module in go.mod, not the standard library
It is github.com/stretchr/testify, downloaded and pinned like any dependency.
-
What does the suite package add?
Answer
Setup and teardown hooks around a group of tests in a struct
suite.Run calls SetupTest and TearDownTest around every test method.
-
What does a test that uses assert do after a failed comparison?
Answer
Keeps running and may report more failures
assert records and returns false; the test decides whether to continue.
-
Which is NOT a reason to choose testify?
Answer
It removes the need for a test file per package
Test files and packages are unchanged by the library.
-
What does go test -failfast change?
Answer
The package stops at the first failing test
It is a runner switch, separate from assert and require.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev