go test: Usage, Options & Common CI Errors

Run your Go test suite, optionally with the race detector.

go test compiles and runs test functions in *_test.go files. In CI you typically add -race to catch data races and -count=1 to defeat test result caching.

What it does

Builds a test binary per package and runs it, reporting pass/fail and optional coverage. Results are cached; an unchanged package shows (cached) on a re-run unless you force re-execution.

Common usage

go test ./...                     # test every package
go test -run TestLogin ./auth     # filter by name regex
go test -race ./...               # enable the race detector
go test -cover ./...              # report coverage
go test -count=1 ./...            # bypass the test cache

Common CI error: data race only fails with -race

Tests pass locally but go test -race ./... fails in CI with "WARNING: DATA RACE" because concurrent access to shared state is only detected under the race detector. Fix: synchronize the shared access (mutex, channel, or atomic); do not drop -race - it is the gate catching a real bug. For "panic: test timed out", raise -timeout or fix the hang.

Options

Related guides