go-test-table-driven

Go Table-Driven Tests

Table-driven tests are a powerful Go idiom — when used correctly. Most codebases either underuse them (10 copy-paste tests) or overuse them (complex branching logic in a 200-line struct). This skill covers the sweet spot.

Detailed reference material, loaded on demand:

• references/patterns.md — full worked examples: canonical tables, wantErr/wantErrIs, parallel tables, map-based tables, error-only tables, struct alignment for readability.
• references/refactoring.md — recognizing bloated tables and rewriting them as explicit subtests, with before/after examples.

Read a reference file only when the summary below is not enough for the task at hand.

1. When Table-Driven Tests Shine

Use a table only when ALL of these are true:

• Same function under test across all cases
• Same assertion pattern — input in, output out, compare
• Cases differ only in data, not in setup or verification logic
• 3+ cases — fewer than 3, explicit tests are clearer

Canonical use case: pure functions, parsers, validators, formatters.

func TestParseSize(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        want    int64
        wantErr bool
    }{
        {name: "plain bytes", input: "1024", want: 1024},
        {name: "kilobytes suffix", input: "4KB", want: 4096},
        {name: "empty string", input: "", wantErr: true},
        {name: "negative size", input: "-1", wantErr: true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := ParseSize(tt.input)
            if tt.wantErr {
                require.Error(t, err)
                return
            }
            require.NoError(t, err)
            assert.Equal(t, tt.want, got)
        })
    }
}

Every case has the same shape, the loop body is a few lines, and adding a case is one struct literal. No branching, no conditionals.

2. When NOT to Use Table-Driven Tests

• Complex per-case setup — setupMock/setupFunc function fields in the struct mean the table is hiding complexity. Write explicit subtests.
• Fewer than 3 cases — the struct definition is more code than two plain test functions.
• Multiple branching paths — if tt.shouldError / if tt.wantRedirect in the loop body means each branch is a different test pretending to share a structure. Split it.