path: root/man/go-testflag.7

.\"                                      Hey, EMACS: -*- nroff -*-
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.TH GO-TESTFLAG 7 "2022-03-15"
.\" Please adjust this date whenever revising the manpage.
.SH NAME
go \- tool for managing Go source code
.SH DESCRIPTION
The \(oqgo test\(cq command takes both flags that apply to \(oqgo test\(cq itself
and flags that apply to the resulting test binary.

Several of the flags control profiling and write an execution profile
suitable for "go tool pprof"; run "go tool pprof \-h" for more
information. The \-\-alloc_space, \-\-alloc_objects, and \-\-show_bytes
options of pprof control how the information is presented.

The following flags are recognized by the \(oqgo test\(cq command and
control the execution of any test:
.TP
.BI \-bench " regexp"
Run only those benchmarks matching a regular expression.
By default, no benchmarks are run.
To run all benchmarks, use \(oq\-bench .\(cq or \(oq\-bench=.\(cq.
The regular expression is split by unbracketed slash (/)
characters into a sequence of regular expressions, and each
part of a benchmark\[cq]s identifier must match the corresponding
element in the 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, which are
then run in full.
.TP
.BI \-benchtime " t"
Run enough iterations of each benchmark to take \fIt\fP, specified
as a time.Duration (for example, \-benchtime 1h30s).
.br
The default is 1 second (1s).
.br
The special syntax \fIN\fPx means to run the benchmark \fIN\fP times
(for example, \-benchtime 100x).
.TP
.BI \-count " n"
Run each test, benchmark, and fuzz seed \fIn\fP times (default 1).
.br
If \-cpu is set, run n times for each GOMAXPROCS value.
.br
Examples are always run once. \-count does not apply to
fuzz tests matched by \-fuzz.
.TP
.B \-cover
Enable coverage analysis.
.br
Note that because coverage works by annotating the source
code before compilation, compilation and test failures with
coverage enabled may report line numbers that don\(cqt correspond
to the original sources.
.TP
.BR \-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 is "atomic".
.br
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.
.br
Sets \-cover.
.TP
.BI "\-coverpkg " pattern1 , pattern2 , pattern3
Apply coverage analysis in each test to packages matching the patterns.
The default is for each test to analyze only the package being tested.
.br
See \(oqgo help packages\(cq for a description of package patterns.
.br
Sets \-cover.
.TP
.BI "\-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.
.TP
.B \-failfast
Do not start new tests after the first test failure.
.TP
.BI \-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.
.TP
.BI \-fuzztime " t"
Run enough iterations of the fuzz target during fuzzing to take \fIt\fP,
specified as a time.Duration (for example, \-fuzztime 1h30s).
    The default is to run forever.
.br
The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times
(for example, \-fuzztime 1000x).
.TP
.BI \-fuzzminimizetime " t"
Run enough iterations of the fuzz target during each minimization
attempt to take \fIt\fP, as specified as a time.Duration (for example,
\-fuzzminimizetime 30s).
    The default is 60s.
.br
The special syntax \fIN\fPx means to run the fuzz target \fIN\fP times
(for example, \-fuzzminimizetime 100x).
.TP
.B \-json
Log verbose output and test results in JSON. This presents the
same information as the \-v flag in a machine-readable format.
.TP
.BI \-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.
.TP
.BI \-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.
.br
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.
.br
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.
Note that \-parallel only applies within a single test binary.
The \(oqgo test\(cq command may run tests for different packages
in parallel as well, according to the setting of the \-p flag
(see \(oqgo help build\(cq).
.TP
.BI \-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\(cqs 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.
.TP
.B \-short
Tell long-running tests to shorten their run time.
It is 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.
.TP
.BR "\-shuffle " off,on,N
Randomize the execution order of tests and benchmarks.
It is 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.
.TP
.BI \-timeout " d"
If a test binary runs longer than duration \fId\fP, panic.
.br
If \fId\fP is 0, the timeout is disabled.
.br
The default is 10 minutes (10m).
.TP
.B \-v
Verbose output: log all tests as they are run. Also print all
text from Log and Logf calls even if the test succeeds.
.TP
.BI \-vet " list"
Configure the invocation of "go vet" during "go test"
to use the comma-separated list of vet checks.
.br
If list is empty, "go test" runs "go vet" with a curated list of
checks believed to be always worth addressing.
.br
If list is "off", "go test" does not run "go vet" at all.
.P
The following flags are also recognized by \(oqgo test\(cq and can be used to
profile the tests during execution:
.TP
.B \-benchmem
Print memory allocation statistics for benchmarks.
.TP
.B \-blockprofile \fRblock.out
Write a goroutine blocking profile to the specified file
when all tests are complete.
.br
Writes test binary as \-c would.
.TP
.BI \-blockprofilerate " n"
Control the detail provided in goroutine blocking profiles by
calling runtime.SetBlockProfileRate with \fIn\fP.
.br
See \(oqgo doc runtime.SetBlockProfileRate\(cq.
.br
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.
.TP
.B \-coverprofile \fRcover.out
Write a coverage profile to the file after all tests have passed.
.br
Sets \-cover.
.TP
.B \-cpuprofile \fRcpu.out
Write a CPU profile to the specified file before exiting.
.br
Writes test binary as \-c would.
.TP
.B \-memprofile \fRmem.out
Write an allocation profile to the file after all tests have passed.
.br
Writes test binary as \-c would.
.TP
.BI \-memprofilerate " n"
Enable more precise (and expensive) memory allocation profiles by
setting runtime.MemProfileRate. See \(oqgo doc runtime.MemProfileRate\(cq.
To profile all memory allocations, use \-test.memprofilerate=1.
.TP
.B \-mutexprofile \fRmutex.out
Write a mutex contention profile to the specified file
when all tests are complete.
.br
Writes test binary as \-c would.
.TP
.BI \-mutexprofilefraction " n"
Sample 1 in \fIn\fP stack traces of goroutines holding a
contended mutex.
.TP
.B \-outputdir \fIdirectory
Place output files from profiling in the specified directory,
by default the directory in which "go test" is running.
.TP
.B \-trace trace.out
Write an execution trace to the specified file before exiting.
.P
Each of these flags is also recognized with an optional \(oqtest.\(cq prefix,
as in \-test.v. When invoking the generated test binary (the result of
\(oqgo test \-c\(cq) directly, however, the prefix is mandatory.

The \(oqgo test\(cq command rewrites or removes recognized flags,
as appropriate, both before and after the optional package list,
before invoking the test binary.

For instance, the command

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

will compile the test binary and then run it as

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

(The \-x flag is removed because it applies only to the go command\(cqs
execution, not to the test itself.)

The test flags that generate profiles (other than for coverage) also
leave the test binary in pkg.test for use when analyzing the profiles.

When \(oqgo test\(cq runs a test binary, it does so from within the
corresponding package\(cqs source code directory. Depending on the test,
it may be necessary to do the same when invoking a generated test
binary directly. Because that directory may be located within the
module cache, which may be read-only and is verified by checksums, the
test must not write to it or any other directory within the module
unless explicitly requested by the user (such as with the \-fuzz flag,
which writes failures to testdata/fuzz).

The command-line package list, if present, must appear before any
flag not known to the go test command. Continuing the example above,
the package list would have to appear before \-myflag, but could appear
on either side of \-v.

When \(oqgo test\(cq runs in package list mode, \(oqgo test\(cq caches successful
package test results to avoid unnecessary repeated running of tests. 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.

To keep an argument for a test binary from being interpreted as a
known flag or a package name, use \-args (see \(oqgo help test\(cq) which
passes the remainder of the command line through to the test binary
uninterpreted and unaltered.

For instance, the command

	go test \-v \-args \-x \-v

will compile the test binary and then run it as

	pkg.test \-test.v \-x \-v

Similarly,

	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 are passed through to the
test binary unchanged and with no effect on the go command itself.
In the second example, the argument math is passed through to the test
binary, instead of being interpreted as the package list.
.SH AUTHOR
.PP
This manual page was written by Michael Stapelberg <stapelberg@debian.org>
and is maintained by the
Debian Go Compiler Team <team+go-compiler@tracker.debian.org>
based on the output of \(oqgo help testflag\(cq
for the Debian project (and may be used by others).