Go Testing skill for Codex

Good Go tests are plain functions with table-driven cases, readable failure messages that show got and want, -race clean, parallel where state allows, and runnable one case at a time with -run.

Inspect first

1. Read AGENTS.md and the Makefile/Taskfile for the canonical test target (tags, -race, -count=1, integration env vars).
2. Check the go directive in go.mod. Features below are gated: loop-variable per iteration (1.22), b.Loop and t.Context (1.24), testing/synctest.Test (1.25).
3. See whether the repo already uses testify, go-cmp, or neither. Follow the existing choice; do not mix assertion styles in one package.
4. Note build tags such as //go:build integration that hide tests from a plain run.

Table-driven tests

func TestParseDuration(t *testing.T) {
	tests := []struct {
		name    string
		in      string
		want    time.Duration
		wantErr bool
	}{
		{name: "minutes", in: "5m", want: 5 * time.Minute},
		{name: "compound", in: "1h30m", want: 90 * time.Minute},
		{name: "empty string", in: "", wantErr: true},
		{name: "missing unit", in: "10", wantErr: true},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			t.Parallel()
			got, err := ParseDuration(tt.in)
			if (err != nil) != tt.wantErr {
				t.Fatalf("ParseDuration(%q) error = %v, wantErr %v", tt.in, err, tt.wantErr)
			}
			if got != tt.want {
				t.Errorf("ParseDuration(%q) = %v, want %v", tt.in, got, tt.want)
			}
		})
	}
}

• Failure messages follow Func(input) = got, want want. A reader should not need the source to understand the failure.
• t.Fatalf when continuing is pointless (nil result); t.Errorf to report several mismatches in one run.
• Subtest names become -run patterns with spaces turned into underscores: go test -run 'TestParseDuration/empty_string' ./....
• Since Go 1.22 the loop variable is per-iteration, so tt := tt is no longer needed. Remove it only if go.mod says 1.22 or later.
• For errors, compare with errors.Is(err, ErrNotFound) or errors.As, never string matching.

Helpers, cleanup, temp state

func newTestStore(t *testing.T) *Store {
	t.Helper()                               // failures point at the caller's line
	dir := t.TempDir()                       // removed automatically
	s, err := Open(filepath.Join(dir, "db"))
	if err != nil {
		t.Fatalf("open store: %v", err)
	}
	t.Cleanup(func() { s.Close() })
	return s
}

• t.Setenv and t.Chdir change process state and panic in parallel tests; do not combine them with t.Parallel().
• t.Context() (1.24) returns a context canceled just before cleanup; use it instead of context.Background() so leaked goroutines see cancellation.
• TestMain(m *testing.M) only for package-wide setup such as starting one container; since Go 1.15 just call m.Run() and return, so deferred teardown still runs (os.Exit would skip it).

Comparing values

Need	Use
Scalars, small structs	== or reflect.DeepEqual with a clear message
Structs, slices, maps with a readable diff	github.com/google/go-cmp/cmp: if d := cmp.Diff(want, got); d != "" { t.Errorf("mismatch (-want +got):\n%s", d) }
Ignore fields, sort slices	cmpopts.IgnoreFields, cmpopts.SortSlices, cmpopts.EquateApproxTime
Team already uses testify	require for preconditions that must stop the test, assert for checks; never use assert where a nil dereference follows

Avoid testify/suite for new code: it fights t.Parallel and subtests. Avoid testify/mock expectations for simple interfaces; a hand-written fake struct is shorter and type-checked.

HTTP handlers and clients

func TestGetUser(t *testing.T) {
	srv := NewServer(fakeRepo{users: map[string]User{"42": {ID: "42", Name: "Ada"}}})

	req := httptest.NewRequest(http.MethodGet, "/users/42", nil)
	rec := httptest.NewRecorder()
	srv.ServeHTTP(rec, req)

	if rec.Code != http.StatusOK {
		t.Fatalf("status = %d, want 200; body: %s", rec.Code, rec.Body)
	}
}

For clients, start httptest.NewServer(handler) and point the client at srv.URL; close it with t.Cleanup(srv.Close).

Golden files

var update = flag.Bool("update", false, "rewrite golden files")

func TestRender(t *testing.T) {
	got := Render(input)
	golden := filepath.Join("testdata", t.Name()+".golden")
	if *update {
		os.MkdirAll(filepath.Dir(golden), 0o755)
		os.WriteFile(golden, got, 0o644)
	}
	want, err := os.ReadFile(golden)
	if err != nil {
		t.Fatal(err)
	}
	if d := cmp.Diff(string(want), string(got)); d != "" {
		t.Errorf("Render mismatch (-want +got):\n%s", d)
	}
}

Run go test ./pkg -run TestRender -update, then review the diff in git diff testdata/ before committing. Never update goldens just to make CI green.

Time-dependent code

Inject a clock interface first. For code that uses time.Sleep, timers or tickers internally, Go 1.25’s testing/synctest runs the test in a bubble with a fake clock:

func TestCacheExpires(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		c := NewCache(time.Minute)
		c.Set("k", "v")
		time.Sleep(61 * time.Second)   // advances instantly inside the bubble
		synctest.Wait()                // let background goroutines settle
		if _, ok := c.Get("k"); ok {
			t.Fatal("entry should have expired")
		}
	})
}

On Go 1.24 the experimental API needs GOEXPERIMENT=synctest and uses synctest.Run.

Fuzzing

func FuzzParseDuration(f *testing.F) {
	for _, seed := range []string{"5m", "1h30m", "", "-0s"} {
		f.Add(seed)
	}
	f.Fuzz(func(t *testing.T, s string) {
		d, err := ParseDuration(s)
		if err != nil {
			return
		}
		if back, err := ParseDuration(d.String()); err != nil || back != d {
			t.Errorf("round trip %q -> %v -> %v (%v)", s, d, back, err)
		}
	})
}

go test -run=^$ -fuzz=FuzzParseDuration -fuzztime=60s ./pkg/timeparse

Failing inputs land in testdata/fuzz/FuzzParseDuration/; commit them so they run as regular cases in every go test. For long campaigns and corpus management, hand off to $fuzz-testing.

Benchmarks

func BenchmarkEncode(b *testing.B) {
	payload := makePayload()
	for b.Loop() {                 // Go 1.24+: setup excluded, result kept alive
		Encode(payload)
	}
}

Compare runs with go test -bench=Encode -count=10 > new.txt and benchstat old.txt new.txt (benchstat needs go install golang.org/x/perf/cmd/benchstat@latest, which requires network).

Running

go test ./...                                   # all packages
go test -race -count=1 -shuffle=on ./...        # no cache, random order, race detector
go test -run 'TestParseDuration/compound' -v ./pkg/timeparse
go test -tags=integration ./...                 # include tagged tests
go test -short ./...                            # tests check testing.Short() to skip slow paths
go test -coverprofile=cover.out ./... && go tool cover -func=cover.out

-count=1 disables the test cache; use it when tests read files or env vars that Go does not track.

Gotchas

• t.Parallel() in the parent and subtests: the parent’s deferred cleanup runs before parallel subtests finish. Use t.Cleanup, which waits.
• Calling t.Fatal from a goroutine other than the test’s does not stop the test; send errors back on a channel.
• Shared package-level maps or fakes plus t.Parallel() produce -race failures; build fresh fakes per subtest.
• External test packages (package foo_test) test the public API; internal ones (package foo) can reach unexported code. Prefer _test packages for behavior tests.

Verification

1. go vet ./... and go test -race -count=1 -shuffle=on ./... pass.
2. Each new subtest can be run alone via -run.
3. Break the behavior under test once and confirm the message shows got and want clearly.
4. Fuzz targets run at least 30 seconds locally without new failures.