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.
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.
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.
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
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.gofile:func TestXxx(t *testing.T),func BenchmarkXxx(b *testing.B),func FuzzXxx(f *testing.F)andfunc 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 usepackage foo_testfor 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=1to force a real run, for example against a database. testdatadirectories 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 callos.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=offto skip it. - Benchmarks do not run unless you pass
-bench. Since Go 1.24, a loop of the formfor b.Loop() { ... }is preferred over manualb.Nloops. - Races and flaky tests. Combine
-race -count=50in CI for concurrent code. See Testing Concurrent Code. - Build tags such as
-tags integrationselect files with a matching//go:buildline, a clean way to separate slow tests. - Running
go testfrom a different directory with a package path works, buttestdata/paths are relative to the package, not to where you typed the command.
Related
- go vet, go build, go run, go list
- Lessons: Testing, Table-Driven Tests, Benchmarks and Fuzzing