Go Test Quality

Go Test Quality

Tests are production code. They run in CI on every commit, they document behavior, and they're the first thing you read when a function breaks at 3am. Write them with the same care you'd give to code that handles money.

Detailed reference material, loaded on demand:

• references/helpers-and-fixtures.md — test helpers, factory functions with options, t.Cleanup, golden files, mock implementations.
• references/integration-testing.md — httptest recorder and server, testcontainers, build tags, TestMain, fuzz testing.

Read a reference file only when the summary below is not enough.

1. Test Design Philosophy

Test behavior, not implementation

// ✅ Good — tests what the function DOES
func TestTransferFunds_InsufficientBalance(t *testing.T) {
    from := NewAccount("alice", 100)
    to := NewAccount("bob", 0)

    err := TransferFunds(from, to, 150)

    require.ErrorIs(t, err, ErrInsufficientFunds)
    assert.Equal(t, 100, from.Balance(), "sender balance should be unchanged")
    assert.Equal(t, 0, to.Balance(), "receiver balance should be unchanged")
}

// ❌ Bad — tests HOW the function does it
// asserts debit() was called before credit(), rollback() was called,
// internal mutex was locked — breaks on every refactor

One assertion per logical concept

Multiple assert calls are fine when they verify different facets of the SAME behavior (both accounts after a transfer). A test that checks creation AND update AND deletion is three tests pretending to be one.

Name tests like bug reports

When the test fails, the name alone should say what broke:

// ✅ Good — reads like a sentence
func TestOrderService_Cancel_RefundsPartiallyShippedItems(t *testing.T) { ... }
func TestParseConfig_ReturnsErrorOnMissingRequiredField(t *testing.T) { ... }

// ❌ Bad — says nothing useful
func TestCancel(t *testing.T) { ... }
func TestRateLimiter_Success(t *testing.T) { ... }

2. Subtests for Organized Scenarios

Use t.Run to group related scenarios under a parent test. Each subtest gets its own setup, its own failure, and its own name in CI output:

func TestUserService_Create(t *testing.T) {
    svc := setupUserService(t)

    t.Run("succeeds with valid input", func(t *testing.T) {
        user, err := svc.Create(ctx, CreateUserInput{Name: "Alice", Email: "alice@example.com"})
        require.NoError(t, err)
        assert.NotEmpty(t, user.ID)
    })

    t.Run("rejects duplicate email", func(t *testing.T) {
        _, _ = svc.Create(ctx, CreateUserInput{Name: "Alice", Email: "taken@example.com"})
        _, err := svc.Create(ctx, CreateUserInput{Name: "Bob", Email: "taken@example.com"})
        require.ErrorIs(t, err, ErrDuplicateEmail)
    })
}

3. Test Helper Rules

1. Always call t.Helper() in test utilities so failures point to the caller, not the helper.
2. Factory functions with functional options for complex test objects — defaults with per-test overrides, never a 15-parameter constructor.
3. Prefer t.Cleanup over defer — it runs even after t.FailNow() and is scoped to the test, not the function.

Full implementations in references/helpers-and-fixtures.md.

4. Choosing the Test Type

5. Mocking Rules

• Interface-based hand-written mocks for small interfaces (≤3 methods): a struct with function fields plus recorded calls.
• Function injection for simple seams (now func() time.Time).
• Do NOT mock: value objects, pure functions, the standard library, or your own code in the same package. Test the real thing.
• If you mock everything, you're testing your mocks, not your code.

6. Parallelism and Coverage

func TestSlugify(t *testing.T) {
    t.Parallel() // safe: pure function, no shared state
    // ...
}

Do NOT use t.Parallel() when tests share mutable state, databases, files, or process-level state (os.Setenv).

go test -race -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Targets: business logic 80%+, critical paths (auth, payments) 95%+, handlers 70%+. Don't chase 100% on generated code and simple getters.

7. Testing Concurrent Code

Never synchronize a test with time.Sleep. It is slow when it works and flaky when it does not.

testing/synctest (Go 1.25+) runs a test inside a bubble with a fake clock. Time advances instantly whenever every goroutine in the bubble is blocked, so a one-hour timeout test finishes in microseconds and is deterministic.

import "testing/synctest"

func TestCacheExpiry(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        c := NewCache(time.Hour)
        c.Set("k", "v")

        time.Sleep(59 * time.Minute) // instant: fake clock
        if _, ok := c.Get("k"); !ok {
            t.Fatal("entry expired early")
        }

        time.Sleep(2 * time.Minute)
        if _, ok := c.Get("k"); ok {
            t.Fatal("entry outlived its TTL")
        }
    })
}

synctest.Wait() blocks until every other goroutine in the bubble is durably blocked — use it instead of sleeping to let a background goroutine reach a known point.

On Go 1.24 the package is behind GOEXPERIMENT=synctest and the entry point is synctest.Run. Below 1.24, poll with a deadline instead of sleeping.

Detect goroutine leaks in tests

A test that leaks a goroutine passes locally and destabilises the suite.

import "go.uber.org/goleak"

// Whole package, in TestMain:
func TestMain(m *testing.M) { goleak.VerifyTestMain(m) }

// Or per test:
func TestWorker(t *testing.T) {
    defer goleak.VerifyNone(t)
    // ... every goroutine started here must exit before the test returns
}

Add it to any package that starts goroutines. go test -race finds data races; it does not find a goroutine that never exits.

8. Test Context, Benchmarks, and Artifacts

Use t.Context() (Go 1.24+) instead of context.Background(). It is cancelled before t.Cleanup functions run, so anything blocking on it unwinds when the test ends — including on timeout or failure.

func TestFetch(t *testing.T) {
    ctx := t.Context()
    got, err := client.Fetch(ctx, "id-1") // cancelled automatically at test end
    // ...
}

Write benchmarks with for b.Loop() (Go 1.24+), not for range b.N. It runs setup exactly once, keeps arguments and results alive without a sink variable, and cannot be optimised away.

// ✅ Go 1.24+
func BenchmarkEncode(b *testing.B) {
    in := makeInput()
    for b.Loop() {
        Encode(in)
    }
}

// ❌ Pre-1.24 form — needs a package-level sink to defeat dead-code elimination
func BenchmarkEncode(b *testing.B) {
    in := makeInput()
    for range b.N {
        sink = Encode(in)
    }
}

Report allocations with b.ReportAllocs() and compare runs with benchstat.

Two newer reporting hooks, when the toolchain supports them:

• t.Attr("build", sha) (Go 1.25+) emits a key/value pair into the test log for CI to parse.
• t.ArtifactDir() with go test -artifacts (Go 1.26+) gives the test a directory that survives the run — write failing golden output, captured HTTP bodies, or profiles there instead of into the repository.

Anti-Patterns

• 🔴 Test with no assertions — always passes, proves nothing
• 🔴 time.Sleep for synchronization — use testing/synctest, channels, or polling
• 🔴 Test depends on execution order — each test must stand alone
• 🔴 Mocking everything — you end up testing your mocks, not your code
• 🟡 Test names like Test1, TestSuccess — name the scenario
• 🟡 Reaching into private fields — test through the public API
• 🟡 No edge cases: empty, nil, zero, max values, unicode
• 🟡 Giant shared setup — each test should set up only what it needs
• 🟢 Fuzz anything that takes untrusted input
• 🟢 Golden files for complex output comparisons
• 🟡 context.Background() in a test — use t.Context()
• 🟡 for range b.N on Go 1.24+ — use for b.Loop()

Verification Checklist

1. Every test has meaningful assertions (no empty test bodies)
2. Test names describe the scenario, not the method
3. t.Helper() called in every test utility function
4. t.Cleanup() used for resource teardown
5. t.Parallel() used where safe, avoided where not
6. Integration tests guarded with testing.Short() or build tags
7. Mocks are minimal — only mock external dependencies
8. No time.Sleep for synchronization anywhere in the suite
9. Packages that start goroutines verify with goleak
10. Benchmarks use for b.Loop() and call b.ReportAllocs()
11. Edge cases covered: empty, nil, zero, boundary values
12. go test -race ./... passes
13. Coverage is meaningful, not just high numbers