go-testing

SKILL.md

Go Testing

Quick Reference

Pattern
Use When

t.Error
Default — report failure, keep running

t.Fatal
Setup failed or continuing is meaningless

cmp.Diff
Comparing structs, slices, maps, protos

Table-driven
Many cases share identical logic

Subtests
Need filtering, parallel execution, or naming

t.Helper()
Any test helper function (call as first statement)

t.Cleanup()
Teardown in helpers instead of defer

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 — never reversed.

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() as a cmp option. Always
include the direction key (-want +got) in diff messages. Avoid comparing
JSON/serialized output — compare semantically instead.

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 when:

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 from a goroutine other than the test
goroutine — use t.Error instead.

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 bool is acceptable.

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