Table-Driven Tests & Subtests

The pattern

A table test is a slice of anonymous-struct cases, looped with t.Run so each becomes a named subtest:

// reverse_test.go
package strutil

import "testing"

func TestReverse(t *testing.T) {
	cases := []struct {
		name  string
		input string
		want  string
	}{
		{"empty", "", ""},
		{"single", "a", "a"},
		{"word", "abc", "cba"},
		{"palindrome", "level", "level"},
		{"unicode", "héllo", "olléh"},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			got := Reverse(tc.input)
			if got != tc.want {
				t.Errorf("Reverse(%q) = %q, want %q", tc.input, got, tc.want)
			}
		})
	}
}

Running it shows each case by name, and -run can target a single row:

$ go test -v -run TestReverse
=== RUN   TestReverse
=== RUN   TestReverse/empty
=== RUN   TestReverse/word
=== RUN   TestReverse/unicode
--- PASS: TestReverse (0.00s)
    --- PASS: TestReverse/empty (0.00s)
    --- PASS: TestReverse/word (0.00s)
    --- PASS: TestReverse/unicode (0.00s)
PASS

# run just one subtest
$ go test -run TestReverse/unicode

Here is the function under test running over the same inputs in main, printing got vs want — exactly what the table checks, but in a form you can run and edit:

package main

import "fmt"

// Reverse returns s with its runes in reverse order (rune-safe).
func Reverse(s string) string {
r := []rune(s)
for i, j := 0, len(r)-1; i < j; i, j = i+1, j-1 {
	r[i], r[j] = r[j], r[i]
}
return string(r)
}

func main() {
cases := []struct{ input, want string }{
	{"", ""},
	{"a", "a"},
	{"abc", "cba"},
	{"level", "level"},
	{"héllo", "olléh"},
}
for _, c := range cases {
	got := Reverse(c.input)
	status := "ok"
	if got != c.want {
		status = "MISMATCH"
	}
	fmt.Printf("Reverse(%q) = %q want %q  [%s]\n", c.input, got, c.want, status)
}
}

Parallel subtests

t.Parallel() lets independent cases run concurrently. Each subtest signals it’s parallel, then pauses until the parent returns and they all run together:

for _, tc := range cases {
	t.Run(tc.name, func(t *testing.T) {
		t.Parallel() // these subtests run concurrently
		if got := Reverse(tc.input); got != tc.want {
			t.Errorf("Reverse(%q) = %q, want %q", tc.input, got, tc.want)
		}
	})
}

graph TD
T["cases []struct{name,input,want}"] --> L["for _, tc := range cases"]
L --> R["t.Run(tc.name, func(t))"]
R --> S1["subtest: empty"]
R --> S2["subtest: word"]
R --> S3["subtest: unicode"]
S1 --> A["assert got == want"]
S2 --> A
S3 --> A

Slice vs map tables

A slice of cases preserves order and lets cases share a name field — the default choice. A map keyed by name enforces unique names and reads a little cleaner, at the cost of random iteration order:

// Map-keyed: the key is the case name; iteration order is random.
cases := map[string]struct {
	input, want string
}{
	"empty":  {"", ""},
	"word":   {"abc", "cba"},
	"unicode": {"héllo", "olléh"},
}
for name, tc := range cases {
	t.Run(name, func(t *testing.T) {
		if got := Reverse(tc.input); got != tc.want {
			t.Errorf("Reverse(%q) = %q, want %q", tc.input, got, tc.want)
		}
	})
}

Reach for the slice form when order matters or you want deterministic output; the map form when each case is independent and you value the uniqueness guarantee.

See also

• testing basics — the t toolbox, t.Run, t.Cleanup, t.TempDir.
• fuzzing — generate inputs automatically once your table covers the known cases.
• benchmarks — the same row-per-case idea, measured with b.N.

Next: throwing random inputs at your code to find the cases you didn’t list — fuzzing.

Related topics