rgoussu.dev
rgoussu@goussu: ~/library/go/toolchain
❯ ~/library/go/toolchain cat go-test.md

go test

# The built-in test runner — test binary model, run/bench/fuzz selectors, caching, race detection, and coverage flags.

Conceptsaved 2026-08-09 #go#tooling#testing

Overview

go test compiles each package's _test.go files together with the package into a test binary, then runs it — there is no external runner, no framework to pick. This note covers the command; testing strategy (what to test, how to structure it) lives under /go/testing/.

Key points

  • Test binary model: a generated TestMain/testmain harness calls every TestXxx, BenchmarkXxx, FuzzXxx; go test -c emits the binary itself, runnable on another machine — handy for embedded targets and containers.
  • Selectors: -run 'TestName/subtest' (regexp over test and subtest names), -bench . for benchmarks (off by default), -fuzz FuzzX for native fuzzing (1.18+).
  • Test cache: passing results are cached per package+inputs; unchanged packages report (cached) instantly. -count=1 forces re-run (the idiomatic "no cache" flag); -count=N also repeats tests to shake out flakes.
  • -race is the flag that earns its keep: run it in CI for any concurrent code.
  • -timeout (default 10m) panics with full goroutine dumps on hang — often the fastest deadlock diagnosis you'll get.
  • Coverage: -cover for the percentage, -coverprofile=c.out for a profile handed to go tool cover; -covermode=atomic when combined with -race.
  • -v, -short, -shuffle on: verbose output, skip slow tests guarded by testing.Short(), randomize execution order to catch inter-test coupling.
  • Table tests fit the tool: one TestXxx iterating cases with t.Run(name, …) gives each case its own selector path and parallelism (t.Parallel()) — the runner's model and the community idiom reinforce each other.

Examples

go test ./...                                   # everything, cached
go test -race -count=1 -timeout 2m ./...        # CI gate
go test -run 'TestParse/empty_input' -v ./pkg   # one subtest
go test -bench BenchmarkDecode -benchmem ./codec

Related