Table-Driven Test Guidelines

Table-driven tests define multiple test cases in a slice of structs, then iterate over them executing the same test logic. This makes it easy to add cases, improves readability, and reduces duplication.

When to use table-driven tests:

• You have 3+ similar test cases that vary by inputs/outputs

• Tests follow the same logic pattern with different data

• Most unit and integration tests benefit from this structure

When to skip:

• Only 1-2 simple test cases (overhead not worth it)

• Each test requires completely different logic

• Test setup/teardown varies significantly between cases

Not the same as: Datadriven tests (different library with testdata files)

Basic Structure

func TestMyFunction(t *testing.T) { tests := []struct { name string input string expectedLen int }{ {name: "basic case", input: "hello", expectedLen: 5}, {name: "empty input", input: "", expectedLen: 0}, }

for _, tc := range tests {
    t.Run(tc.name, func(t *testing.T) {
        result, err := MyFunction(tc.input)
        require.NoError(t, err)
        require.Equal(t, tc.expectedLen, result)
    })
}

}

Core Principles

1. Only Specify What's Necessary

Bad:

{ name: "remap table", tableID: 100, tableName: "users", schemaID: 1, schemaName: "public", databaseID: 50, databaseName: "mydb", expectedID: 51, // only this is actually tested! }

Good:

{name: "remap table", tableID: 100, expectedID: 51}

2. Struct Field Ordering: Inputs First, Then Expected

Order struct fields with input fields at the top and verification fields at the bottom. Prefix all verification fields with expected so readers can immediately distinguish inputs from outputs.

Bad:

tests := []struct { name string wantErr bool // verification mixed with inputs input string output int // unclear if this is input or verification }

Good:

tests := []struct { name string input string expectedCount int expectedErr string }

3. One Concern Per Test Case

Bad:

{ name: "multiple behaviors", input: map[int]int{ 10: 60, // normal remapping 49: 99, // edge case 50: 50, // system table preservation }, }

Good:

{name: "normal remapping", input: map[int]int{10: 60}}, {name: "preserve system table IDs under 50", input: map[int]int{49: 49}}, {name: "remap IDs at or above 50", input: map[int]int{50: 100}},

4. Independent Test Cases

Each case should be self-contained. Don't build dependent state across cases.

5. Names Describe Intent, Not Inputs

Test case names should hint at the intention or scenario, not duplicate the input data. A reader should understand what the case is testing from the name alone.

• Good: "two matched regions" , "error on negative input"

• Bad: "match region x and y" , "test1" , "input_abc"

The name should answer "what scenario is this?" not "what data does this use?"

Assertions

Use require.* (stops on failure) for most checks. Use assert.* (continues on failure) only when you want to see multiple failures.

Common patterns:

// Errors require.NoError(t, err) require.Error(t, err) require.ErrorContains(t, err, "not found")

// Equality require.Equal(t, expected, actual) // shows both values on failure require.True(t, result == expected) // don't do this - hides values

// Collections require.Len(t, slice, expectedLen) require.Contains(t, slice, element)

Avoid redundant nil checks: Don't use require.NotNil before an assertion that will already fail on nil (like require.Equal or require.Contains ). The subsequent assertion provides a clearer failure message anyway.

// Bad: redundant nil check require.NotNil(t, result) require.Equal(t, expectedVal, result.Field)

// Good: Equal already fails clearly if result is nil require.Equal(t, expectedVal, result.Field)

Error handling in test cases:

tests := []struct { name string input string expectedErr string }{ {name: "valid input", input: "hello"}, {name: "empty input rejected", input: "", expectedErr: "must not be empty"}, }

for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { err := Validate(tc.input) if tc.expectedErr != "" { require.ErrorContains(t, err, tc.expectedErr) } else { require.NoError(t, err) } }) }

Variadic Helper Functions

Use helpers to reduce boilerplate and make test data readable.

Example from CockroachDB (pkg/backup/compaction_dist_test.go ):

// Helper types type mockEntry struct { span roachpb.Span locality string }

// Variadic helpers func entry(start, end string, locality string) mockEntry { return mockEntry{ span: mockSpan(start, end), locality: locality, } }

func entries(specs ...mockEntry) []execinfrapb.RestoreSpanEntry { var entries []execinfrapb.RestoreSpanEntry for _, s := range specs { var dir cloudpb.ExternalStorage if s.locality != "" { dir = cloudpb.ExternalStorage{ URI: "nodelocal://1/test?COCKROACH_LOCALITY=" + s.locality, } } entries = append(entries, execinfrapb.RestoreSpanEntry{ Span: s.span, Files: []execinfrapb.RestoreFileSpec{{Dir: dir}}, }) } return entries }

// Usage - reads like a specification entries := entries( entry("a", "b", "dc=dc1"), entry("c", "d", "dc=dc2"), entry("e", "f", "dc=dc3"), )

When to create helpers:

• Complex struct initialization obscures test intent

• Patterns repeat across test cases

• Building composite data structures

When NOT to use:

• Simple values that don't need transformation

• One-off test cases

• Helpers add more complexity than they remove

Integration Tests

For tests requiring a database server, see the /integration-test skill. The table-driven patterns here apply to both unit and integration tests.