Provided by: golang-go_1.21~2_amd64 bug

NAME

       go - tool for managing Go source code

DESCRIPTION

       The ‘go test’ command takes both flags that apply to ‘go test’ 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 ‘go test’ command and control the execution of
       any test:

       -bench regexp
              Run only those benchmarks matching a regular expression.  By default, no benchmarks
              are  run.   To  run  all  benchmarks,  use  ‘-bench  .’ or ‘-bench=.’.  The regular
              expression is split by unbracketed slash (/) characters into a sequence of  regular
              expressions, and each part of a benchmark’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.

       -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).
              The special syntax Nx means to 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.
              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’t correspond to the original sources.

       -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".
              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  matching  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.

       -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.
              The special syntax Nx means to 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.
              The special syntax  Nx  means  to  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 in a machine-readable format.

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

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

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

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

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

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

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

       -outputdir directory
              Place  output  files  from  profiling  in  the  specified directory, by default the
              directory in which "go test" is running.

       -trace trace.out
              Write an execution trace to the specified file before exiting.

       Each of these flags is also recognized with an optional ‘test.’  prefix,  as  in  -test.v.
       When  invoking  the  generated test binary (the result of ‘go test -c’) directly, however,
       the prefix is mandatory.

       The ‘go test’ 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’s 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  ‘go  test’  runs  a  test binary, it does so from within the corresponding package’s
       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 ‘go test’ runs in package list mode, ‘go test’ 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 ‘go help test’) 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.

AUTHOR

       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 ‘go help testflag’ for the Debian project (and may be used by others).

                                            2022-03-15                             GO-TESTFLAG(7)