Go Reference ยท Logging, Flags and Testing
Go testing package
Reference for the Go testing package and go test: test functions, file naming, subtests, TestMain, benchmarks, fuzz targets, examples, coverage and useful flags.
The package testing is Go's built-in test framework, and the go test command is its runner. There is no assertion library: a test is a plain function that reports problems with methods on *testing.T, and any Go code can be a check. The same package also supports benchmarks, fuzz tests and testable examples.
Tests live in files whose names end in _test.go, in the same directory as the code they test. The go tool compiles those files only for go test, never into your program.
// slug_test.go func TestSlugify(t *testing.T) { if got := Slugify("Hello World"); got != "hello-world" { t.Errorf("got %q", got) } }
Try it
On this site everything compiles as one main.go, so there is no go test. The examples start the real test machinery with testing.Main, which is what go test does behind the scenes.
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
func TestXxx(t *testing.T) func BenchmarkXxx(b *testing.B) func FuzzXxx(f *testing.F) func ExampleXxx() func TestMain(m *testing.M)
| Rule | Description |
|---|---|
| File name | Must end with _test.go. Files starting with _ or . are ignored. |
| Function name | Test, Benchmark, Fuzz or Example, followed by a name that does not start with a lowercase letter (TestParse, Test_parse, not Testparse). |
| Package | Either the same package (white-box) or package foo_test (black-box, can only use exported names). Both can exist in one directory. |
TestMain |
Optional. Receives *testing.M; call m.Run() and pass its result to os.Exit. Use it for one-time setup and teardown. |
| Common flag | Meaning |
|---|---|
-run regexp |
Run only tests (and examples) whose names match. / separates subtest levels: -run 'TestSlug/empty'. |
-v |
Print each test as it runs, plus t.Log output. |
-count=n |
Run each test n times; -count=1 disables result caching. |
-race |
Enable the race detector. |
-cover, -coverprofile=c.out |
Report coverage and write a profile for go tool cover. |
-bench regexp, -benchmem |
Run benchmarks, show allocations. |
-fuzz name, -fuzztime d |
Fuzz one target for a duration. |
-short, -timeout d, -failfast, -shuffle on |
Short mode, deadline (default 10 minutes), stop at first failure, random order. |
Usage notes
- Failure vs. stopping.
t.Errorrecords a failure and continues;t.Fatalrecords and stops that test. PreferErrorwhen later checks are independent. - Table-driven tests with
t.Runare the idiom: one slice of cases, one loop, named subtests you can run individually. - Results are cached.
go testskips a package whose files and inputs did not change and prints(cached). Use-count=1to force a rerun. - Packages without tests report
[no test files]. Test binaries run with the package directory as working directory, sotestdata/files are found with relative paths. - Helpers. Call
t.Helper()in assertion helpers so failures point at the caller.t.TempDir(),t.Setenv()andt.Cleanup()clean up automatically. - Parallelism.
t.Parallel()pauses a test until the serial ones are done, then runs it alongside others. Capture loop variables carefully in older code; since Go 1.22 each iteration has its own variable. testing.Short()lets slow tests skip themselves under-short.- Do not leave goroutines running past the end of a test; they are a common source of flaky failures. Go 1.25 adds the
testing/synctestpackage for testing concurrent code with a fake clock. - Benchmarks, fuzz tests and examples use the same files; see testing.B, testing.F and Example functions.
Related
- testing.T, testing.B
- net/http/httptest
- Tutorial: Testing, Table-driven tests and Benchmarks and fuzzing