GO-TESTFLAG(7)

📦
version 1.27~1 · 4 versions
, in ubuntu stonking

💅 GO-TESTFLAG(7) — aka testflag, aka testing flags

ok bestie, welcome to the manual page for testflag — the testing flags. this is the whole entire vibe of how go test gets told what to do. sit down, hydrate, let's go. 🫶

✨ NAME ✨

testflag — testing flags. that's it, that's the name. periodt. 💅

🌸 DESCRIPTION 🌸

okay so here's the tea ☕: the go test command is lowkey two things at once. it takes flags that apply to go test itself, and it ALSO takes flags that get passed down to the resulting test binary. two flavors, one command. iconic.

several of the flags control profiling and write out an execution profile that's suitable for go tool pprof. if you wanna know more about that, run go tool pprof -h. and listen — the -sample_index=alloc_space, -sample_index=alloc_objects, and -show_bytes options of pprof are what control how that info gets presented to you. iykyk. 👑

the following flags are recognized by the go test command and control the execution of any test:

  • -artifacts — save test artifacts into the directory you specified with -outputdir. see go doc testing.T.ArtifactDir. 🎀
  • -bench regexp — run only the benchmarks that match a regular expression. by default, no benchmarks are run (she's shy, she stays home). to run ALL of them, use -bench . or -bench=.. here's the trick: the regular expression gets split by unbracketed slash (/) characters into a sequence of regular expressions, and each part of a benchmark's identifier has to match the corresponding element in that sequence, if any. possible parents of matches are run with b.N=1 to identify sub-benchmarks. for example, given -bench=X/Y, top-level benchmarks matching X are run with b.N=1 to find any sub-benchmarks matching Y, and those then get run in full. 🦋
  • -benchtime t — run enough iterations of each benchmark to take t, specified as a time.Duration (for example, -benchtime 1h30s). the default is 1 second (1s). special syntax Nx means run the benchmark N times (for example, -benchtime 100x). ⭐
  • -count n — run each test, benchmark, and fuzz seed n times (default 1). if -cpu is set, run n times for each GOMAXPROCS value. examples are always run once. -count does not apply to fuzz tests matched by -fuzz. 🙈
  • -cover — enable coverage analysis. ⚠️ heads up: because coverage works by annotating the source code before compilation, compilation and test failures with coverage enabled may report line numbers that don't correspond to the original sources. so like, don't panic when the line numbers feel off, bestie. 😭
  • -covermode set,count,atomic — set the mode for coverage analysis for the package[s] being tested. the default is "set" unless -race is enabled, in which case it's "atomic". the values:
    • set: bool: does this statement run?
    • count: int: how many times does this statement run?
    • atomic: int: count, but correct in multithreaded tests; significantly more expensive.

sets -cover. 💖

  • -coverpkg pattern1,pattern2,pattern3 — apply coverage analysis in each test to packages whose import paths match the patterns. the default is for each test to analyze only the package being tested. see go help packages for a description of package patterns. sets -cover. 🌈
  • -cpu 1,2,4 — specify a list of GOMAXPROCS values for which the tests, benchmarks or fuzz tests should be executed. the default is the current value of GOMAXPROCS. -cpu does not apply to fuzz tests matched by -fuzz. 🔥
  • -failfast — do not start new tests after the first test failure. she said "we're done here". 💀
  • -fullpath — show full file names in the error messages.
  • -fuzz regexp — run the fuzz test matching the regular expression. when specified, the command line argument must match exactly one package within the main module, and regexp must match exactly one fuzz test within that package. fuzzing will occur after tests, benchmarks, seed corpora of other fuzz tests, and examples have completed. see the Fuzzing section of the testing package documentation for details. 🧚
  • -fuzztime t — run enough iterations of the fuzz target during fuzzing to take t, specified as a time.Duration (for example, -fuzztime 1h30s). the default is to run forever. special syntax Nx means run the fuzz target N times (for example, -fuzztime 1000x). 🌀
  • -fuzzminimizetime t — run enough iterations of the fuzz target during each minimization attempt to take t, as specified as a time.Duration (for example, -fuzzminimizetime 30s). the default is 60s. special syntax Nx means run the fuzz target N times (for example, -fuzzminimizetime 100x). ✨
  • -json — log verbose output and test results in JSON. this presents the same information as the -v flag, but in a machine-readable format. for the robots. 🤖 (but make it cute)
  • -list regexp — list tests, benchmarks, fuzz tests, or examples matching the regular expression. no tests, benchmarks, fuzz tests, or examples will be run. this will only list top-level tests. no subtest or subbenchmarks will be shown. 🎀
  • -outputdir directory — place output files from profiling and test artifacts in the specified directory. by default, that's the directory in which go test is running. 📁
  • -parallel n — allow parallel execution of test functions that call t.Parallel, and fuzz targets that call t.Parallel when running the seed corpus. the value of this flag is the maximum number of tests to run simultaneously. while fuzzing, the value of this flag is the maximum number of subprocesses that may call the fuzz function simultaneously, regardless of whether T.Parallel is called. by default, -parallel is set to the value of GOMAXPROCS. ⚠️ setting -parallel to values higher than GOMAXPROCS may cause degraded performance due to CPU contention, especially when fuzzing. also note that -parallel only applies within a single test binary — the go test command may run tests for different packages in parallel as well, according to the setting of the -p flag (see go help build). 👑
  • -run regexp — run only those tests, examples, and fuzz tests matching the regular expression. for tests, the regular expression is split by unbracketed slash (/) characters into a sequence of regular expressions, and each part of a test's identifier must match the corresponding element in the sequence, if any. 📌 note that possible parents of matches are run too, so that -run=X/Y matches and runs and reports the result of all tests matching X, even those without sub-tests matching Y, because it must run them to look for those sub-tests. see also -skip. 🌸
  • -short — tell long-running tests to shorten their run time. it's off by default but set during all.bash so that installing the Go tree can run a sanity check but not spend time running exhaustive tests. 🫶
  • -shuffle off,on,N — randomize the execution order of tests and benchmarks. it's off by default. if -shuffle is set to on, then it will seed the randomizer using the system clock. 🕐 if -shuffle is set to an integer N, then N will be used as the seed value. in both cases, the seed will be reported for reproducibility. 🎲
  • -skip regexp — run only those tests, examples, fuzz tests, and benchmarks that do not match the regular expression. like for -run and -bench, for tests and benchmarks, the regular expression is split by unbracketed slash (/) characters into a sequence of regular expressions, and each part of a test's identifier must match the corresponding element in the sequence, if any. the opposite-girl energy flag. 💅
  • -timeout d — if a test binary runs longer than duration d, panic. if d is 0, the timeout is disabled. the default is 10 minutes (10m). ⏰
  • -v — verbose output: log all tests as they are run. also print all text from Log and Logf calls even if the test succeeds. she's not hiding anything. 💖
  • -vet list — configure the invocation of "go vet" during "go test" to use the comma-separated list of vet checks. if list is empty, "go test" runs "go vet" with a curated list of checks believed to be always worth addressing. if list is "off", "go test" does not run "go vet" at all. 🚫

🌈 the profiling girlies 🌈

the following flags are also recognized by go test and can be used to profile the tests during execution:

  • -benchmem — print memory allocation statistics for benchmarks. 📊 note: allocations made in C or using C.malloc are not counted.
  • -blockprofile block.out — write a goroutine blocking profile to the specified file when all tests are complete. writes test binary as -c would. 🧊
  • -blockprofilerate n — control the detail provided in goroutine blocking profiles by calling runtime.SetBlockProfileRate with n. see go doc runtime.SetBlockProfileRate. the profiler aims to sample, on average, one blocking event every n nanoseconds the program spends blocked. by default, if -test.blockprofile is set without this flag, all blocking events are recorded, equivalent to -test.blockprofilerate=1. 👀
  • -coverprofile cover.out — write a coverage profile to the file after all tests have passed. sets -cover. ✅
  • -cpuprofile cpu.out — write a CPU profile to the specified file before exiting. writes test binary as -c would. 🔥
  • -memprofile mem.out — write an allocation profile to the file after all tests have passed. writes test binary as -c would. 🧠
  • -memprofilerate n — enable more precise (and expensive) memory allocation profiles by setting runtime.MemProfileRate. see go doc runtime.MemProfileRate. to profile all memory allocations, use -test.memprofilerate=1. 💸
  • -mutexprofile mutex.out — write a mutex contention profile to the specified file when all tests are complete. writes test binary as -c would. 🔒
  • -mutexprofilefraction n — sample 1 in n stack traces of goroutines holding a contended mutex.
  • -trace trace.out — write an execution trace to the specified file before exiting. 🛤️

🎀 the prefix tea 🎀

each of these flags is also recognized with an optional test. prefix, as in -test.v. however — and this is the important part — when invoking the generated test binary (the result of go test -c) directly, the prefix is mandatory. no prefix, no service. 🙅‍♀️

the go test command rewrites or removes recognized flags, as appropriate, both before and after the optional package list, before invoking the test binary. she's doing a lil cleanup backstage before the show. ✨

for instance, the command

go-test -v -myflag testdata -cpuprofile=prof.out -x

...and that's where we're pausing, bestie — part 2 is coming, don't go anywhere 💖

ok so when go test actually RUNS the compiled test binary, here's the tea on how it does it: it will compile the test binary and then run it as

pkg.test -test.v -myflag testdata
-test.cpuprofile=prof.out

(and note bestie: the -x flag is gone in that line, because it only applies to the go command's own execution, not to the test itself.)

✨ Heads up ✨ — the test flags that generate profiles (the ones other than the coverage ones) also leave the test binary sitting there in pkg.test so you can use it when you're analyzing those profiles. Very generous of them, honestly.

Now this next bit is IMPORTANT so pay attention 🙏 When go test runs a test binary, it does so from inside the corresponding package's source code directory. Depending on what your test does, you might need to do the exact same thing when you invoke a generated test binary by hand. And here's the catch: that directory might live inside the module cache, which may be read-only and is verified by checksums. So your test must NOT write to it, or to any other directory inside the module, unless the user explicitly asked for that (like with the -fuzz flag, which writes failures to testdata/fuzz). Don't go writing into the module cache, babe, it will not end well 💀

The command-line package list, if you have one, has to show up before any flag that the go test command doesn't know about. Carrying on from the example above: the package list would have to come before -myflag, but it could be on either side of -v. Slay, flexible.

When go test runs in package list mode, it caches successful package test results so it doesn't re-run the same tests over and over like a clown. If you want to disable test caching, just use any test flag or argument that isn't one of the cacheable flags. The idiomatic way to kill caching explicitly is:

-count=1

periodt.

Also!! If you need to keep an argument meant for the test binary from being read as a known flag or a package name, use -args (go check go help test for the deets) — it passes the rest of the command line straight through to the test binary, uninterpreted and unaltered. Untouched. Pristine. The way it should be.

For instance, this command:

go test -v -args -x -v

will compile the test binary and then run it as

pkg.test -test.v -x -v

Similarly, this one:

go test -args math

will compile the test binary and then run it as

pkg.test math

In the first example, the -x and the second -v get passed through to the test binary unchanged and with no effect on the go command itself. In the second example, the argument math gets passed through to the test binary instead of being read as the package list. no cap 🫶

👑 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). shoutout to the maintainers, absolute icons 💖

and that's a wrap, bestie ✨ this whole thing is from Go 1.27, dated August 2026, and it's the GO-TESTFLAG(7) page — go forth and test responsibly 🌸💅

📦 where this page comes from