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

NAME

       go-test - test packages

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 the format:

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

       followed by detailed output for each failed package.

       "Go test" recompiles each package along with  any  files  with  names  matching  the  file
       pattern  "*_test.go".   These  additional  files  can  contain  test  functions, benchmark
       functions, fuzz tests and example functions. See ‘go help testfunc’ for more.
       Each listed package causes the execution of a separate test  binary.   Files  whose  names
       begin 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.

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

       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’,   ‘errorsas’,
       ‘ifaceassert’, ‘nilfunc’, ‘printf’, and ‘stringintconv’. 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.

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

       Go test runs in two different modes:

       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.

       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.

       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, -cpu, -list, -parallel, -run, -short, -timeout, -failfast, 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 source root (usually $GOPATH) 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.

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.

       -c     Compile  the  test  binary  to  pkg.test  but  do not run it (where pkg is the last
              element of the package’s import path).  The file name 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.

       -i     Install packages that are dependencies of the test.  Do not run the test.

       -json  Convert test output to  JSON  suitable  for  automated  processing.   See  ‘go  doc
              test2json’ for the encoding details.

       -o file
              Compile the test binary to the named file.  The test still runs (unless -c or -i is
              specified).

       The test binary also accepts flags that control execution of the  test;  these  flags  are
       also accessible by ‘go test’.  See go-testflag(7) for details.

       For more about build flags, see go-build(1).

       For more about specifying packages, see go-packages(7).

SEE ALSO

       go-build(1), go-vet(1).

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

                                            2022-08-02                                 GO-TEST(1)