Go test Command

Internal

• go Tool
• Go Testing

Overview

The test command runs tests. The shared flags described here apply:

Shared Flags

For more general details on testing in Go, see:

Go Testing

How go test Works

go test recompiles each package specified in its command line, depending on the mode it is running in (local directory mode or package list mode), along with any files with names matching the file pattern *_test.go and creates a binary test file. More details about the files that are included and compiles are available in the File Selection section below. The resulted binary test file that is then executed.

Local Directory Mode

go test runs in local directory mode when it is invoked with no package argument. In this mode, go test compiles the package sources and tests found in the current directory into a single test binary, and then runs the resulting test binary. Caching is disabled. This seems to assume there's a single package in the directory. What about nested packages? After the package test finishes (what if there are multiple packages?), the runtime prints a summary line with the test status ('ok', 'FAIL', package name and elapsed time).

Package List Mode

go test runs in package list mode when go test is invoked with explicit package arguments (ex: go test math), with the ./... argument or even with .. In this mode the tool compiles and tests each of the packages listed on the command line. If the package test passes, the tool prints only the final 'ok' summary line. If it fails, the test prints a full test output. Successful package test results are cached to avoid unnecessary repeated running of the test.

File Selection

Upon execution, go test identifies all files that match the *_test.go pattern and compiles them along the package files. These files may contain test functions, benchmark functions, fuzz tests and example functions.

Files whose name begins with "_" (including "_test.go") or "." are ignored.

Test files that declare a package with the suffix "_test" will be compiled as a separate package, and then linked and run with the main test binary.

go test will ignore a directory named "testdata", making it available to hold ancillary data needed by the tests.

The Test Binary

For each package, go test compiles the package and it links it together with its dependencies into a test binary file named <package-name>.test (example: $WORK/b391/scheduler.test). The test binary file is executed as such:

$WORK/b391/scheduler.test -test.paniconexit0 -test.timeout=10m0s -test.v=true -test.count=1

As part of building a test binary, go test runs go vet on the package and its test source files to identify significant problems. If go vet finds any problems, go test reports those and does not run the test binary. Only a high-confidence subset of the default go vet checks are used. That subset is: atomic, bool, buildtags, directive, errorsas, ifaceassert, nilfunc, printf, and stringintconv.

Test Execution

All test output and summary lines are printed to the go command's standard output, even if the test printed them to its own standard error. The go command's standard error is reserved for printing errors building the tests.

Caching

The rule for a cache hit is that TODO.

Cacheable test flags: -benchtime, -cpu, -list, -parallel, -run, -short, -timeout, -failfast and -v.

To disable test caching, use any test flag or argument other than the cacheable flags. The idiomatic way to disable test caching explicitly is to use -count=1.