go-testing

Go Testing

Tests are executable specifications. Their job is to fail usefully when behaviour regresses — and to keep failing in the same way until the bug is fixed. Tests that are passing-or-flaky teach the team to ignore them, which is worse than no test at all.

Core Rules

1. Failures must be diagnosable from the log alone. Every t.Errorf includes the function under test, the inputs, what we got, and what we wanted, in that order.
2. No assertion libraries by default. Use the standard t.Errorf / t.Fatalf plus go-cmp for structural comparison. testify is acceptable when adopted consistently — pick one and stick with it.
3. Test observable behaviour, not implementation details. If a refactor that preserves behaviour breaks the test, the test was wrong.
4. Each test runs independently. No execution-order dependencies, no shared global state without t.Cleanup.
5. t.Parallel() whenever the test is safe to run in parallel. Most are.
6. t.Helper() is the first line of any helper function that calls t.Errorf/t.Fatalf. Reserve t.Fatal for "next line is meaningless without this value"; everything else uses t.Error. Never call t.Fatal/t.FailNow from a non-test goroutine — send the failure back via channel.

"Useful Failures" Format

The failure message is the test's user interface. The canonical shape:

FunctionUnderTest(input) = got, want want

// Good
t.Errorf("Add(2, 3) = %d, want %d", got, 5)

// Bad — no function, no inputs, reversed
t.Errorf("expected %d but got %d", 5, got)

Always print got before want. With cmp.Diff(want, got), the diff shows (-want +got) — echo that direction in your message.

"No Asserts" Philosophy

Standard-library testing with if + t.Errorf reads as plain Go and produces messages you control. Assertion libraries shorten call sites but trade away message quality and reorder the got/want convention.

• Default — if got != want { t.Errorf("...") } plus cmp.Diff for structs, slices, maps, protos.
• Permitted — testify if the team agrees and testifylint is enabled. require only when continuing is meaningless.
• Avoid — mixing styles within the same package.