Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

The go test command

Reference for go test: how tests are found, -run, -v, -count, -race, -cover, -bench, -fuzz, -short, -timeout and the package list versus local mode caching.

go test builds and runs the tests, benchmarks, fuzz tests and examples of the packages you name. It looks for files ending in _test.go, compiles them together with the package, links a temporary test binary, runs it, and prints a summary. Test code is never part of the normal build, so tests cost nothing in production.

There are two modes. In local directory mode (go test with no arguments) it tests the package in the current directory and does not cache the result. In package list mode (go test ./..., or any named package) successful results are cached, and an unchanged package prints (cached) instead of running again.

Terminal
go test                  # the package in this directory
go test ./...            # every package in the module
go test -run TestParse -v ./internal/parser
go test -race -cover ./...

Try it

A test binary is an ordinary program that calls into the testing package, so the snippets below run the same machinery directly: a test runner, a benchmark, and allocation counting.

Go Running tests without go test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Benchmarks and allocation counts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Terminal
go test [build/test flags] [packages] [-args program flags]
Flag Description
-run regexp Run only tests (and examples) whose names match. Use / to match subtests: -run 'TestParse/empty'.
-v Print every test as it runs (=== RUN, --- PASS), not just failures.
-count n Run each test n times. -count=1 also disables result caching.
-short Sets testing.Short(), so slow tests can skip themselves.
-timeout d Fail the test binary if it runs longer than d (default 10 minutes).
-race Enable the race detector.
-cover, -coverprofile f, -covermode m Report coverage, write a profile for go tool cover, choose set, count or atomic.
-bench regexp Run benchmarks matching the pattern (-bench . for all). Add -benchmem for allocations and -benchtime 2s or -benchtime 100x.
-fuzz regexp, -fuzztime d Run fuzzing for one fuzz test, for a time or a number of executions.
-parallel n Maximum parallel tests marked with t.Parallel() (default GOMAXPROCS).
-failfast Stop after the first failing test.
-shuffle on Randomize test order; the seed is printed so a failure can be repeated.
-json Machine-readable event stream (what CI tools consume).
-cpu 1,2,4 Run the tests with those GOMAXPROCS values.
-skip regexp Do not run tests matching the pattern (Go 1.20).
-list regexp Print matching test names and exit.
-args Everything after goes to the test binary unchanged, for your own flag definitions.

Exit status: 0 if everything passed, 1 for a test failure or build failure. Output ends with ok pkg 0.012s or FAIL pkg 0.012s.

Usage notes

  • What counts as a test. In a _test.go file: func TestXxx(t *testing.T), func BenchmarkXxx(b *testing.B), func FuzzXxx(f *testing.F) and func ExampleXxx() with an // Output: comment. The letter after the prefix must not be lowercase.
  • Package names. Tests may share the package (package foo) to reach unexported names, or use package foo_test for black-box tests of the public API. Both can live in one directory.
  • Caching. Cached results are keyed by the test binary and the files and environment variables it reads. Use -count=1 to force a real run, for example against a database.
  • testdata directories are ignored by the go tool and are the conventional home for fixtures. Tests run with the package directory as working directory.
  • TestMain(m *testing.M) replaces the default entry point so you can set up and tear down shared resources and call os.Exit(m.Run()).
  • A test binary vets the code. A small high-confidence subset of go vet (such as printf checks) runs automatically; add -vet=off to skip it.
  • Benchmarks do not run unless you pass -bench. Since Go 1.24, a loop of the form for b.Loop() { ... } is preferred over manual b.N loops.
  • Races and flaky tests. Combine -race -count=50 in CI for concurrent code. See Testing Concurrent Code.
  • Build tags such as -tags integration select files with a matching //go:build line, a clean way to separate slow tests.
  • Running go test from a different directory with a package path works, but testdata/ paths are relative to the package, not to where you typed the command.