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)