diff options
Diffstat (limited to 'man/go-test.1')
| -rw-r--r-- | man/go-test.1 | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/man/go-test.1 b/man/go-test.1 new file mode 100644 index 0000000..8636e67 --- /dev/null +++ b/man/go-test.1 @@ -0,0 +1,150 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TEST 1 "2022-08-02" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go-test \- test packages +.SH SYNOPSIS +.B go test +.RI [ "build/test flags" ] +.RI [ packages ] +.RI [ "build/test flags & test binary flags" ] +.SH DESCRIPTION +"Go test" automates testing the packages named by the import paths. +It prints a summary of the test results in the format: + +.Vb 6 +\& ok archive/tar 0.011s +\& FAIL archive/zip 0.022s +\& ok compress/gzip 0.033s +\& ... +.Ve + +followed by detailed output for each failed package. +.P +"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 \(oqgo help testfunc\(cq for more. +.br +Each listed package causes the execution of a separate test binary. +Files whose names begin with "_" (including "_test.go") or "." are ignored. +.P +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. +.P +The go tool will ignore a directory named "testdata", making it available +to hold ancillary data needed by the tests. +.P +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: \(oqatomic\(cq, \(oqbool\(cq, \(oqbuildtags\(cq, \(oqerrorsas\(cq, \(oqifaceassert\(cq, \(oqnilfunc\(cq, \(oqprintf\(cq, and \(oqstringintconv\(cq. 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. +.P +All test output and summary lines are printed to the go command\(cqs +standard output, even if the test printed them to its own standard +error. (The go command\(cqs standard error is reserved for printing +errors building the tests.) +.P +Go test runs in two different modes: +.P +The first, called local directory mode, occurs when go test is +invoked with no package arguments (for example, \(oqgo test\(cq or \(oqgo +test \-v\(cq). 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 (\(oqok\(cq or \(oqFAIL\(cq), package name, and elapsed +time. +.P +The second, called package list mode, occurs when go test is invoked +with explicit package arguments (for example \(oqgo test math\(cq, \(oqgo +test ./...\(cq, and even \(oqgo test .\(cq). 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 \(oqok\(cq 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 \(oqFAIL\(cq status if any package test +has failed. +.P +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 \(oq(cached)\(cq in place of the +elapsed time in the summary line. +.P +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 \[oq]cacheable\[cq] 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\(cqs 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. +.SH OPTIONS +In addition to the build flags, the flags handled by \(oqgo test\(cq itself are: +.TP +.B \-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. +.TP +.B \-c +Compile the test binary to pkg.test but do not run it +(where pkg is the last element of the package\(cqs import path). +The file name can be changed with the \-o flag. +.TP +.BI "\-exec " xprog +Run the test binary using xprog. The behavior is the same as +in \(oqgo run\(cq. See \(oqgo help run\(cq for details. +.TP +.B \-i +Install packages that are dependencies of the test. +Do not run the test. +.TP +.B \-json +Convert test output to JSON suitable for automated processing. +See \(oqgo doc test2json\(cq for the encoding details. +.TP +.BI "\-o " file +Compile the test binary to the named file. +The test still runs (unless \-c or \-i is specified). +.P +The test binary also accepts flags that control execution of the test; these +flags are also accessible by \(oqgo test\(cq. See \fBgo-testflag\fP(7) for details. +.P +For more about build flags, see \fBgo-build\fP(1). +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-vet (1). +.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 test\(cq +for the Debian project (and may be used by others). |