Go Testing

Quick Reference

t.Error

t.Fatal

cmp.Diff

t.Helper()

t.Cleanup()

Useful Test Failures

Normative: Test failures must be diagnosable without reading the test source.

Every failure message must include: function name, inputs, actual (got), and expected (want). Use the format

YourFunc(%v) = %v, want %v

// Good:
t.Errorf("Add(2, 3) = %d, want %d", got, 5)

// Bad: Missing function name and inputs
t.Errorf("got %d, want %d", got, 5)

Always print got before want:

got %v, want %v

No Assertion Libraries

Normative: Do not use assertion libraries. Use

cmp.Diff

for complex comparisons.

if diff := cmp.Diff(want, got); diff != "" {
    t.Errorf("GetPost() mismatch (-want +got):\n%s", diff)
}

For protocol buffers, add

protocmp.Transform()

(-want +got)

Read references/TEST-HELPERS.md when writing custom comparison helpers or domain-specific test utilities.

t.Error vs t.Fatal

Normative: Use

t.Error

by default to report all failures in one run. Use

t.Fatal

only when continuing is impossible.

Choose

t.Fatal

• Setup fails (DB connection, file load)
• The next assertion depends on the previous one succeeding (e.g., decode after encode)

Never call

t.Fatal

t.FailNow

t.Error

Read references/TEST-HELPERS.md when writing helpers that need to choose between t.Error and t.Fatal, or for detailed examples of both.

Table-Driven Tests

See

assets/table-test-template.go

when scaffolding a new table-driven test and need the canonical struct, loop, and subtest layout.

Advisory: Use table-driven tests when many cases share identical logic.

Use table tests when: all cases run the same code path with no conditional setup, mocking, or assertions. A single

shouldErr

Don't use table tests when: cases need complex setup, conditional mocking, or multiple branches — write separate test functions instead.

Key rules:

• Use field names when cases span many lines or have same-type adjacent fields
• Include inputs in failure messages — never identify rows by index

Read references/TABLE-DRIVEN-TESTS.md when writing table-driven tests, subtests, or parallel tests.

Validation: After generating or modifying tests, run

go test -run TestXxx -v

to verify the tests compile and pass. Fix any compilation errors before proceeding.

Test Helpers

Normative: Test helpers must call

t.Helper()

first and use

t.Cleanup()

for teardown.

func setupTestDB(t *testing.T) *sql.DB {
    t.Helper()
    db, err := sql.Open("sqlite3", ":memory:")
    if err != nil {
        t.Fatalf("Could not open database: %v", err)
    }
    t.Cleanup(func() { db.Close() })
    return db
}

Read references/TEST-HELPERS.md when writing test helpers, cleanup functions, or custom comparison utilities.

Test Error Semantics

Advisory: Test error semantics, not error message strings.

// Bad: Brittle string comparison
if err.Error() != "invalid input" { ... }

// Good: Semantic check
if !errors.Is(err, ErrInvalidInput) { ... }

For simple presence checks when specific semantics don't matter:

if gotErr := err != nil; gotErr != tt.wantErr {
    t.Errorf("f(%v) error = %v, want error presence = %t", tt.input, err, tt.wantErr)
}

Test Organization

Read references/TEST-ORGANIZATION.md when working with test doubles, choosing test package placement, or scoping test setup.

Read references/VALIDATION-APIS.md when designing reusable test validation functions.

Integration Testing

Read references/INTEGRATION.md when writing TestMain, acceptance tests, or tests that need real HTTP/RPC transports.

Available Scripts

• scripts/gen-table-test.sh

  — Generates a table-driven test scaffold

bash scripts/gen-table-test.sh ParseConfig config > config/parse_config_test.go
bash scripts/gen-table-test.sh --parallel ParseConfig config      # with t.Parallel()
bash scripts/gen-table-test.sh --output config/parse_config_test.go ParseConfig config

Related Skills

• Error testing: See go-error-handling when testing error semantics with

  errors.Is

  /

  errors.As

  or sentinel errors
• Interface mocking: See go-interfaces when creating test doubles by implementing interfaces at the consumer side
• Naming test functions: See go-naming when naming test functions, subtests, or test helper utilities
• Linter integration: See go-linting when running linters alongside tests in CI or pre-commit hooks