Go Testing

Go Testing

Compatibility: Diff examples may use github.com/google/go-cmp.

Resource Routing

• scripts/gen-table-test.sh - Run when generating a table-driven test scaffold.
• assets/table-test-template.go - Use as a copyable table-test starting point.
• references/TABLE-DRIVEN-TESTS.md - Read when choosing table tests, subtests, or parallel test patterns.
• references/TEST-HELPERS.md - Read when writing helpers, fixtures, cleanup, or test doubles.
• references/TEST-ORGANIZATION.md - Read when structuring packages, black-box tests, or larger test suites.
• references/VALIDATION-APIS.md - Read when choosing t.Error, t.Fatal, cmp.Diff, or assertion style.
• references/INTEGRATION.md - Read when testing external services, HTTP handlers, databases, or long-running setup.

Quick Reference

---

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.

---

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.

---

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

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
}

---

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)
}

---

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

Go Testing: Integration and Advanced Patterns

Detailed reference for TestMain, acceptance testing, and real transport testing. Sources: Google Go Style Guide (best-practices).

---

TestMain

Source: Google Go Style Guide (best-practices)

Use func TestMain(m *testing.M) when all tests in the package require common setup that needs teardown (e.g., a shared database). This should not be your first choice---prefer scoped test helpers or t.Cleanup when possible.

var db *sql.DB

func TestInsert(t *testing.T) { /* uses db */ }
func TestSelect(t *testing.T) { /* uses db */ }

func runMain(ctx context.Context, m *testing.M) (code int, err error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    d, err := setupDatabase(ctx)
    if err != nil {
        return 0, err
    }
    defer d.Close()
    db = d

    return m.Run(), nil
}

func TestMain(m *testing.M) {
    code, err := runMain(context.Background(), m)
    if err != nil {
        log.Fatal(err)
    }
    // defer statements do not run past os.Exit
    os.Exit(code)
}

Key points:

• Extract setup into a helper function (runMain) so defer works correctly
• Write failure messages to stderr via log.Fatal
• Ensure individual test cases remain hermetic---reset any global state they modify

---

Acceptance Testing

Source: Google Go Style Guide (best-practices)

Acceptance testing validates that an implementation upholds a contract, treating it as a black box. This pattern is useful when users implement your interfaces and you want to provide a reusable validation suite.

Structure

1. Create a test helper package (e.g., chesstest for package chess) 2. Export a validation function that accepts the implementation under test:

// Package chesstest provides acceptance tests for chess.Player implementations.
package chesstest

// ExercisePlayer tests a Player implementation in a single turn.
// Returns nil if the player makes a correct move, or an error describing
// the violation.
func ExercisePlayer(b *chess.Board, p chess.Player) error {
    move := p.Move()
    if putsOwnKingIntoCheck(b, move) {
        return &IllegalMoveError{Move: move, Reason: "puts own king in check"}
    }
    return nil
}

3. End users write simple tests against the validation function:

func TestAcceptance(t *testing.T) {
    player := deepblue.New()
    if err := chesstest.ExercisePlayer(chesstest.StartingBoard(), player); err != nil {
        t.Errorf("Deep Blue player failed acceptance test: %v", err)
    }
}

Reserve t.Fatal for setup failures only---validation errors should be returned, not fataled.

---

Use Real Transports

Source: Google Go Style Guide (best-practices)

When testing component integrations over HTTP or RPC, prefer real transport round-trips over hand-implemented client mocks:

func TestAPIIntegration(t *testing.T) {
    // Start a test server with a fake backend
    srv := httptest.NewServer(newFakeHandler())
    t.Cleanup(srv.Close)

    // Use a real HTTP client against the test server
    client := api.NewClient(srv.URL)
    result, err := client.GetUser(t.Context(), "user-123")
    if err != nil {
        t.Fatalf("GetUser() error: %v", err)
    }
    if result.Name != "Test User" {
        t.Errorf("GetUser().Name = %q, want %q", result.Name, "Test User")
    }
}

Using the production client with a test server ensures your test exercises as much real code as possible, avoiding the complexity of imitating client behavior. t.Context() requires Go 1.24 or newer; use an explicit context with cleanup-managed cancellation when maintaining older Go versions.

---

Common Mistakes

Calling os.Exit directly in TestMain

os.Exit terminates the process immediately — deferred cleanup functions never run. Extract setup/teardown into a helper so defer works correctly:

// Bad: defers won't run
func TestMain(m *testing.M) {
    setup()
    defer cleanup()
    os.Exit(m.Run()) // cleanup() never executes
}

// Good: Extract to a helper function so defer runs before os.Exit
func runTests(m *testing.M) int {
    setup()
    defer cleanup()
    return m.Run()
}

func TestMain(m *testing.M) {
    os.Exit(runTests(m))
}

Table-Driven Tests, Subtests, and Parallel Tests

Detailed reference for structuring table-driven tests and subtests in Go. Sources: Google Go Style Guide, Uber Go Style Guide.

---

Basic Structure

func TestCompare(t *testing.T) {
    tests := []struct {
        a, b string
        want int
    }{
        {"", "", 0},
        {"a", "", 1},
        {"", "a", -1},
        {"abc", "abc", 0},
    }
    for _, tt := range tests {
        got := Compare(tt.a, tt.b)
        if got != tt.want {
            t.Errorf("Compare(%q, %q) = %v, want %v", tt.a, tt.b, got, tt.want)
        }
    }
}

---

Best Practices

Use field names when test cases span many lines or have adjacent fields of the same type:

tests := []struct {
    name  string
    input string
    want  int
}{
    {name: "empty", input: "", want: 0},
    {name: "single", input: "a", want: 1},
}

Don't identify rows by index — include inputs in failure messages instead of Case #%d failed.

---

Avoid Complexity in Table Tests

When test cases need complex setup, conditional mocking, or multiple branches, prefer separate test functions over table tests.

// Bad: Too many conditional fields make tests hard to understand
tests := []struct {
    give          string
    want          string
    wantErr       error
    shouldCallX   bool
    shouldCallY   bool
    giveXResponse string
    giveXErr      error
    giveYResponse string
    giveYErr      error
}{...}

for _, tt := range tests {
    t.Run(tt.give, func(t *testing.T) {
        if tt.shouldCallX {
            xMock.EXPECT().Call().Return(tt.giveXResponse, tt.giveXErr)
        }
        if tt.shouldCallY {
            yMock.EXPECT().Call().Return(tt.giveYResponse, tt.giveYErr)
        }
        // ...
    })
}

// Good: Separate focused tests are clearer
func TestShouldCallX(t *testing.T) {
    xMock.EXPECT().Call().Return("XResponse", nil)
    got, err := DoComplexThing("inputX", xMock, yMock)
    // assert...
}

func TestShouldCallYAndFail(t *testing.T) {
    yMock.EXPECT().Call().Return("YResponse", nil)
    _, err := DoComplexThing("inputY", xMock, yMock)
    // assert error...
}

Table tests work best when:

• All cases run identical logic (no conditional assertions)
• Setup is the same for all cases
• No conditional mocking based on test case fields
• All table fields are used in all tests

A single shouldErr field for success/failure is acceptable if the test body is short and straightforward.

---

Subtests

Use t.Run for better organization, filtering, and parallel execution.

Subtest Names

• Use clear, concise names: t.Run("empty_input", ...), t.Run("hu_to_en", ...)
• Avoid wordy descriptions or slashes (slashes break test filtering)
• Subtests must be independent — no shared state or execution order dependencies

Table Tests with Subtests

func TestTranslate(t *testing.T) {
    tests := []struct {
        name, srcLang, dstLang, input, want string
    }{
        {"hu_en_basic", "hu", "en", "köszönöm", "thank you"},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            if got := Translate(tt.srcLang, tt.dstLang, tt.input); got != tt.want {
                t.Errorf("Translate(%q, %q, %q) = %q, want %q",
                    tt.srcLang, tt.dstLang, tt.input, got, tt.want)
            }
        })
    }
}

---

Parallel Tests

When using t.Parallel() in table tests, be aware of loop variable capture:

for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        t.Parallel()
        // Go 1.22+: tt is correctly captured per iteration
        // Go 1.21-: add "tt := tt" here to capture the variable
        got := Process(tt.give)
        if got != tt.want {
            t.Errorf("Process(%q) = %q, want %q", tt.give, got, tt.want)
        }
    })
}

Test Helpers, Assertions, and Comparisons

Detailed reference for writing test helpers, avoiding assertion libraries, and choosing between t.Error and t.Fatal. Sources: Google Go Style Guide, Uber Go Style Guide.

---

Test Helper Pattern

Test helpers must call t.Helper() first so failures point to the caller. Use t.Fatal for setup failures, and t.Cleanup for teardown.

func mustLoadTestData(t *testing.T, filename string) []byte {
    t.Helper()
    data, err := os.ReadFile(filename)
    if err != nil {
        t.Fatalf("Setup failed: could not read %s: %v", filename, err)
    }
    return data
}

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
}

Key rules:

• Call t.Helper() as the first statement to attribute failures to the caller
• Use t.Fatal for setup failures (don't return errors from helpers)
• Use t.Cleanup() for teardown instead of defer — it runs even if the test

calls t.FailNow

---

Avoiding Assertion Libraries

Normative: Do not create or use assertion libraries.

Assertion libraries fragment the developer experience and often produce unhelpful failure messages.

// Bad:
assert.IsNotNil(t, "obj", obj)
assert.StringEq(t, "obj.Type", obj.Type, "blogPost")
assert.IntEq(t, "obj.Comments", obj.Comments, 2)

// Good: Use cmp package and standard comparisons
want := BlogPost{
    Type:     "blogPost",
    Comments: 2,
    Body:     "Hello, world!",
}
if diff := cmp.Diff(want, got); diff != "" {
    t.Errorf("GetPost() mismatch (-want +got):\n%s", diff)
}

Domain-Specific Comparisons

For domain-specific comparisons, return values or errors instead of calling t.Error:

func postLength(p BlogPost) int { return len(p.Body) }

func TestBlogPost(t *testing.T) {
    post := BlogPost{Body: "Hello"}
    if got, want := postLength(post), 5; got != want {
        t.Errorf("postLength(post) = %v, want %v", got, want)
    }
}

---

Comparisons and Diffs

Prefer cmp.Equal and cmp.Diff for complex types. Always include the direction key (-want +got) in diff messages.

// Struct comparison
want := &Doc{Type: "blogPost", Authors: []string{"isaac", "albert"}}
if diff := cmp.Diff(want, got); diff != "" {
    t.Errorf("AddPost() mismatch (-want +got):\n%s", diff)
}

// Protocol buffers
if diff := cmp.Diff(want, got, protocmp.Transform()); diff != "" {
    t.Errorf("Foo() mismatch (-want +got):\n%s", diff)
}

Avoid unstable comparisons — don't compare JSON/serialized output that may change. Compare semantically instead.

---

t.Error vs t.Fatal: Detailed Guidance

Use t.Error to keep tests going and report all failures in a single run:

// Good: Report all mismatches
if diff := cmp.Diff(wantMean, gotMean); diff != "" {
    t.Errorf("Mean mismatch (-want +got):\n%s", diff)
}
if diff := cmp.Diff(wantVariance, gotVariance); diff != "" {
    t.Errorf("Variance mismatch (-want +got):\n%s", diff)
}

Use t.Fatal when subsequent checks would be meaningless:

gotEncoded := Encode(input)
if gotEncoded != wantEncoded {
    t.Fatalf("Encode(%q) = %q, want %q", input, gotEncoded, wantEncoded)
}
gotDecoded, err := Decode(gotEncoded)
if err != nil {
    t.Fatalf("Decode(%q) error: %v", gotEncoded, err)
}

Don't Call t.Fatal from Goroutines

Normative: Never call t.Fatal, t.Fatalf, or t.FailNow from a

goroutine other than the test goroutine. Use t.Error instead and let the

goroutine return naturally.

Test Organization Reference

Sources: Google Go Style Guide (best-practices, decisions).

---

Test Double Types

Prefer fakes over mocks. Fakes are more readable and don't require mock frameworks. Reserve spies for verifying side effects (e.g., an analytics event).

// Fake: Working in-memory implementation
type FakeUserStore struct {
    users map[string]*User
}

func (f *FakeUserStore) GetUser(id string) (*User, error) {
    u, ok := f.users[id]
    if !ok {
        return nil, ErrNotFound
    }
    return u, nil
}

// Spy: Records calls for later assertion
type SpyEmailSender struct{ Sent []string }

func (s *SpyEmailSender) Send(to, body string) error {
    s.Sent = append(s.Sent, to)
    return nil
}

---

Test Double Naming Conventions

Advisory: Follow consistent naming for test doubles (stubs, fakes, spies).

Package naming: Create a *test package alongside production code (e.g., creditcardtest for package creditcard, fakeauthservice for a standalone fake service).

// Good: In package creditcardtest

// Single double — use simple name
type Stub struct{}
func (Stub) Charge(*creditcard.Card, money.Money) error { return nil }

// Multiple behaviors — name by behavior
type AlwaysCharges struct{}
type AlwaysDeclines struct{}

// Multiple types — include type name
type StubService struct{}
type StubStoredValue struct{}

Local variables: Prefix test double variables with the double type for clarity at the call site:

// Good: Double type is immediately visible
spyCC := &creditcardtest.Spy{}
stubDB := &dbtest.Stub{Balance: 100}

// Bad: Ambiguous — is this real or a double?
cc := &creditcardtest.Spy{}
db := &dbtest.Stub{Balance: 100}

---

Standalone Test Helper Packages

Create a standalone test helper package when multiple packages need the same double, the helper has enough logic to warrant its own tests, or you want to provide an acceptance test suite for interface implementers.

package usertest

func NewFakeStore(t *testing.T, users ...*user.User) *FakeUserStore {
    t.Helper()
    store := &FakeUserStore{users: make(map[string]*user.User)}
    for _, u := range users {
        store.users[u.ID] = u
    }
    return store
}

Export constructors that accept *testing.T so they can call t.Helper() and t.Cleanup().

---

Test Packages

Both go in foo_test.go files in the same directory.

Use `package foo` (white-box) when you need to test unexported functions or internal state.

Use `package foo_test` (black-box) when testing only the public API, breaking import cycles, or verifying external usability.

package parser_test  // Black-box: only tests exported API

import "mymodule/parser"

func TestParse(t *testing.T) {
    got, err := parser.Parse("input")
    // ...
}

If a black-box test needs an unexported symbol, create export_test.go in package foo (not foo_test) that exposes it. Use this sparingly.

---

Setup Scoping

Advisory: Keep setup scoped to tests that need it.

Explicit setup in each test is clearer and avoids penalizing unrelated tests:

// Good: Explicit setup in tests that need it
func TestParseData(t *testing.T) {
    data := mustLoadDataset(t)
    // ...
}

func TestUnrelated(t *testing.T) {
    // Doesn't pay for dataset loading
}

Avoid global `init` for test setup — it runs for every test in the file, even unrelated ones.

Subtest setup: Use a parent test with t.Run when a group of subtests shares setup:

func TestDatabase(t *testing.T) {
    db := setupTestDB(t)

    t.Run("Insert", func(t *testing.T) {
        // uses db
    })
    t.Run("Select", func(t *testing.T) {
        // uses db
    })
}

This scopes the database lifecycle to the subtests that need it. Use TestMain only as a last resort (see INTEGRATION.md).

Extensible Validation APIs

Detailed reference for designing reusable test validation functions that callers can use for acceptance testing. Sources: Google Go Style Guide (best-practices).

---

The *test Package Export Pattern

When you own an interface that others implement, export a validation function in a companion *test package. This lets implementers verify correctness without duplicating your test logic.

// Package storagetest provides acceptance tests for storage.Backend.
package storagetest

// Verify runs a validation suite against any storage.Backend.
// Returns an error describing the first violation, or nil on success.
func Verify(b storage.Backend) error {
    if err := verifyRoundTrip(b); err != nil {
        return fmt.Errorf("round-trip: %w", err)
    }
    if err := verifyNotFound(b); err != nil {
        return fmt.Errorf("not-found: %w", err)
    }
    return nil
}

Callers write a thin test that plugs in their implementation:

func TestMyBackend(t *testing.T) {
    b := mybackend.New(t)
    if err := storagetest.Verify(b); err != nil {
        t.Errorf("MyBackend failed acceptance: %v", err)
    }
}

---

Designing Extensible Validation Functions

*Return errors, not `testing.T failures.** This keeps validation functions usable as plain Go functions — callers decide whether a violation is t.Error or t.Fatal`.

// Good: Returns error — caller controls test flow
func ExercisePlayer(b *chess.Board, p chess.Player) error {
    move := p.Move()
    if putsOwnKingIntoCheck(b, move) {
        return &IllegalMoveError{Move: move, Reason: "puts own king in check"}
    }
    return nil
}

// Bad: Calls t.Fatal — caller loses control
func ExercisePlayer(t *testing.T, b *chess.Board, p chess.Player) {
    t.Helper()
    move := p.Move()
    if putsOwnKingIntoCheck(b, move) {
        t.Fatalf("illegal move: %v puts own king in check", move)
    }
}

Use custom error types for rich diagnostics when needed:

type IllegalMoveError struct {
    Move   chess.Move
    Reason string
}

func (e *IllegalMoveError) Error() string {
    return fmt.Sprintf("illegal move %v: %s", e.Move, e.Reason)
}

---

When to Use Validation APIs vs Simple Helpers

Validation APIs are worth the extra package when:

• Multiple external packages will implement your interface
• The contract has non-obvious invariants that are easy to get wrong
• You want a single source of truth for "correct behavior"

Simple helpers are better when:

• The helper is a straightforward setup or comparison function
• The reuse is incidental, not part of a published contract

---

Naming Conventions

Name the function with a verb that signals scope: Verify, Exercise, RunConformance. Accept the interface under test as a parameter — never construct the implementation inside the validation package.