# Golang Stretchr Testify

> Write or review Go tests using `github.com/stretchr/testify`. Covers assert versus require, wrapped-error and structural assertions, eventual checks, mock expectations and matchers, suite lifecycle, and test isolation; use the standard testing package directly when Testify is absent and simple checks suffice.

- Skill: `reagin/golang-stretchr-testify` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add reagin/golang-stretchr-testify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reagin/golang-stretchr-testify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: reagin (https://skillmd.com/u/reagin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/reagin/golang-stretchr-testify

---


# Testify in Go tests

Keep Go's `testing` package as the test runner and match the repository's existing assertion style. Use Testify where its diagnostics, suites, or mocks improve the test; a direct `if` remains appropriate when clearer.

## Inspect before editing

Check `go.mod`, package-level assertion conventions, helper functions, mock-generation or hand-written mock patterns, suite usage, parallel tests, and linters such as `testifylint`. Verify APIs against the selected version before adopting newer assertions or mock helpers.

## Assertions and requirements

- Use `require` for a failed precondition after which continuing would panic or make later results meaningless.
- Use `assert` when independent checks can still provide useful diagnostics after one fails.
- Keep expected and actual argument order correct for assertions that distinguish them.
- Use `ErrorIs`/`ErrorAs` for wrapped errors when identity or type matters; compare text only when text is the contract.
- Testify equality assertions perform value-oriented comparison for supported values, including pointed-to data. Use identity-specific assertions when pointer identity itself is the behavior.

`require` ultimately calls `FailNow`, so call it from the goroutine running the test rather than an asynchronous worker. Communicate worker failures back to that goroutine. Make callbacks used by eventual assertions concurrency-safe and give them meaningful time bounds.

For concrete assertion selection, eventual checks, mock implementations and matchers, and suite hooks, read [references/api-and-testing.md](references/api-and-testing.md).

Choose assertions that describe the contract directly. A helper or custom assertion is worthwhile when it improves repeated failure diagnostics, not merely to hide setup or compress a one-line standard-library check.

Use `t.Helper` in local wrappers so failures point to the caller rather than the assertion utility.

## Mocks

Mock a meaningful interaction boundary, not internal implementation details that make refactoring unnecessarily expensive. Prefer a small fake when it expresses stateful behavior more clearly.

When using `testify/mock`:

- match arguments narrowly enough to verify behavior without depending on irrelevant representation;
- declare call counts only when count is part of the contract;
- return values with the exact types and nil behavior expected by the mocked method;
- verify expectations using the pattern supported by the selected version and repository;
- treat call ordering as unspecified unless the test explicitly configures and requires it;
- avoid sharing mutable mock state across parallel tests without synchronization.

A broad `Anything` matcher can hide a missing contract. A mock panic often indicates an expectation or return-type mismatch worth diagnosing.

## Suites and test isolation

Create fresh state for each test and release resources with `t.Cleanup` or suite teardown. Confirm the selected version and shared-state safety before running suite methods in parallel. Ensure every suite has a normal `TestXxx` entry point that calls `suite.Run`.

## Verification

Run formatting, the affected tests, race detection when concurrency changed, and configured linters. Confirm failing-path diagnostics are useful: intentionally broken expectations should fail for the behavior being tested, not due to setup panic or leaked state.

## Official references

- [Testify package documentation](https://pkg.go.dev/github.com/stretchr/testify)
- [Testify repository](https://github.com/stretchr/testify)