Skip to content

Test Helpers — Senior

← Back

A senior treatment of test helpers is not about adding more helpers. It is about deciding which helpers belong in a project, how they compose without turning into a framework, and how the testing strategy changes when a suite crosses thousands of tests. This tier covers t.Helper internals, parallel test interactions, property-based testing through testing/quick.Check, helper testing at depth, custom cmp.Option design, and a sober comparison between hand-rolled helpers and testify.

The audience for this page has already written a few internal/testutil packages, has felt the pain of helpers that grew too large, and is ready to think about helpers as a part of the test architecture rather than a convenience. The goal is not to add more techniques to your toolbox; it is to understand the techniques you already use well enough to apply them with judgement.

What t.Helper actually does

The Go runtime maintains, per test, a map of program counters that have been declared as helper frames. When a test calls t.Helper, the testing package records the program counter of the immediate caller. When the test later calls t.Errorf, t.Fatalf, or any other reporting method, the package calls runtime.Callers to walk the goroutine stack, then skips frames whose program counters are in the map until it finds one that is not. The first unmarked frame is the file:line pair printed beside the failure message.

This explains why t.Helper must be called inside every helper rather than on the test object once. It also explains why marking is local to the function: each program counter is independent. A closure created inside a helper has its own program counter; it must call t.Helper itself or the reported failure points into the closure.

The runner's behaviour is documented succinctly in the testing.T.Helper godoc: "Helper marks the calling function as a test helper function. When printing file and line information, that function will be skipped." Three practical consequences follow.

First, t.Helper is cheap. A pointer comparison against the helper map on failure is negligible. Use it everywhere it is appropriate; there is no reason to be sparing.

Second, marking a function does not change the runtime behaviour of t.Fatalf. The test still terminates immediately by calling runtime.Goexit on the test's goroutine; the helper exits, the test's goroutine exits, and deferred functions run. The only difference is the reported location.

Third, t.Helper does not propagate across goroutines. If a helper spawns a goroutine that calls t.Errorf, the failure is reported with the location inside the goroutine, regardless of t.Helper calls on either side. The testing package warns that calling reporting methods from goroutines other than the test's own is unsafe and forbids t.Fatalf there; the only safe pattern is to communicate the failure back through a channel and let the main goroutine report it.

A worked stack-walking example

Consider a chain of three helpers:

func assertValidPayment(tb testing.TB, p Payment) {
    tb.Helper()
    assertNonZeroAmount(tb, p.Amount)
    assertValidCurrency(tb, p.Currency)
}

func assertNonZeroAmount(tb testing.TB, amount int64) {
    tb.Helper()
    if amount == 0 {
        tb.Errorf("amount is zero")
    }
}

func assertValidCurrency(tb testing.TB, c string) {
    tb.Helper()
    if !validCurrencies[c] {
        tb.Errorf("invalid currency %q", c)
    }
}

A failing call from TestPayment produces a trace that walks past all three helpers and lands on TestPayment. Drop tb.Helper() from assertValidPayment and the trace lands inside that function, between the two inner calls. The reader has to look at the source of assertValidPayment to know which inner assertion failed. The trace is still readable, but the file:line is wrong.

The lesson is consistent application: every helper, every call. Skip none, even ones that only delegate to another helper.

Parallel tests and helpers

A helper that allocates a shared resource must not be called from a parallel test without locking, or worse, must not be shared at all. The standard pattern is per-test resources:

func newTestStore(tb testing.TB) *Store {
    tb.Helper()
    dir := tb.TempDir()
    s, err := store.Open(dir)
    if err != nil {
        tb.Fatalf("open: %v", err)
    }
    tb.Cleanup(func() { _ = s.Close() })
    return s
}

func TestStoreInsert(t *testing.T) {
    t.Parallel()
    s := newTestStore(t)
    _ = s.Put("k", "v")
}

Each test calls tb.TempDir, which returns a unique directory. Each test has its own store. The helper makes parallel execution safe by isolating state; it does not need any synchronisation.

When a helper depends on truly shared state (a docker container, a network namespace), the helper either acquires a lock for the duration of the test or refuses to be called from a parallel test. The cleanest pattern is to detect parallel use and skip:

var sharedFixtureMu sync.Mutex

func newSharedFixture(tb testing.TB) *Fixture {
    tb.Helper()
    sharedFixtureMu.Lock()
    tb.Cleanup(sharedFixtureMu.Unlock)
    return globalFixture
}

Even so, a helper that requires global serialisation is a smell. Look for a way to isolate the resource per test before reaching for a lock. A docker container can be ephemeral; a network namespace can have a unique name; a singleton service can be wrapped in a per-test proxy. Locking is a last resort.

Subtests and t.Parallel

A subtest inherits parallel status from its parent only if the subtest itself calls t.Parallel. A parallel parent with sequential subtests runs the subtests inside the parent's goroutine. A parallel parent with parallel subtests runs the subtests concurrently with each other and with other parallel tests.

Helpers do not need to know about this. The contract is that the helper receives a *testing.T whose lifetime spans the call. The helper registers cleanup with that t, which the runner attaches to the right scope. Subtests and parents have separate *testing.T values; passing the wrong one produces cleanups attached to the wrong scope. The compiler does not catch the mistake; tests pass and resources leak.

The rule from the junior tier ("inside t.Run, use the inner t") is the rule that prevents the bug.

Property tests via testing/quick.Check

testing/quick is the standard library's tiny property testing toolkit. It runs a function with random arguments and reports the first failing case. A helper wraps the awkward error handling:

func checkProperty(tb testing.TB, f any, cfg *quick.Config) {
    tb.Helper()
    if err := quick.Check(f, cfg); err != nil {
        tb.Errorf("property failed: %v", err)
    }
}

A property test:

func TestReverseInvolution(t *testing.T) {
    checkProperty(t, func(xs []int) bool {
        ys := append([]int(nil), xs...)
        Reverse(ys)
        Reverse(ys)
        return reflect.DeepEqual(xs, ys)
    }, nil)
}

quick.Check runs the property 100 times by default with random []int values. The helper attributes failure to the test's line, not its own.

testing/quick is limited. The generators it produces are uniform over the type's domain, which often does not match the input distribution the code expects. The error from quick.Check reports the failing input but does not shrink it; a failing slice of 1000 elements remains 1000 elements wide. For richer generators, the gopter library or the more recent rapid package give better shrinking and combinators. For many invariant tests, the standard library is enough.

Properties worth testing

Algebraic laws are the natural targets for property tests:

  • reverse(reverse(xs)) == xs for any list.
  • sort(sort(xs)) == sort(xs) (idempotence).
  • marshal(unmarshal(data)) == data for any value.
  • parse(format(t)) == t for any time.
  • encrypt(decrypt(ct)) == ct for any ciphertext under a fixed key.

These are the properties that example-based tests miss because they hold for inputs the author never considered. A helper that wraps quick.Check makes them easy to add.

func TestJSONRoundTrip(t *testing.T) {
    checkProperty(t, func(p Payment) bool {
        data, err := json.Marshal(p)
        if err != nil {
            return false
        }
        var p2 Payment
        if err := json.Unmarshal(data, &p2); err != nil {
            return false
        }
        return cmp.Equal(p, p2)
    }, nil)
}

The property is "any payment marshals and unmarshals to itself". The test is one helper call. If the property fails, the runner prints the failing payment.

cmp.Diff with custom comparers

The interesting part of cmp.Diff is not Diff itself but the option system that lets the comparison match what the test means by equal. A helper that knows about its domain encapsulates these options:

var paymentOpts = cmp.Options{
    cmpopts.IgnoreFields(Payment{}, "ID", "CreatedAt"),
    cmpopts.EquateApprox(0, 1e-9),
}

func diffPayment(tb testing.TB, got, want Payment) {
    tb.Helper()
    if d := cmp.Diff(want, got, paymentOpts...); d != "" {
        tb.Errorf("payment mismatch (-want +got):\n%s", d)
    }
}

Now every test that compares payments uses the same definition of equality. A change in the rule (suddenly the rounding tolerance is too loose) is a single-line edit, not a sweep across every test file.

For collections, cmpopts.SortSlices and cmpopts.SortMaps reduce a position-sensitive comparison to a content-based one. For private types, cmp.AllowUnexported(MyType{}) lets the diff cross package boundaries without exporting internal fields.

Custom comparers and transformers

When the standard options do not fit, two interfaces extend the system: cmp.Comparer and cmp.Transformer. A Comparer takes a binary function and returns an option that uses it on values of the function's type:

opt := cmp.Comparer(func(a, b BigInt) bool { return a.Cmp(b) == 0 })
testutil.Diff(t, got, want, opt)

A Transformer rewrites values before comparison. Useful for normalising volatile data:

opt := cmp.Transformer("trim", func(s string) string {
    return strings.TrimSpace(s)
})
testutil.Diff(t, got, want, opt)

Both options are powerful and best confined to a domain helper. A test that calls cmp.Diff with five inline options is harder to read than a test that calls diffPayment(t, got, want) with the options encapsulated.

When to define Equal on the type

Some types implement an Equal(T) bool method. cmp.Diff honours it automatically: when comparing two values, it calls their Equal method if defined. This is the cleanest path when the type has a canonical notion of equality that does not match ==. A big.Int.Cmp wrapped in Equal is the classic example.

When the type belongs to a third party, you cannot add Equal. The cmp.Comparer option fills the gap. When the type is yours and the test's definition of equality matches the production definition, defining Equal on the type is the most discoverable approach.

Helper testing

A helper that fails to fail is dangerous. Test the helpers themselves with a fake testing.TB. The interface is large but each helper exercises only a small slice:

type fakeTB struct {
    testing.TB
    errors  []string
    fatal   bool
    helpers int
}

func (f *fakeTB) Helper()                              { f.helpers++ }
func (f *fakeTB) Errorf(format string, args ...any)    { f.errors = append(f.errors, fmt.Sprintf(format, args...)) }
func (f *fakeTB) Fatalf(format string, args ...any)    { f.errors = append(f.errors, fmt.Sprintf(format, args...)); f.fatal = true; runtime.Goexit() }

A test for Equal:

func TestEqualFails(t *testing.T) {
    f := &fakeTB{TB: t}
    func() {
        defer func() { _ = recover() }()
        Equal(f, 1, 2)
    }()
    if len(f.errors) != 1 {
        t.Errorf("expected 1 error, got %d", len(f.errors))
    }
    if f.helpers == 0 {
        t.Error("helper did not call t.Helper()")
    }
}

The fake records the calls and the assertion verifies behaviour. This is exactly how the standard library tests its own helpers, and it scales to property-style tests of helpers (random inputs, check that equal inputs do not produce errors).

Why test the helpers

Three reasons make helper testing worth the time.

First, a helper that does not fail when it should breaks every test that uses it. Silent helpers produce silent test bugs.

Second, refactors are mechanical: rename a parameter, swap an implementation, change the failure message. Without helper tests, the refactor is verified only by the helpers' downstream tests, and a missed case slips through.

Third, helpers are the project's test API. The same scrutiny you apply to production APIs (input validation, error messages, backwards compatibility) is worth applying to helpers used across fifty packages.

testify versus hand-rolled

testify is the most popular assertion library in the Go ecosystem. It defines two main packages:

  • assert records a failure and continues, like t.Errorf.
  • require records a failure and stops, like t.Fatalf.

A test in testify style:

import "github.com/stretchr/testify/require"

func TestUser(t *testing.T) {
    u, err := loadUser(1)
    require.NoError(t, err)
    require.Equal(t, "Ada", u.Name)
    require.Equal(t, 36, u.Age)
}

The library uses reflection and produces a uniform failure format. Its strengths are familiarity for developers from other languages, a large library of matchers (Contains, Subset, Eventually, Panics, HTTPError), and consistency across projects that adopt it.

Its weaknesses are well known. Reflection means slower failure paths and worse error messages for typed values that print poorly through %v. Equal on slices and maps does not produce a diff; you need cmp.Diff anyway. The fluent API tempts authors to write long lists of assertions that document fields without explaining intent. Adding the dependency on a small project costs more than it gains.

The practical rule: prefer hand-rolled helpers built on cmp.Diff and t.Helper. Reach for testify when an existing project already uses it and consistency matters more than aesthetics, or when the team has many contributors who are more productive with the matchers. Never mix the two within a package; pick one style per package and stick to it.

A detailed comparison

The same test rewritten in three styles. Standard library:

func TestAuthorizeStdlib(t *testing.T) {
    sess, err := Login("ada", "pw")
    if err != nil {
        t.Fatalf("Login: %v", err)
    }
    if !sess.IsAuthenticated() {
        t.Error("expected authenticated session")
    }
    if sess.User.Role != "admin" {
        t.Errorf("role: got %q, want admin", sess.User.Role)
    }
}

Hand-rolled helpers:

func TestAuthorizeHelpers(t *testing.T) {
    sess, err := Login("ada", "pw")
    testutil.RequireNoError(t, err)
    testutil.Equal(t, sess.IsAuthenticated(), true)
    testutil.Equal(t, sess.User.Role, "admin")
}

Testify:

func TestAuthorizeTestify(t *testing.T) {
    sess, err := Login("ada", "pw")
    require.NoError(t, err)
    assert.True(t, sess.IsAuthenticated())
    assert.Equal(t, "admin", sess.User.Role)
}

All three communicate the same intent. The differences are matters of taste, package boundaries, and dependency management. None of the three is wrong; the choice is about what the project standardises on.

When a helper has become a framework

A helper graduates into a framework when reading the test no longer tells you what is being tested. Signs include:

  • The setup line is opaque: newScenario(t).withDefaults().run().
  • A failure message points at the helper and does not name a meaningful property of the system.
  • Adding a new test requires adding a new method to the helper.

The cure is to push behaviour back into the test. Helpers should reduce noise, not encode behaviour. A small DSL of two or three methods is fine. A class hierarchy of fixtures, hooks, and matchers is over.

A useful exercise: delete the helpers and rewrite the test inline. If the inline version is clearer, the helper was a framework in disguise. If the inline version is twenty lines longer for the same intent, the helper earns its place.

The cost of a framework

A test framework that hides behaviour has three concrete costs.

First, debugging takes longer. A failure message that says "scenario X failed" forces the reader to open the framework and trace what scenario X does. A direct assertion says "got 404, want 200" and the reader knows immediately.

Second, the framework couples every test to its internals. A change in the framework breaks tests in ways the framework's tests cannot catch, because the failure mode depends on what each test expects.

Third, the framework discourages writing new tests. Authors who do not understand the framework hesitate to add tests because they are not sure where the right hook lives. The friction shows up as under-tested code, not as visible complaints.

The fix is the same in every case: shrink the framework until it becomes a set of helpers again.

Documenting helpers

Helpers in internal/testutil are still part of the project's API for its tests. Document them with godoc comments that describe the failure mode explicitly:

// Equal reports an error via tb.Errorf when got != want. It does not
// stop the test; use Require for a fatal variant. Equal calls
// tb.Helper so failure messages point at the caller.
func Equal[T comparable](tb testing.TB, got, want T) {
    tb.Helper()
    if got != want {
        tb.Errorf("got %v, want %v", got, want)
    }
}

When a new contributor reads testutil.Equal, the comment removes the need to read the implementation. The comment also makes the distinction between Equal and RequireEqual explicit; without it, the names alone do not communicate the difference.

Examples in godoc

A // Example function attached to a helper appears in the godoc output and is run as a test:

func ExampleEqual() {
    var tb testing.TB = nil // would be a real *testing.T in a test
    _ = tb
    // testutil.Equal(t, computeSum(1, 2), 3)
}

Examples are not the right venue for elaborate documentation, but they double as compile-time checks that the API works as described.

What changes at scale

In a suite of two hundred tests, you can write each helper for one use case. In a suite of five thousand tests, helpers become the project's test language and their decisions compound. Three rules pay off at that scale.

First, every helper takes testing.TB, not *testing.T. Benchmarks reuse the same helpers, and parallel benchmark suites cost nothing extra.

Second, every helper that owns a resource uses t.Cleanup. Manual cleanup returns are a perennial source of leaks in long suites.

Third, every helper calls t.Helper as the first statement. The marginal cost is zero and the marginal benefit (clear failure traces) is large.

Helper performance

At scale, helpers run thousands of times. A helper that allocates a bytes.Buffer or compiles a regular expression on every call shows up in the suite's runtime. Profile the suite with go test -bench when the runtime gets unacceptable; helpers are the first place to look.

The Optimize page on this module walks through a concrete example. The general rule: cheap path first, allocate only on failure, never compile regular expressions inside the helper body.

Helpers in benchmarks

Benchmarks accept *testing.B, which embeds testing.TB. Every helper that takes testing.TB works in benchmarks without changes:

func BenchmarkInsert(b *testing.B) {
    db := newTestDB(b)
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        if err := db.Insert(i); err != nil {
            b.Fatalf("insert: %v", err)
        }
    }
}

The benchmark uses the same newTestDB helper as the tests. Resource allocation happens once outside the loop; the loop body measures the operation under test. b.ResetTimer excludes the setup time from the measurement.

Without shared helpers, benchmarks duplicate setup code from tests. With them, the same fixtures work in both, and a refactor to the fixture updates both at once.

Helpers for context handling

Modern Go code threads context.Context everywhere. A helper that produces a test-scoped context simplifies callers:

func TestContext(tb testing.TB) (context.Context, context.CancelFunc) {
    tb.Helper()
    ctx, cancel := context.WithCancel(context.Background())
    tb.Cleanup(cancel)
    return ctx, cancel
}

func TestContextWithTimeout(tb testing.TB, d time.Duration) (context.Context, context.CancelFunc) {
    tb.Helper()
    ctx, cancel := context.WithTimeout(context.Background(), d)
    tb.Cleanup(cancel)
    return ctx, cancel
}

The test:

func TestProcess(t *testing.T) {
    ctx, _ := TestContext(t)
    if err := Process(ctx); err != nil {
        t.Fatalf("Process: %v", err)
    }
}

The cleanup cancels the context when the test ends, freeing any goroutines that are waiting on it. The pattern prevents the leak that happens when a test starts a context-aware goroutine and exits without cancelling.

Goroutines and assertion safety

The testing package documents that calls to t.Errorf, t.Fatalf, and friends from goroutines other than the test's own goroutine are unsafe. t.Fatalf in particular relies on runtime.Goexit to stop the test, which only works for the goroutine that called t.Run. Calling t.Fatalf from a worker goroutine produces undefined behaviour: the worker might exit, the test might continue, or the runtime might panic.

The right pattern is to communicate the failure back:

func TestWorker(t *testing.T) {
    errs := make(chan error, 1)
    go func() {
        if err := process(); err != nil {
            errs <- err
            return
        }
        errs <- nil
    }()
    select {
    case err := <-errs:
        if err != nil {
            t.Fatalf("process: %v", err)
        }
    case <-time.After(time.Second):
        t.Fatal("timeout waiting for worker")
    }
}

A helper that does this for the common case:

func waitOrFail(tb testing.TB, errs <-chan error, d time.Duration) {
    tb.Helper()
    select {
    case err := <-errs:
        if err != nil {
            tb.Fatalf("worker error: %v", err)
        }
    case <-time.After(d):
        tb.Fatalf("worker did not finish within %s", d)
    }
}

The helper runs on the test's goroutine, which is the only safe place to call Fatalf. The worker reports its outcome through the channel.

t.Cleanup in concurrent tests

t.Cleanup functions run after the test function returns, on the test's goroutine. If a cleanup blocks (waits on a channel that the test never closes), the test hangs. The runtime detects most cases of this via the -timeout flag, but the diagnostic is poor; the suite simply exits with "test timed out".

Helpers that register cleanups must guarantee progress. For goroutines spawned during the test, a typical pattern is:

func startWorker(tb testing.TB) *worker {
    tb.Helper()
    ctx, cancel := context.WithCancel(context.Background())
    w := &worker{}
    done := make(chan struct{})
    go func() {
        defer close(done)
        w.run(ctx)
    }()
    tb.Cleanup(func() {
        cancel()
        select {
        case <-done:
        case <-time.After(5 * time.Second):
            tb.Errorf("worker did not exit within 5s")
        }
    })
    return w
}

The cleanup cancels the context and waits for the worker to exit. The bounded wait prevents a hang; an error message tells the operator that something held the worker beyond the timeout.

Picking the right helper level

A common question is whether to put a helper in the test file, in the package's helpers_test.go, or in internal/testutil. The decision is about reach.

  • One use, one file: keep it in the test file.
  • Several uses, one package: move to helpers_test.go in the package.
  • Several uses, several packages: move to internal/testutil.

Promotion is one-way. A helper rarely demotes from internal/testutil back to a single package, because once it is shared, removing it breaks consumers. Be sure the helper is worth promoting before doing so.

Avoid premature sharing

Helpers in internal/testutil are commitments. Once five packages import a helper, changing its signature requires touching all five. A helper that lives in one package is free to evolve.

The rule of thumb: a helper graduates to internal/testutil when at least two packages have copied it. Two existing copies prove that the helper is generic. One copy in one package is data; you do not yet know whether the helper has a single canonical shape or whether each package should specialise it.

Helpers and integration boundaries

Some tests touch external systems: a real database, a containerised service, a mocked HTTP endpoint. Helpers at the boundary serve a double purpose: they hide the integration mechanics, and they document which tests need which dependencies.

A typical pattern is a per-dependency helper:

func requireDocker(tb testing.TB) {
    tb.Helper()
    if _, err := exec.LookPath("docker"); err != nil {
        tb.Skip("docker not available")
    }
}

func TestWithRealRedis(t *testing.T) {
    requireDocker(t)
    redis := startRedisContainer(t)
    // ...
}

The helper skips the test on machines that lack the dependency. CI configures the dependencies and runs the full suite; local development runs the lighter suite without the heavier ones. The skip is explicit and the reason is in the test, not hidden in build tags.

t.Skip versus build tags

Build tags exclude a file from compilation. t.Skip includes the file but skips the run. The choice depends on whether the test code itself can build on the constrained machine.

  • A test that imports a package only available on Linux uses a build tag.
  • A test that needs Docker but compiles without it uses t.Skip through a helper.

Skip is friendlier: the test exists, contributors see it, and the helper documents the dependency. Build tags are necessary when the imports themselves are not portable.

A pattern: snapshot testing helpers

Snapshot testing compares the test's output to a stored snapshot. The pattern is the same as golden files, but the snapshot helper handles serialisation:

func assertSnapshot[T any](tb testing.TB, name string, got T) {
    tb.Helper()
    data, err := json.MarshalIndent(got, "", "  ")
    if err != nil {
        tb.Fatalf("marshal: %v", err)
    }
    path := filepath.Join("testdata", "snapshots", name+".json")
    if *updateSnapshots {
        if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
            tb.Fatalf("mkdir: %v", err)
        }
        if err := os.WriteFile(path, data, 0o644); err != nil {
            tb.Fatalf("write snapshot: %v", err)
        }
        return
    }
    want, err := os.ReadFile(path)
    if err != nil {
        tb.Fatalf("read snapshot %s: %v", path, err)
    }
    if !bytes.Equal(data, want) {
        tb.Errorf("snapshot mismatch for %s\ngot:  %s\nwant: %s", name, data, want)
    }
}

The helper makes adding a new snapshot test one line:

func TestRenderTemplate(t *testing.T) {
    out := RenderTemplate(input)
    assertSnapshot(t, "render_template", out)
}

Running go test -update-snapshots rewrites the snapshot. The pattern works for any deterministic output: HTML, SQL, JSON, generated code.

Helpers across module boundaries

When a project publishes a library, the library's tests may need helpers that the library's consumers also need. The choice is between:

  • Keep helpers in internal/testutil: only the library uses them.
  • Publish helpers in a testing/ subpackage: consumers can use them too.

The second option is rare and risky. Publishing test helpers makes them part of the library's public API: a breaking change in a helper is a major version bump. Most projects keep helpers internal and document patterns instead.

A library that does publish helpers names the package <lib>test, similar to the standard library's httptest, iotest, fstest. The convention signals that the package is for tests of code that uses the library, not for tests of the library itself.

The testing.M entry point

A package's tests run inside a TestMain function if defined. Helpers can hook into this point for one-time setup:

func TestMain(m *testing.M) {
    setup()
    code := m.Run()
    teardown()
    os.Exit(code)
}

Use TestMain sparingly. Most setup belongs in test functions or helpers, not in a package-global hook. The hook makes parallel test running tricky and hides state that the test author would otherwise see.

When TestMain is justified (a global database connection that cannot be per-test, a one-time fixture that takes minutes to build), the pattern is:

var globalDB *sql.DB

func TestMain(m *testing.M) {
    var err error
    globalDB, err = openSharedDB()
    if err != nil {
        fmt.Fprintf(os.Stderr, "setup: %v\n", err)
        os.Exit(1)
    }
    code := m.Run()
    globalDB.Close()
    os.Exit(code)
}

Tests access globalDB directly. The compromise is acceptable when the setup cost dominates the run time and the tests are read-only on the shared resource.

A helper file checklist

When reviewing a helper file (helpers_test.go or internal/testutil), walk through each function and check:

  • Does it start with tb.Helper()?
  • Is the failure mode (continue vs stop) appropriate for the helper's purpose?
  • Does it register cleanup via tb.Cleanup instead of returning a func?
  • Does it accept testing.TB rather than *testing.T?
  • Is the godoc comment accurate?
  • Is the helper used by at least one test? (Dead helpers accumulate.)
  • Does the helper compose with others, or does it duplicate work another helper already does?

Running this checklist takes a few minutes per file and surfaces the incremental drift that turns a clean helper package into a tangle.

A note on quick.Config

testing/quick.Check accepts a *quick.Config parameter. The config sets the iteration count, the random seed, the maximum generation size for slices, and a function that produces values for types the package cannot generate itself.

A helper that exposes the config sensibly:

func checkPropertyN(tb testing.TB, n int, f any) {
    tb.Helper()
    cfg := &quick.Config{MaxCount: n}
    if err := quick.Check(f, cfg); err != nil {
        tb.Errorf("property failed: %v", err)
    }
}

func TestSortStability(t *testing.T) {
    checkPropertyN(t, 1000, func(xs []int) bool {
        ys := append([]int(nil), xs...)
        sort.Ints(ys)
        return sort.IntsAreSorted(ys)
    })
}

Increasing the iteration count exercises more inputs at the cost of runtime. A property that holds for 100 cases usually holds for 1000; when it does not, the larger sample finds the bug.

Backwards compatibility for shared helpers

A helper used by 50 packages cannot change its signature without breaking 50 callers. The discipline for internal/testutil is the same as for any shared library: add, do not change.

When a helper needs new behaviour:

  • Prefer adding a new helper rather than adding parameters to the existing one.
  • Use variadic options if the new parameter is genuinely optional and rarely used.
  • Bump the helper's name (EqualV2) only if the old version cannot evolve.

The cost of breaking a helper compounds with the suite size. A helper that hundreds of tests use has the same blast radius as a core production API.

Wrapping up

The senior tier is about judgement: when a helper is worth writing, when it has become too large, how the failure trace mechanism actually works, and how helpers fit into the test architecture as a whole. The Professional tier raises the same questions at the level of API design: signatures, documentation contracts, and the distinction between helpers that name properties of the system and helpers that encode behaviour the test pretends to check.

If you internalise one habit from this page, make it consistent application of t.Helper. Every helper. Every call. Every layer. The trace mechanism is the foundation that makes every other helper-related decision worth caring about.

Refactoring patterns for helper sprawl

Over time a project accumulates helpers that solve overlapping problems. Several signs of sprawl:

  • Two helpers do almost the same thing with slightly different signatures.
  • A helper is used once in the project and never again.
  • A helper's body is longer than the tests that call it.
  • The helper file has subsections marked with "// deprecated".

The remedies are mechanical:

  • Consolidate duplicates by keeping the better-named version and rewriting callers.
  • Inline single-use helpers back into their callers.
  • Split long helpers into focused ones.
  • Delete deprecated helpers once a migration window has passed.

A periodic cleanup of helpers is cheap insurance against drift. A team that touches helpers monthly keeps them aligned with the way tests are written; a team that lets helpers grow unchecked ends up with a folklore around which helper "really" works.

A pattern: dependency-aware helpers

A helper that depends on a particular kind of fixture can require it through a type rather than through a struct field. The pattern looks like a dependency injection container in miniature:

type fixtureDeps interface {
    DB() *sql.DB
    Clock() Clock
}

func newAuditLog(tb testing.TB, deps fixtureDeps) *AuditLog {
    tb.Helper()
    return NewAuditLog(deps.DB(), deps.Clock())
}

The test wires up deps once and passes it to every helper that needs it. The helpers do not have to know whether the database is SQLite or PostgreSQL or in-memory; they ask the interface and get the right thing.

The pattern is overkill for a small package. It pays off when a suite has several independent subsystems and tests combine them.

Error-message hygiene

Failure messages are read under pressure. A message that is unclear during the day costs minutes; the same message at 2 AM during an incident costs hours. Helpers should produce messages that satisfy two rules.

First, the message names the property. got 0, want 1000 is data; Amount: got 0, want 1000 names which property is wrong. The label is the difference between a stranger to the code recognising the failure and not.

Second, the message includes enough context to reproduce. A failure in a property test should print the failing input. A failure in a table test should print the case name. A failure in a polling helper should print the timeout.

A helper that does both:

func assertEqualWithContext[T comparable](tb testing.TB, got, want T, label string, ctx ...any) {
    tb.Helper()
    if got != want {
        msg := fmt.Sprintf("%s: got %v, want %v", label, got, want)
        for i := 0; i < len(ctx); i += 2 {
            key, val := ctx[i], ctx[i+1]
            msg += fmt.Sprintf(" (%v=%v)", key, val)
        }
        tb.Errorf("%s", msg)
    }
}

// Usage:
assertEqualWithContext(t, got.Amount, want.Amount, "Amount", "user", userID, "request", reqID)

Output: Amount: got 0, want 1000 (user=42) (request=abc-123).

The trailing context is optional; for most calls the basic form is sufficient. When the test fails in production-like data, the context tells the operator which row was involved.

Helpers in benchmarks revisited

A benchmark uses *testing.B, which embeds testing.TB. Helpers that allocate inside the benchmark loop affect the measured performance. The discipline:

  • Setup helpers run before b.ResetTimer. They are free.
  • Per-iteration helpers run inside the loop. They are measured.

A helper that runs once per iteration must be cheap; otherwise the benchmark measures the helper, not the code under test.

func BenchmarkProcess(b *testing.B) {
    db := newTestDB(b)        // free
    items := loadJSON[[]Item](b, "items.json") // free
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        if err := Process(db, items); err != nil {
            b.Fatalf("Process: %v", err)
        }
    }
}

Calling loadJSON inside the loop would dominate the measurement. Calling it once before ResetTimer excludes its cost from the result.

Distinguishing helpers from infrastructure

A small fragment of the codebase blurs the line between helpers and production code. A clock interface, for example, exists in production because the code needs to be testable. Its implementation for tests lives in internal/testutil (or internal/clock); the interface lives in the production package.

The rule is to keep production code free of test-specific imports. A helper that wraps a production interface for testing is fine; a helper that the production code itself imports is wrong.

// Production:
package clock
type Clock interface { Now() time.Time }
type real struct{}
func (real) Now() time.Time { return time.Now() }
func Real() Clock { return real{} }

// Test helper:
package testutil
import "example.com/myapp/clock"
type FixedClock struct{ T time.Time }
func (f FixedClock) Now() time.Time { return f.T }

The production clock package does not know about FixedClock. The test helper depends on the production interface, not the other way around.

A worked example: end-to-end test with helpers

A complete end-to-end test combines several helper patterns. The test starts a worker, sends a job, waits for completion, and checks the result.

func TestJobLifecycle(t *testing.T) {
    t.Parallel()

    db := newTestDB(t)
    queue := newTestQueue(t)
    clock := startClock(t, "2026-05-21T12:00:00Z")
    worker := startWorker(t, workerConfig{
        DB:    db,
        Queue: queue,
        Clock: clock,
    })

    jobID := mustEnqueue(t, queue, Job{Type: "transcode", Input: "video.mp4"})

    eventually(t, 5*time.Second, func() bool {
        return getJobStatus(t, db, jobID) == "completed"
    })

    job := mustLoadJob(t, db, jobID)
    testutil.Equal(t, job.Status, "completed")
    testutil.Equal(t, job.Output, "video.mp4.transcoded")
    testutil.Diff(t, job.Logs, []string{
        "started",
        "transcoding",
        "uploaded",
        "completed",
    })

    _ = worker
}

Six helpers do the heavy lifting. The test body reads as the sequence of events the test author cares about: set up resources, enqueue a job, wait for it to finish, check the outcome. Every helper takes testing.TB, registers cleanup, calls t.Helper, and produces clear failure messages.

This is the level helpers should reach. The test does not contain any os.Open, defer Close, or error-checking boilerplate; it contains only domain operations.

A final mental model

Think of helpers as a project-specific test vocabulary. The vocabulary names properties (IsAuthenticated, HasExpired, MatchesGoldenFile) and resources (newDB, newServer, newContext). Tests written in the vocabulary read fluently and fail informatively. Tests written without it read as a sequence of mechanical operations and fail with messages that point at plumbing.

The vocabulary grows by accretion. Each new helper joins it because some test needed it more than once. The vocabulary shrinks rarely; removing a helper means rewriting every test that uses it. Plan for growth, plan for stability, and treat the vocabulary as the project's lasting investment in its own testability.

One last debugging story

A team had a flaky test that failed once every fifty runs. The failure message read:

got nil, want non-nil

with a file:line that pointed inside assertNotNil. The team had forgotten to call t.Helper() in that helper. They spent two days chasing the actual cause through a deeply nested code path. When they finally added t.Helper(), the next run's failure pointed at the exact line in the actual test, which named the property in question, which named the upstream data source, which was a race in a cache layer.

The race took five minutes to fix once the failure pointed at the right code. The two days of chasing were the cost of a missing t.Helper. Add the call. Always.

Comparison with other ecosystems

Languages with assertion libraries baked into their stdlib (Python's unittest, JUnit in Java) move the equivalent of t.Helper machinery deep into the framework. The Go approach exposes it as a single call, leaving the rest to the test author. The exposure is a feature: helpers in Go are normal functions that can be read, tested, and refactored like any other code.

The lighter framework also limits the framework's blast radius. A bug in t.Helper would affect the runtime's stack walking; that machinery is small enough to audit. A bug in a sprawling assertion library can cost a release. The Go approach trades a few extra keystrokes per helper for a smaller surface to trust.

Reading the testing package source

A senior engineer benefits from reading the testing package source once. The implementation of t.Helper is short, and the code that walks the stack on failure is straightforward. After reading it, the mental model of "helper marks a frame; failure skips marked frames" stops being a black box.

The relevant entry points:

  • (*common).Helper records the program counter.
  • (*common).decorate produces the failure prefix and walks the stack.
  • (*common).Cleanup registers a deferred function.

A few hundred lines of straightforward code. Worth a read when you have an hour to spare; it grounds every helper-related decision in concrete machinery.

Last reminder: helpers belong to the project

A common mistake is treating helpers as universal. They are not. Each project's helpers reflect that project's domain, style, and constraints. A newTestPayment helper from a billing service is useless in a video-streaming service. A test framework that tries to be both produces helpers nobody loves.

Write helpers for your project. Borrow patterns, not code. The patterns on this page apply everywhere; the specific helpers belong to specific codebases.

Reading list

  • The testing package source in the Go standard library.
  • The google/go-cmp documentation, particularly the cmpopts examples.
  • The testify repository for its strengths and weaknesses in practice.
  • Mitchell Hashimoto's writing on test helpers in Terraform.
  • Dave Cheney's articles on testing patterns in Go.

Each source contributes one piece of the puzzle. Reading them in sequence builds the judgement this page tries to summarise.

Helpers are the punctuation of a test suite: invisible when right, deeply annoying when wrong. Every page in this module is a way of saying the same thing: get the small things consistently right and the big things take care of themselves.