GO-TEST(1)

✨ GO-TEST(1) — test packages ✨

okay bestie, welcome to the go-test page from the Go programming tools and commands manual (section 1, obviously 💅). sit down, grab a matcha, we're gonna learn how to test packages. no cap.

---

🌸 NAME 🌸

go-test — test packages. that's it. that's the vibe. 🦋

---

🎀 SYNOPSIS 🎀

go test [build/test flags] [packages] [build/test flags & test binary flags]

---

💖 DESCRIPTION 💖

Go test automates testing the packages named by the import paths. it prints a summary of the test results in this exact format:

ok   archive/tar   0.011s
FAIL archive/zip   0.022s
ok   compress/gzip 0.033s
...

and then, right after, it gives you the detailed output for each failed package. receipts, basically. 😭

Go test recompiles each package along with any files with names matching the file pattern *_test.go. these extra files can contain test functions, benchmark functions, fuzz tests and example functions — see go help testfunc for more. every listed package causes the execution of a separate test binary. and heads up: files whose names begin with _ (including _test.go) or . are ignored. they get the silent treatment, periodt.

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. slay ✨

The go tool will ignore a directory named testdata, which makes it available to hold ancillary data needed by the tests. it's the test's little junk drawer, and honestly? iconic.

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, bools, buildtag, directive, errorsas, ifaceassert, nilfunc, printf, stdversion, stringintconv, and tests. you can see the documentation for these and other vet tests via go doc cmd/vet. to disable the running of go vet, use the -vet=off flag. to run all checks, use the -vet=all flag. choose your fighter. 👑

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. it's a one-job kingpin, respect it.)

The go command places $GOROOT/bin at the beginning of $PATH in the test's environment, so that tests that execute go commands use the same go as the parent go test command. consistency queen 💅

🦋 the two modes 🦋

Go test runs in two different modes, and knowing which one you're in is lowkey the whole game:

The first, called local directory mode, occurs when go test is invoked with no package arguments (for example, go test or go test -v). in this mode, go test compiles the package sources and tests found in the current directory and then runs the resulting test binary. in this mode, caching (discussed below) is disabled. after the package test finishes, go test prints a summary line showing the test status (ok or FAIL), package name, and elapsed time.

The second, called package list mode, occurs when go test is invoked with explicit package arguments (for example go test math, go test ./..., and even go test .). in this mode, go test compiles and tests each of the packages listed on the command line. if a package test passes, go test prints only the final ok summary line. if a package test fails, go test prints the full test output. if invoked with the -bench or -v flag, go test prints the full output even for passing package tests, in order to display the requested benchmark results or verbose logging. after the package tests for all of the listed packages finish, and their output is printed, go test prints a final FAIL status if any package test has failed.

💜 the cache (iykyk) 💜

In package list mode only, go test caches successful package test results to avoid unnecessary repeated running of tests. when the result of a test can be recovered from the cache, go test will redisplay the previous output instead of running the test binary again. when this happens, go test prints (cached) in place of the elapsed time in the summary line. not the glow-up you asked for, but it's the one you got. 🙈

The rule for a match in the cache is that the run involves the same test binary and the flags on the command line come entirely from a restricted set of cacheable test flags, defined as -benchtime, -coverprofile, -cpu, -failfast, -fullpath, -list, -outputdir, -parallel, -run, -short, -skip, -timeout and -v. if a run of go test has any test or non-test flags outside this set, the result is not cached.

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. 🫶

Tests that open files within the package's module or that consult environment variables only match future runs in which the files and environment variables are unchanged. a cached test result is treated as executing in no time at all, so a successful package test result will be cached and reused regardless of -timeout setting. the clock is fake. time is a construct. anyway.

---

⭐ OPTIONS ⭐

in addition to the build flags, the flags handled by go test itself are:

• -args — pass the remainder of the command line (everything after -args) to the test binary, uninterpreted and unchanged. because this flag consumes the remainder of the command line, the package list (if present) must appear before this flag. yeah it eats everything after it, so order matters fr fr.
• -c — compile the test binary to pkg.test in the current directory but do not run it (where pkg is the last element of the package's import path). the file name or target directory can be changed with the -o flag.
• -exec xprog — run the test binary using xprog. the behavior is the same as in go run. see go help run for details.
• -json — convert test output to JSON suitable for automated processing. see go doc test2json for the encoding details. also emits build output in JSON. see go help buildjson.
• -o file — save a copy of the test binary to the named file. the test still runs (unless -c is specified). if file ends in a slash or names an existing directory, the test is written to pkg.test in that directory.

The test binary also accepts flags that control execution of the test; these flags are also accessible by go test. see go help testflag for details.

For more about build flags, see go help build. for more about specifying packages, see go help packages.

---

🌈 SEE ALSO 🌈

• go build(1)
• go vet(1)

---

👑 AUTHOR 👑

This manual page was created using help2man and afterwards updating the output. it is maintained by the Debian Go Compiler Team <team+go-compiler@tracker.debian.org> for the Debian project (and may be used by others). absolute legends, no notes. 💖

---

okay that's the whole page, bestie. go forth, run your tests, and remember: if go vet yells at you, it's not being mean, it's being high-confidence about your wellbeing. Go 1.27, August 2026 — the GO-TEST(1) era, and you're living in it. slay. 💅✨🦋