1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
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).
|
