Go Test Flags You Should Know and When to Use Them

A reference of the go test flags worth memorising: selecting tests, repeating, failing fast, shuffling, timing, coverage, race and output, with real examples.

5 min read

Summarize in AI

Quick Summary

The go test flags that matter fall into groups: choose tests with -run, -skip and -short; repeat with -count and -cpu; fail fast with -failfast and -timeout; reorder with -shuffle; look inside with -v, -json and -race; measure with -cover and -bench. Flags before a package list belong to go test, and flags after -args go to your test binary.

Key takeaways

go test -list . printed the five test names without running them, which is the quickest way to check what a -run pattern will match.
-run Beta -short ran TestBeta and reported TestBetaSlow as skipped, because that test checks testing.Short().
-skip 'Beta|FailEarly' left only TestAlpha and TestGamma; -skip arrived in Go 1.20.
-failfast stopped after TestFailEarly, and TestGamma never ran.
go test -c compiled a test binary, and ./t.bin -test.run FailEarly -test.v ran it with the -test. prefix on every flag.

go test has dozens of flags and a working set of about fifteen. This page is the reference for that set: what each flag does, a command to copy and the surprise that goes with it. The examples ran on Go 1.25.6 against a file with five tests, and the output below is from that run.

Tested with Go 1.25.6, macOS on Apple Silicon (arm64)

The test file

main.goGo

package main

func main() {}

flags_test.goGo

package main

import "testing"

func TestAlpha(t *testing.T) { t.Log("alpha") }
func TestBeta(t *testing.T)  { t.Log("beta") }
func TestBetaSlow(t *testing.T) {
	if testing.Short() {
		t.Skip("short mode")
	}
	t.Log("slow beta")
}
func TestFailEarly(t *testing.T) { t.Fatal("stop here") }
func TestGamma(t *testing.T)     { t.Log("gamma") }

Shell

G='s/\t[0-9.]+s//; s/ \([0-9.]+s\)//'
echo '$ go test -list .'; go test -list . | sed -E "$G"
echo; echo '$ go test -v -run Beta -short'; go test -count=1 -v -run Beta -short . | grep -E '^(---|ok|PASS)' | sed -E "$G"
echo; echo '$ go test -v -skip "Beta|FailEarly"'; go test -count=1 -v -skip 'Beta|FailEarly' . | grep -E '^(---|ok)' | sed -E "$G"
echo; echo '$ go test -failfast -v'; go test -count=1 -failfast -v . | grep -E '^(---|FAIL|ok)' | sed -E "$G"
echo; echo '$ go test -run FailEarly -c -o t.bin && ./t.bin -test.v'; go test -c -o t.bin . && ./t.bin -test.run FailEarly -test.v | grep -E '^(---|FAIL)' | sed -E "$G"

Text

$ go test -list .
TestAlpha
TestBeta
TestBetaSlow
TestFailEarly
TestGamma
ok  	example.test/lab

$ go test -v -run Beta -short
--- PASS: TestBeta
--- SKIP: TestBetaSlow
PASS
ok  	example.test/lab

$ go test -v -skip "Beta|FailEarly"
--- PASS: TestAlpha
--- PASS: TestGamma
ok  	example.test/lab

$ go test -failfast -v
--- PASS: TestAlpha
--- PASS: TestBeta
--- PASS: TestBetaSlow
--- FAIL: TestFailEarly
FAIL
FAIL	example.test/lab
FAIL

$ go test -run FailEarly -c -o t.bin && ./t.bin -test.v
--- FAIL: TestFailEarly
FAIL

Choosing tests

Flag	Use it to	Note
`-run regexp`	Run tests whose name matches	Unanchored, so `-run Beta` also matches `TestBetaSlow`. Anchor with `^TestBeta$`
`-run 'A/b'`	Match a subtest	Slash separates levels, each level is its own regexp
`-skip regexp`	Leave tests out	Added in Go 1.20; same syntax as `-run`
`-list regexp`	Print matching names without running	Also lists examples and benchmarks; check a `-run` pattern before a long run
`-short`	Set `testing.Short()`	Opt-in: only tests that check it skip
`-fuzz regexp`	Fuzz one target	Must match exactly one target in one package

In the recorded run, -list . printed the five test names and exited. -run Beta -short ran TestBeta, and TestBetaSlow skipped itself because it checks testing.Short(). -skip 'Beta|FailEarly' left TestAlpha and TestGamma. Use -list first when you are not sure what a pattern selects, particularly with subtests, where the pattern applies per level.

Repeating and varying

Flag	Use it to	Note
`-count N`	Run each test N times	`-count=1` also bypasses the test cache; see the cache article
`-cpu 1,2,4`	Run with each `GOMAXPROCS` value	Each value is a full pass
`-shuffle on` or a seed	Randomise test order	Prints the seed on failure for replay
`-parallel N`	Cap concurrently running parallel tests	Defaults to `GOMAXPROCS`
`-p N`	Cap packages tested at once	Different from `-parallel`: processes, not tests

These are the flaky-test hunting flags; the method for combining them is in the flaky tests guide.

Stopping early and bounding time

Flag	Use it to	Note
`-failfast`	Stop after the first failure	Applies within a package; other packages still run
`-timeout 30s`	Abort a hung run with a goroutine dump	Default is 10 minutes; `0` disables it
`-benchtime 5s` or `100x`	Set benchmark length	A count with `x` runs exactly that many iterations

The -failfast run printed FAIL after TestFailEarly and never reached TestGamma. Set -timeout in CI to a value just above the suite's normal time, so a deadlock fails in minutes and not ten of them.

Looking inside

Flag	Use it to	Note
`-v`	Print every test as it runs, with `t.Log` output	Without it, passing tests print nothing
`-json`	Emit one JSON event per line	For tools; see the JSON output note
`-race`	Enable the race detector	Needs cgo; slows the run down by several times
`-cover`, `-coverprofile f`	Measure statement coverage	See the coverage article
`-covermode set,count,atomic`	Pick how counts are kept	`-race` implies `atomic`
`-coverpkg ./...`	Count coverage in other packages	Needed when one package's tests drive another
`-cpuprofile`, `-memprofile`	Write profiles	Used with benchmarks; see the benchmark guide
`-trimpath`	Remove local paths from output	Makes recorded output reproducible

Building without running

go test -c -o t.bin ./pkg compiles the test binary and stops. Run it with ./t.bin -test.run FailEarly -test.v. Every flag takes the -test. prefix when you call the binary directly, and the recorded run shows TestFailEarly failing the same way. A compiled test binary starts instantly, can be copied to another machine, and is how you repeat a test hundreds of times without rebuilding. go vet runs automatically before tests with a small set of checks; -vet=off disables it and -vet=all runs every analyzer.

Passing flags to the binary

Flags that go test does not know belong to your test binary and are passed after the package list or after -args. A custom flag declared with the flag package in a test file is given as go test ./pkg -args -myflag=1. Anything after -args goes through untouched, which is the reliable form. Flags before the package list are go test's own, and the Go 1.20 release notes are where -skip was announced. When a command works locally and not in CI, compare the two GOFLAGS values first.

Environment variables that affect tests

Variable	Effect
`GOFLAGS`	Default flags for every go command, such as `-count=1` in CI
`GOMAXPROCS`	The default for `-cpu`
`GORACE`	Race detector options, such as `halt_on_error=1`
`GOCOVERDIR`	Where instrumented binaries write coverage data
`GOCACHE`	Where results and builds are cached

Boundaries

This list leaves out flags that are rarely needed, such as -blockprofile, -mutexprofile, -outputdir, -fullpath and the fuzzing tuning flags. go help testflag lists every one, and the cmd/go testing flags reference is the same text on the web. The testing hub article shows how the flags fit into a working practice.

Also inTooling

Taggedcheatsheet