1// Package testing provides support for automated testing of Go ...
2PACKAGE testing
3
4IMPORTPATH
5 testdata/testing
6
7IMPORTS
8 bytes
9 flag
10 fmt
11 io
12 os
13 runtime
14 runtime/pprof
15 strconv
16 strings
17 time
18
19FILENAMES
20 testdata/benchmark.go
21 testdata/example.go
22 testdata/testing.go
23
24VARIABLES
25 //
26 var (
27 // The short flag requests that tests run more quickly, but its functionality
28 // is provided by test writers themselves. The testing package is just its
29 // home. The all.bash installation script sets it to make installation more
30 // efficient, but by default the flag is off so a plain "go test" will do a
31 // full test of the package.
32 short = flag.Bool("test.short", false, "run smaller test suite to save time")
33
34 // Report as tests are run; default is silent for success.
35 chatty = flag.Bool("test.v", false, "verbose: print additional output")
36 match = flag.String("test.run", "", "regular expression to select tests to run")
37 memProfile = flag.String("test.memprofile", "", "write a memory profile to the named file after execution")
38 memProfileRate = flag.Int("test.memprofilerate", 0, "if >=0, sets runtime.MemProfileRate")
39 cpuProfile = flag.String("test.cpuprofile", "", "write a cpu profile to the named file during execution")
40 timeout = flag.Duration("test.timeout", 0, "if positive, sets an aggregate time limit for all tests")
41 cpuListStr = flag.String("test.cpu", "", "comma-separated list of number of CPUs to use for each test")
42 parallel = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "maximum test parallelism")
43
44 cpuList []int
45 )
46
47 //
48 var benchTime = flag.Duration("test.benchtime", 1*time.Second, "approximate run time for each benchmark")
49
50 //
51 var matchBenchmarks = flag.String("test.bench", "", "regular expression to select benchmarks to run")
52
53 //
54 var timer *time.Timer
55
56
57FUNCTIONS
58 // An internal function but exported because it is cross-package; ...
59 func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample)
60
61 // An internal function but exported because it is cross-package; ...
62 func RunBenchmarks(matchString func(pat, str string) (bool, error), benchmarks []InternalBenchmark)
63
64 //
65 func RunExamples(examples []InternalExample) (ok bool)
66
67 //
68 func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool)
69
70 // Short reports whether the -test.short flag is set.
71 func Short() bool
72
73 // after runs after all testing.
74 func after()
75
76 // alarm is called if the timeout expires.
77 func alarm()
78
79 // before runs before all testing.
80 func before()
81
82 // decorate inserts the final newline if needed and indentation ...
83 func decorate(s string, addFileLine bool) string
84
85 //
86 func max(x, y int) int
87
88 //
89 func min(x, y int) int
90
91 //
92 func parseCpuList()
93
94 // roundDown10 rounds a number down to the nearest power of 10.
95 func roundDown10(n int) int
96
97 // roundUp rounds x up to a number of the form [1eX, 2eX, 5eX].
98 func roundUp(n int) int
99
100 // startAlarm starts an alarm if requested.
101 func startAlarm()
102
103 // stopAlarm turns off the alarm.
104 func stopAlarm()
105
106 //
107 func tRunner(t *T, test *InternalTest)
108
109
110TYPES
111 // B is a type passed to Benchmark functions to manage benchmark ...
112 type B struct {
113 common
114 N int
115 benchmark InternalBenchmark
116 bytes int64
117 timerOn bool
118 result BenchmarkResult
119 }
120
121 // Error is equivalent to Log() followed by Fail().
122 func (c *B) Error(args ...any)
123
124 // Errorf is equivalent to Logf() followed by Fail().
125 func (c *B) Errorf(format string, args ...any)
126
127 // Fail marks the function as having failed but continues ...
128 func (c *B) Fail()
129
130 // FailNow marks the function as having failed and stops its ...
131 func (c *B) FailNow()
132
133 // Failed reports whether the function has failed.
134 func (c *B) Failed() bool
135
136 // Fatal is equivalent to Log() followed by FailNow().
137 func (c *B) Fatal(args ...any)
138
139 // Fatalf is equivalent to Logf() followed by FailNow().
140 func (c *B) Fatalf(format string, args ...any)
141
142 // Log formats its arguments using default formatting, analogous ...
143 func (c *B) Log(args ...any)
144
145 // Logf formats its arguments according to the format, analogous ...
146 func (c *B) Logf(format string, args ...any)
147
148 // ResetTimer sets the elapsed benchmark time to zero. It does not ...
149 func (b *B) ResetTimer()
150
151 // SetBytes records the number of bytes processed in a single ...
152 func (b *B) SetBytes(n int64)
153
154 // StartTimer starts timing a test. This function is called ...
155 func (b *B) StartTimer()
156
157 // StopTimer stops timing a test. This can be used to pause the ...
158 func (b *B) StopTimer()
159
160 // launch launches the benchmark function. It gradually increases ...
161 func (b *B) launch()
162
163 // log generates the output. It's always at the same stack depth.
164 func (c *B) log(s string)
165
166 //
167 func (b *B) nsPerOp() int64
168
169 // run times the benchmark function in a separate goroutine.
170 func (b *B) run() BenchmarkResult
171
172 // runN runs a single benchmark for the specified number of ...
173 func (b *B) runN(n int)
174
175 // trimOutput shortens the output from a benchmark, which can be ...
176 func (b *B) trimOutput()
177
178 // The results of a benchmark run.
179 type BenchmarkResult struct {
180 N int // The number of iterations.
181 T time.Duration // The total time taken.
182 Bytes int64 // Bytes processed in one iteration.
183 }
184
185 // Benchmark benchmarks a single function. Useful for creating ...
186 func Benchmark(f func(b *B)) BenchmarkResult
187
188 //
189 func (r BenchmarkResult) NsPerOp() int64
190
191 //
192 func (r BenchmarkResult) String() string
193
194 //
195 func (r BenchmarkResult) mbPerSec() float64
196
197 // An internal type but exported because it is cross-package; part ...
198 type InternalBenchmark struct {
199 Name string
200 F func(b *B)
201 }
202
203 //
204 type InternalExample struct {
205 Name string
206 F func()
207 Output string
208 }
209
210 // An internal type but exported because it is cross-package; part ...
211 type InternalTest struct {
212 Name string
213 F func(*T)
214 }
215
216 // T is a type passed to Test functions to manage test state and ...
217 type T struct {
218 common
219 name string // Name of test.
220 startParallel chan bool // Parallel tests will wait on this.
221 }
222
223 // Error is equivalent to Log() followed by Fail().
224 func (c *T) Error(args ...any)
225
226 // Errorf is equivalent to Logf() followed by Fail().
227 func (c *T) Errorf(format string, args ...any)
228
229 // Fail marks the function as having failed but continues ...
230 func (c *T) Fail()
231
232 // FailNow marks the function as having failed and stops its ...
233 func (c *T) FailNow()
234
235 // Failed reports whether the function has failed.
236 func (c *T) Failed() bool
237
238 // Fatal is equivalent to Log() followed by FailNow().
239 func (c *T) Fatal(args ...any)
240
241 // Fatalf is equivalent to Logf() followed by FailNow().
242 func (c *T) Fatalf(format string, args ...any)
243
244 // Log formats its arguments using default formatting, analogous ...
245 func (c *T) Log(args ...any)
246
247 // Logf formats its arguments according to the format, analogous ...
248 func (c *T) Logf(format string, args ...any)
249
250 // Parallel signals that this test is to be run in parallel with ...
251 func (t *T) Parallel()
252
253 // log generates the output. It's always at the same stack depth.
254 func (c *T) log(s string)
255
256 //
257 func (t *T) report()
258
259 // common holds the elements common between T and B and captures ...
260 type common struct {
261 output []byte // Output generated by test or benchmark.
262 failed bool // Test or benchmark has failed.
263 start time.Time // Time test or benchmark started
264 duration time.Duration
265 self any // To be sent on signal channel when done.
266 signal chan any // Output for serial tests.
267 }
268
269 // Error is equivalent to Log() followed by Fail().
270 func (c *common) Error(args ...any)
271
272 // Errorf is equivalent to Logf() followed by Fail().
273 func (c *common) Errorf(format string, args ...any)
274
275 // Fail marks the function as having failed but continues ...
276 func (c *common) Fail()
277
278 // FailNow marks the function as having failed and stops its ...
279 func (c *common) FailNow()
280
281 // Failed reports whether the function has failed.
282 func (c *common) Failed() bool
283
284 // Fatal is equivalent to Log() followed by FailNow().
285 func (c *common) Fatal(args ...any)
286
287 // Fatalf is equivalent to Logf() followed by FailNow().
288 func (c *common) Fatalf(format string, args ...any)
289
290 // Log formats its arguments using default formatting, analogous ...
291 func (c *common) Log(args ...any)
292
293 // Logf formats its arguments according to the format, analogous ...
294 func (c *common) Logf(format string, args ...any)
295
296 // log generates the output. It's always at the same stack depth.
297 func (c *common) log(s string)
298
View as plain text