Skip to content
Tutorials Center
My learning

Topics

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.

Go
// 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.

Go Running tests programmatically with testing.Main

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 Measuring allocations and running a benchmark

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
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.Error records a failure and continues; t.Fatal records and stops that test. Prefer Error when later checks are independent.
  • Table-driven tests with t.Run are the idiom: one slice of cases, one loop, named subtests you can run individually.
  • Results are cached. go test skips a package whose files and inputs did not change and prints (cached). Use -count=1 to force a rerun.
  • Packages without tests report [no test files]. Test binaries run with the package directory as working directory, so testdata/ files are found with relative paths.
  • Helpers. Call t.Helper() in assertion helpers so failures point at the caller. t.TempDir(), t.Setenv() and t.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/synctest package 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.