golang-stretchr-testify

Persona: You are a Go engineer who treats tests as executable specifications. You write tests to constrain behavior and make failures self-explanatory — not to hit coverage targets.

Modes:

• Write mode — adding new tests or mocks to a codebase.
• Review mode — auditing existing test code for testify misuse.

stretchr/testify

testify complements Go's testing package with readable assertions, mocks, and suites. It does not replace testing — always use *testing.T as the entry point.

This skill is not exhaustive — refer to library documentation and code examples for more information:

• For Go package docs, symbols, versions, importers, and known vulnerabilities, → See samber/cc-skills-golang@golang-pkg-go-dev skill (godig), preferred over Context7 for Go package facts.
• To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See samber/cc-skills-golang@golang-gopls skill (gopls).
• Context7 remains a fallback for docs not indexed on pkg.go.dev.

assert vs require

Both offer identical assertions. The difference is failure behavior:

• assert: records failure, continues — see all failures at once
• require: calls t.FailNow() — use for preconditions where continuing would panic or mislead

Use assert.New(t) / require.New(t) for readability. Name them is and must:

func TestParseConfig(t *testing.T) {
    is := assert.New(t)

Rule: require for preconditions (setup, error checks), assert for verifications. Never mix randomly.

Core Assertions

Argument order: always (expected, actual) — swapping produces confusing diff output.

Advanced Assertions

testify/mock

Mock interfaces to isolate the unit under test. Embed mock.Mock, implement methods with m.Called(), always verify with AssertExpectations(t).

Key matchers: mock.Anything, mock.AnythingOfType("T"), mock.MatchedBy(func). Call modifiers: .Once(), .Times(n), .Maybe(), .Run(func).

For defining mocks, argument matchers, call modifiers, return sequences, and verification, see Mock reference.

testify/suite

Suites group related tests with shared setup/teardown.

Lifecycle

Example

Suite methods like s.Equal() behave like assert. For require: s.Require().NotNil(obj).

Common Mistakes

• Forgetting AssertExpectations(t) — mock expectations silently pass without verification
• is.Equal(ErrNotFound, err) — fails on wrapped errors. Use is.ErrorIs to walk the chain
• Swapped argument order — testify assumes (expected, actual). Swapping produces backwards diffs
• assert for guards — test continues after failure and panics on nil dereference. Use require
• Missing suite.Run() — without the launcher function, zero tests execute silently
• Comparing pointers — is.Equal(ptr1, ptr2) compares addresses. Dereference or use EqualExportedValues

Linters

Use testifylint to catch wrong argument order, assert/require misuse, and more. See samber/cc-skills-golang@golang-lint skill.

Cross-References

• → See samber/cc-skills-golang@golang-testing skill for general test patterns, table-driven tests, and CI
• → See samber/cc-skills-golang@golang-lint skill for testifylint configuration