The go test command

go test is not a runner that reads test files. It compiles the package and its _test.go files into an ordinary Go binary, runs that binary, and deletes it. Everything else follows from that: the tests are built by the same compiler as the program, the test binary can be kept with -c, and the flags of the testing package reach it after a -test. prefix. The lessons go test, test files and the testing package and table tests and subtests teach the code; this page is about the command a developer and a CI job type, and every run below was made in this container.

The test binary

The package has one file of code and one file of tests. The test file names the package it tests, so it can call unexported functions; the _test suffix is what keeps it out of a normal build.

package calc import "errors" // ErrDivideByZero is returned when the denominator is zero. var ErrDivideByZero = errors.New("divide by zero") // Divide returns a/b, or ErrDivideByZero. func Divide(a, b int) (int, error) { if b == 0 { return 0, ErrDivideByZero } return a / b, nil } // Clamp limits v to the range [lo, hi]. func Clamp(v, lo, hi int) int { if v < lo { return lo } if v > hi { return hi } return v }

package calc import ( "errors" "testing" ) func TestDivide(t *testing.T) { got, err := Divide(10, 2) if err != nil { t.Fatalf("Divide(10, 2): %v", err) } if got != 5 { t.Errorf("Divide(10, 2) = %d, want 5", got) } } func TestDivideByZero(t *testing.T) { _, err := Divide(1, 0) if !errors.Is(err, ErrDivideByZero) { t.Fatalf("Divide(1, 0) error = %v, want ErrDivideByZero", err) } } func TestSlow(t *testing.T) { if testing.Short() { t.Skip("skipping the slow test in short mode") } t.Log("the slow path ran") }

The three tests below pass. The run names each test, prints nothing for a passing one, and ends with ok and the time the binary took.

go test -v ./calc

=== RUN TestDivide
--- PASS: TestDivide (0.00s)
=== RUN TestDivideByZero
--- PASS: TestDivideByZero (0.00s)
=== RUN TestSlow
calc_test.go:29: the slow path ran
--- PASS: TestSlow (0.00s)
PASS
ok example.com/shop/calc 0.004s

-v is passed to the test binary as -test.v. -c stops the command after building and leaves the binary where it is asked to:

go test -c -o calc.test ./calc
du -h calc.test
./calc.test -test.v
./calc.test -test.list '.*'

4.2M calc.test
=== RUN TestDivide
--- PASS: TestDivide (0.00s)
=== RUN TestDivideByZero
--- PASS: TestDivideByZero (0.00s)
=== RUN TestSlow
calc_test.go:29: the slow path ran
--- PASS: TestSlow (0.00s)
PASS
TestDivide
TestDivideByZero
TestSlow

The binary is 4.2 MB because it links the testing package, reflect and the whole runtime, and that is the reason a test build is slower than a normal one. It is also a normal Go program: run it under the race detector, in a debugger or under strace, and it behaves. -test.list prints the test names without running them, which is how a tool learns what a package offers.

The flags that matter

Four flags are enough for daily work and six more are what a CI job adds. The table says what each one changes; the runs below show three of them on the package above.

Flag What it does
-run PATTERN Runs the tests and subtests whose name matches the regular expression.
-short Sets testing.Short(), so a test can skip its slow part.
-count=1 Runs once and does not read a cached result, the honest run before a commit.
-shuffle=on Runs the tests in a random order and prints the seed, which catches order dependence.
-failfast Stops at the first failing test instead of running the rest.
-timeout 30s Kills a run that hangs, after 10 minutes by default, and dumps every goroutine.
-json Writes one JSON object per event instead of the plain text stream.
-race Builds with the race detector, which needs cgo and therefore a C toolchain.
-cover Prints the statement coverage of the package and writes a profile with a file name.
./... The package pattern for every package under the current module.

One test at a time, in a package with several. -run matches the full name, so TestDivide also selects TestDivideByZero, and ^TestDivide$ selects only the first.

go test -run TestDivideByZero -v ./calc

=== RUN TestDivideByZero
--- PASS: TestDivideByZero (0.00s)
PASS
ok example.com/shop/calc 0.007s

go test -short -v ./calc

=== RUN TestDivide
--- PASS: TestDivide (0.00s)
=== RUN TestDivideByZero
--- PASS: TestDivideByZero (0.00s)
=== RUN TestSlow
calc_test.go:27: skipping the slow test in short mode
--- SKIP: TestSlow (0.00s)
PASS
ok example.com/shop/calc 0.004s

A skipped test is not a failure: the package still reports ok. A CI job that wants the slow tests to run simply does not pass -short, and the same binary then takes the other branch.

go test -shuffle=on -v ./calc

-test.shuffle 1794968573684888979
=== RUN TestSlow
calc_test.go:29: the slow path ran
--- PASS: TestSlow (0.00s)
=== RUN TestDivideByZero
--- PASS: TestDivideByZero (0.00s)
=== RUN TestDivide
--- PASS: TestDivide (0.00s)
PASS
ok example.com/shop/calc 0.004s

The seed is printed so a failure can be reproduced with -shuffle=1794968573684888979. Tests that share a package variable or a temporary file fail in one order and pass in another, and shuffling finds them before a user does. The default, -shuffle=off, is what most projects keep for a readable log and turn on in one nightly job.

A second package makes ./... worth using, and this one is small enough to show whole: a map behind a type, with its own test.

package store // Memory is a map-backed key-value store. type Memory struct { data map[string]string } // New returns an empty Memory store. func New() *Memory { return &Memory{data: make(map[string]string)} } // Set stores value under key. func (m *Memory) Set(key, value string) { m.data[key] = value } // Get returns the value and whether the key exists. func (m *Memory) Get(key string) (string, bool) { v, ok := m.data[key] return v, ok }

package store import "testing" func TestMemory(t *testing.T) { s := New() s.Set("a", "1") if got, ok := s.Get("a"); !ok || got != "1" { t.Fatalf("Get(a) = %q, %v; want 1, true", got, ok) } if _, ok := s.Get("b"); ok { t.Error("Get(b) reported a key that was never set") } }

Every package of the module at once, which is what a CI step usually runs:

go test ./...

ok example.com/shop/calc 0.006s
ok example.com/shop/store 0.004s

A failure and its exit status

The test below expects twelve from a clamp that returns ten. It is added to the calc package as a second test file, and -run TestClamp selects it.

package calc import "testing" func TestClamp(t *testing.T) { if got := Clamp(11, 1, 10); got != 12 { t.Errorf("Clamp(11, 1, 10) = %d, want 12", got) } }

go test -run TestClamp -v ./calc; echo "status: $?"

=== RUN TestClamp
broken_test.go:7: Clamp(11, 1, 10) = 10, want 12
--- FAIL: TestClamp (0.00s)
FAIL
FAIL example.com/shop/calc 0.004s
FAIL
status: 1

The failing case prints the file and line of the t.Errorf call, the values it was given, and the run ends with a status of 1. Note the order of the two messages: my sentence comes from the test, and got 10, want 12 is the pair a reader checks. A test that prints only the failing line number sends the reader back to the source; a test that prints both numbers can be understood from the log alone.

Machine-readable output

-json turns the plain stream into events that a CI system parses without guessing. Four lines of one passing test:

go test -json -run TestDivideByZero ./calc | head -4

{"Time":"2026-11-18T02:22:59.333029978Z","Action":"start","Package":"example.com/shop/calc"}
{"Time":"2026-11-18T02:22:59.336895525Z","Action":"run","Package":"example.com/shop/calc","Test":"TestDivideByZero"}
{"Time":"2026-11-18T02:22:59.336940266Z","Action":"output","Package":"example.com/shop/calc","Test":"TestDivideByZero","Output":"=== RUN TestDivideByZero\n"}
{"Time":"2026-11-18T02:22:59.337879482Z","Action":"output","Package":"example.com/shop/calc","Test":"TestDivideByZero","Output":"--- PASS: TestDivideByZero (0.00s)\n"}

The Action field takes the values start, run, output, pause, cont, pass, bench, fail and skip, and a Test field names the test or subtest the event belongs to. That is what the editors and the CI dashboards read; a human still reads the plain output. The Time values differ on every run.

The cache

A passing result is cached, and a second run of an unchanged package prints (cached) after a few milliseconds. The cache key covers the test binary, the environment and the files the test read, so a test that opens a file outside its package makes its own result uncacheable rather than stale.

go test -count=1 ./calc
go test ./calc
go test ./calc
go clean -testcache
go test ./calc

ok example.com/shop/calc 0.005s
ok example.com/shop/calc 0.004s
ok example.com/shop/calc (cached)
ok example.com/shop/calc 0.004s

-count=1 is the way to say "run it again" without clearing anything, and it is what a release checklist should use: a cached pass proves that the code has not changed, which is not the same claim. go clean -testcache clears every cached result on the machine, and go env GOCACHE prints where they live.

The rest of the group: assertions and the libraries compare the standard library with testify, go-cmp and is; httptest, fakes and mocks test a handler and an interface; golden files, fuzzing, benchmarks, the race detector and coverage and go vet, staticcheck and CI take the rest. For the code behind the flags, see the lesson on go test.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev