Table tests, subtests and parallel tests

A table test is a slice of cases and one loop. Each case has a name, the inputs and the expected result, and t.Run turns it into a subtest with its own name, its own failure and its own line in the output. It is the shape most Go code uses, because adding a case is one line and a failure says which case it was. The previous lesson wrote one test per behaviour; this one writes one test per table.

The table

The anonymous struct inside the slice keeps the case fields next to the values and needs no type declaration outside the test. The loop names the variable tc and passes it to t.Run, so the subtest name is the case name and the failure output is TestDivide/zero_denominator. Spaces become underscores in the name, which is what -run matches against.

package calc import ( "errors" "testing" ) func TestDivide(t *testing.T) { cases := []struct { name string a, b int want int wantErr error }{ {"even", 10, 2, 5, nil}, {"truncates", 7, 2, 3, nil}, {"zero denominator", 1, 0, 0, ErrDivideByZero}, {"negative", -8, 2, -4, nil}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { got, err := Divide(tc.a, tc.b) if !errors.Is(err, tc.wantErr) { t.Fatalf("Divide(%d, %d) error = %v, want %v", tc.a, tc.b, err, tc.wantErr) } if got != tc.want { t.Errorf("Divide(%d, %d) = %d, want %d", tc.a, tc.b, got, tc.want) } }) } } func TestClamp(t *testing.T) { cases := []struct { name string v, lo, hi int want int }{ {"inside", 5, 1, 10, 5}, {"below", 0, 1, 10, 1}, {"above", 11, 1, 10, 10}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { if got := Clamp(tc.v, tc.lo, tc.hi); got != tc.want { t.Errorf("Clamp(%d, %d, %d) = %d, want %d", tc.v, tc.lo, tc.hi, got, tc.want) } }) } }

go test -v .

=== RUN TestDivide
=== RUN TestDivide/even
=== RUN TestDivide/truncates
=== RUN TestDivide/zero_denominator
=== RUN TestDivide/negative
--- PASS: TestDivide (0.00s)
--- PASS: TestDivide/even (0.00s)
--- PASS: TestDivide/truncates (0.00s)
--- PASS: TestDivide/zero_denominator (0.00s)
--- PASS: TestDivide/negative (0.00s)
=== RUN TestClamp
=== RUN TestClamp/inside
=== RUN TestClamp/below
=== RUN TestClamp/above
--- PASS: TestClamp (0.00s)
--- PASS: TestClamp/inside (0.00s)
--- PASS: TestClamp/below (0.00s)
--- PASS: TestClamp/above (0.00s)
PASS
ok example.com/calc (cached)

Seven subtests ran and passed, each with its own line. t.Errorf inside a subtest fails that subtest and lets the others run, so one go test reports every broken case in the table instead of stopping at the first.

Running one case

go test -run TestDivide/zero runs only the subtests whose name matches, which turns a table into a set of independently runnable cases. The pattern is a regular expression, so -run TestDivide/(even|negative) selects two of them. This is the practical reason to name cases well: the name is the handle a developer uses while debugging.

package calc import ( "errors" "testing" ) func TestDivide(t *testing.T) { cases := []struct { name string a, b int want int wantErr error }{ {"even", 10, 2, 5, nil}, {"truncates", 7, 2, 3, nil}, {"zero denominator", 1, 0, 0, ErrDivideByZero}, {"negative", -8, 2, -4, nil}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { got, err := Divide(tc.a, tc.b) if !errors.Is(err, tc.wantErr) { t.Fatalf("Divide(%d, %d) error = %v, want %v", tc.a, tc.b, err, tc.wantErr) } if got != tc.want { t.Errorf("Divide(%d, %d) = %d, want %d", tc.a, tc.b, got, tc.want) } }) } } func TestClamp(t *testing.T) { cases := []struct { name string v, lo, hi int want int }{ {"inside", 5, 1, 10, 5}, {"below", 0, 1, 10, 1}, {"above", 11, 1, 10, 10}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { if got := Clamp(tc.v, tc.lo, tc.hi); got != tc.want { t.Errorf("Clamp(%d, %d, %d) = %d, want %d", tc.v, tc.lo, tc.hi, got, tc.want) } }) } }

go test -v -run TestDivide/zero .

=== RUN TestDivide
=== RUN TestDivide/zero_denominator
--- PASS: TestDivide (0.00s)
--- PASS: TestDivide/zero_denominator (0.00s)
PASS
ok example.com/calc (cached)

One subtest ran and the parent test still reported PASS, because the filter excluded the rest. A filter that matches nothing is not an error: the package reports ok with no tests run, which is worth knowing when a CI job claims success too quickly.

Parallel subtests

t.Parallel pauses the subtest and lets the others start, then runs the paused ones together up to -parallel, which defaults to the number of CPUs. The cases must be independent: shared state, a shared temporary file or an environment variable makes the result depend on scheduling. The tc := tc line was needed before Go 1.22 and is harmless now; with the per-iteration variable it is redundant but common in older code.

package calc import "testing" func TestDivideTable(t *testing.T) { cases := []struct { name string a, b int want int }{ {"ten", 100, 10, 10}, {"nine", 81, 9, 9}, {"one", 4, 4, 1}, } for _, tc := range cases { tc := tc t.Run(tc.name, func(t *testing.T) { t.Parallel() if got := Clamp(tc.a/tc.b, -100, 100); got != tc.want { t.Errorf("got %d, want %d", got, tc.want) } }) } }

go test -v .

=== RUN TestDivideTable
=== RUN TestDivideTable/ten
=== PAUSE TestDivideTable/ten
=== RUN TestDivideTable/nine
=== PAUSE TestDivideTable/nine
=== RUN TestDivideTable/one
=== PAUSE TestDivideTable/one
=== CONT TestDivideTable/ten
=== CONT TestDivideTable/one
=== CONT TestDivideTable/nine
--- PASS: TestDivideTable (0.00s)
--- PASS: TestDivideTable/ten (0.00s)
--- PASS: TestDivideTable/one (0.00s)
--- PASS: TestDivideTable/nine (0.00s)
PASS
ok example.com/calc (cached)

The output shows === PAUSE for each subtest and a CONT line when it resumed, and the total time is not the sum of the cases because they overlapped. A test with t.Parallel must not call t.Setenv or change a package-level variable, and the race detector is what proves it does not.

A failure that names its case

The last table has one wrong expectation, and the output points at the subtest that failed rather than at the loop. That is the whole value of t.Run: a table with forty cases reports the two broken ones by name, and a reader does not have to count iterations to find them.

package calc import "testing" func TestClampBounds(t *testing.T) { cases := []struct { name string v, lo, hi int want int }{ {"inside", 5, 1, 10, 5}, {"below", 0, 1, 10, 1}, {"above", 11, 1, 10, 12}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { if got := Clamp(tc.v, tc.lo, tc.hi); got != tc.want { t.Errorf("Clamp(%d, %d, %d) = %d, want %d", tc.v, tc.lo, tc.hi, got, tc.want) } }) } }

go test -v .

=== RUN TestClampBounds
=== RUN TestClampBounds/inside
=== RUN TestClampBounds/below
=== RUN TestClampBounds/above
fail_test.go:19: Clamp(11, 1, 10) = 10, want 12
--- FAIL: TestClampBounds (0.00s)
--- PASS: TestClampBounds/inside (0.00s)
--- PASS: TestClampBounds/below (0.00s)
--- FAIL: TestClampBounds/above (0.00s)
FAIL
FAIL example.com/calc 0.004s
FAIL

The failing subtest printed its case name, the call and both numbers, and the run ended with FAIL and exit status 1. Write the expectation as the second number a reader would check, not as a copy of the output the code produced, or the test proves only that the code does what it does.

Exercises

  1. Add a case to the divide table for a negative denominator and run only that case with -run.
  2. Make the clamp table parallel and run the package with -race. What would break if two cases shared a temporary file?
  3. Turn the three clamp cases into one table with a wantErr field for a function that can fail. How does the table express the two kinds of failure?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What makes a table test a table test?

    Answer

    A slice of cases with names and one loop that runs them as subtests

    The cases are data and the loop is the only executable part.

  2. What does t.Run give each case?

    Answer

    A named subtest with its own failure output

    The name is the handle for -run and for the failure line.

  3. How does -run select a subtest?

    Answer

    A regular expression matched against TestName/subtest

    The pattern is a regexp over the full subtest name.

  4. What does t.Parallel do?

    Answer

    Pauses the subtest and runs it alongside the other paused ones

    The runner batches paused subtests up to the -parallel limit.

  5. Which state makes a parallel subtest unsafe?

    Answer

    State shared with another subtest, such as a package variable or one temporary file

    Parallel cases must not write what another case reads.

  6. What happens when a subtest fails and the others pass?

    Answer

    The parent test fails and the output names the failing subtest

    A failed subtest fails its parent, so go test exits non-zero.

  7. Why write the expected value by hand rather than copying the output?

    Answer

    A copied output proves only that the code still does what it did

    The expectation encodes the contract; the output is what the contract is checked against.

  8. What does go test -run TestDivide/zero match?

    Answer

    The subtests of TestDivide whose name contains zero

    The pattern is matched against the full subtest name.

  9. What does the === PAUSE line in the output mean?

    Answer

    The subtest asked to run in parallel and is waiting for the runner

    PAUSE and CONT show the scheduling of parallel subtests.

  10. How many places does a new case need?

    Answer

    One line in the table slice

    That is the practical advantage of the table shape.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev