1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package testing provides support for automated testing of Go packages.
6 // It is intended to be used in concert with the ``go test'' command, which automates
7 // execution of any function of the form
8 // func TestXxx(*testing.T)
9 // where Xxx can be any alphanumeric string (but the first letter must not be in
10 // [a-z]) and serves to identify the test routine.
11 // These TestXxx routines should be declared within the package they are testing.
13 // Tests and benchmarks may be skipped if not applicable like this:
14 // func TestTimeConsuming(t *testing.T) {
15 // if testing.Short() {
16 // t.Skip("skipping test in short mode.")
23 // Functions of the form
24 // func BenchmarkXxx(*testing.B)
25 // are considered benchmarks, and are executed by the "go test" command when
26 // the -test.bench flag is provided. Benchmarks are run sequentially.
28 // For a description of the testing flags, see
29 // http://golang.org/cmd/go/#Description_of_testing_flags.
31 // A sample benchmark function looks like this:
32 // func BenchmarkHello(b *testing.B) {
33 // for i := 0; i < b.N; i++ {
34 // fmt.Sprintf("hello")
38 // The benchmark function must run the target code b.N times.
39 // The benchmark package will vary b.N until the benchmark function lasts
40 // long enough to be timed reliably. The output
41 // BenchmarkHello 10000000 282 ns/op
42 // means that the loop ran 10000000 times at a speed of 282 ns per loop.
44 // If a benchmark needs some expensive setup before running, the timer
46 // func BenchmarkBigLen(b *testing.B) {
49 // for i := 0; i < b.N; i++ {
56 // The package also runs and verifies example code. Example functions may
57 // include a concluding line comment that begins with "Output:" and is compared with
58 // the standard output of the function when the tests are run. (The comparison
59 // ignores leading and trailing space.) These are examples of an example:
61 // func ExampleHello() {
62 // fmt.Println("hello")
66 // func ExampleSalutations() {
67 // fmt.Println("hello, and")
68 // fmt.Println("goodbye")
74 // Example functions without output comments are compiled but not executed.
76 // The naming convention to declare examples for a function F, a type T and
77 // method M on type T are:
79 // func ExampleF() { ... }
80 // func ExampleT() { ... }
81 // func ExampleT_M() { ... }
83 // Multiple example functions for a type/function/method may be provided by
84 // appending a distinct suffix to the name. The suffix must start with a
87 // func ExampleF_suffix() { ... }
88 // func ExampleT_suffix() { ... }
89 // func ExampleT_M_suffix() { ... }
91 // The entire test file is presented as the example when it contains a single
92 // example function, at least one other function, type, variable, or constant
93 // declaration, and no test or benchmark functions.
110 // The short flag requests that tests run more quickly, but its functionality
111 // is provided by test writers themselves. The testing package is just its
112 // home. The all.bash installation script sets it to make installation more
113 // efficient, but by default the flag is off so a plain "go test" will do a
114 // full test of the package.
115 short
= flag
.Bool("test.short", false, "run smaller test suite to save time")
117 // Report as tests are run; default is silent for success.
118 chatty
= flag
.Bool("test.v", false, "verbose: print additional output")
119 match
= flag
.String("test.run", "", "regular expression to select tests and examples to run")
120 memProfile
= flag
.String("test.memprofile", "", "write a memory profile to the named file after execution")
121 memProfileRate
= flag
.Int("test.memprofilerate", 0, "if >=0, sets runtime.MemProfileRate")
122 cpuProfile
= flag
.String("test.cpuprofile", "", "write a cpu profile to the named file during execution")
123 blockProfile
= flag
.String("test.blockprofile", "", "write a goroutine blocking profile to the named file after execution")
124 blockProfileRate
= flag
.Int("test.blockprofilerate", 1, "if >= 0, calls runtime.SetBlockProfileRate()")
125 timeout
= flag
.Duration("test.timeout", 0, "if positive, sets an aggregate time limit for all tests")
126 cpuListStr
= flag
.String("test.cpu", "", "comma-separated list of number of CPUs to use for each test")
127 parallel
= flag
.Int("test.parallel", runtime
.GOMAXPROCS(0), "maximum test parallelism")
129 haveExamples
bool // are there examples?
134 // common holds the elements common between T and B and
135 // captures common methods such as Errorf.
137 mu sync
.RWMutex
// guards output and failed
138 output
[]byte // Output generated by test or benchmark.
139 failed
bool // Test or benchmark has failed.
140 skipped
bool // Test of benchmark has been skipped.
142 start time
.Time
// Time test or benchmark started
143 duration time
.Duration
144 self
interface{} // To be sent on signal channel when done.
145 signal
chan interface{} // Output for serial tests.
148 // Short reports whether the -test.short flag is set.
153 // Verbose reports whether the -test.v flag is set.
154 func Verbose() bool {
158 // decorate prefixes the string with the file and line of the call site
159 // and inserts the final newline if needed and indentation tabs for formatting.
160 func decorate(s
string) string {
161 _
, file
, line
, ok
:= runtime
.Caller(3) // decorate + log + public function.
163 // Truncate file name at last file name separator.
164 if index
:= strings
.LastIndex(file
, "/"); index
>= 0 {
165 file
= file
[index
+1:]
166 } else if index
= strings
.LastIndex(file
, "\\"); index
>= 0 {
167 file
= file
[index
+1:]
173 buf
:= new(bytes
.Buffer
)
174 // Every line is indented at least one tab.
176 fmt
.Fprintf(buf
, "%s:%d: ", file
, line
)
177 lines
:= strings
.Split(s
, "\n")
178 if l
:= len(lines
); l
> 1 && lines
[l
-1] == "" {
181 for i
, line
:= range lines
{
183 // Second and subsequent lines are indented an extra tab.
184 buf
.WriteString("\n\t\t")
186 buf
.WriteString(line
)
192 // T is a type passed to Test functions to manage test state and support formatted test logs.
193 // Logs are accumulated during execution and dumped to standard error when done.
196 name
string // Name of test.
197 startParallel
chan bool // Parallel tests will wait on this.
200 // Fail marks the function as having failed but continues execution.
201 func (c
*common
) Fail() {
207 // Failed reports whether the function has failed.
208 func (c
*common
) Failed() bool {
214 // FailNow marks the function as having failed and stops its execution.
215 // Execution will continue at the next test or benchmark.
216 // FailNow must be called from the goroutine running the
217 // test or benchmark function, not from other goroutines
218 // created during the test. Calling FailNow does not stop
219 // those other goroutines.
220 func (c
*common
) FailNow() {
223 // Calling runtime.Goexit will exit the goroutine, which
224 // will run the deferred functions in this goroutine,
225 // which will eventually run the deferred lines in tRunner,
226 // which will signal to the test loop that this test is done.
228 // A previous version of this code said:
231 // c.signal <- c.self
234 // This previous version duplicated code (those lines are in
235 // tRunner no matter what), but worse the goroutine teardown
236 // implicit in runtime.Goexit was not guaranteed to complete
237 // before the test exited. If a test deferred an important cleanup
238 // function (like removing temporary files), there was no guarantee
239 // it would run on a test failure. Because we send on c.signal during
240 // a top-of-stack deferred function now, we know that the send
241 // only happens after any other stacked defers have completed.
245 // log generates the output. It's always at the same stack depth.
246 func (c
*common
) log(s
string) {
249 c
.output
= append(c
.output
, decorate(s
)...)
252 // Log formats its arguments using default formatting, analogous to Println,
253 // and records the text in the error log. The text will be printed only if
254 // the test fails or the -test.v flag is set.
255 func (c
*common
) Log(args
...interface{}) { c
.log(fmt
.Sprintln(args
...)) }
257 // Logf formats its arguments according to the format, analogous to Printf,
258 // and records the text in the error log. The text will be printed only if
259 // the test fails or the -test.v flag is set.
260 func (c
*common
) Logf(format
string, args
...interface{}) { c
.log(fmt
.Sprintf(format
, args
...)) }
262 // Error is equivalent to Log followed by Fail.
263 func (c
*common
) Error(args
...interface{}) {
264 c
.log(fmt
.Sprintln(args
...))
268 // Errorf is equivalent to Logf followed by Fail.
269 func (c
*common
) Errorf(format
string, args
...interface{}) {
270 c
.log(fmt
.Sprintf(format
, args
...))
274 // Fatal is equivalent to Log followed by FailNow.
275 func (c
*common
) Fatal(args
...interface{}) {
276 c
.log(fmt
.Sprintln(args
...))
280 // Fatalf is equivalent to Logf followed by FailNow.
281 func (c
*common
) Fatalf(format
string, args
...interface{}) {
282 c
.log(fmt
.Sprintf(format
, args
...))
286 // Skip is equivalent to Log followed by SkipNow.
287 func (c
*common
) Skip(args
...interface{}) {
288 c
.log(fmt
.Sprintln(args
...))
292 // Skipf is equivalent to Logf followed by SkipNow.
293 func (c
*common
) Skipf(format
string, args
...interface{}) {
294 c
.log(fmt
.Sprintf(format
, args
...))
298 // SkipNow marks the test as having been skipped and stops its execution.
299 // Execution will continue at the next test or benchmark. See also FailNow.
300 // SkipNow must be called from the goroutine running the test, not from
301 // other goroutines created during the test. Calling SkipNow does not stop
302 // those other goroutines.
303 func (c
*common
) SkipNow() {
308 func (c
*common
) skip() {
314 // Skipped reports whether the test was skipped.
315 func (c
*common
) Skipped() bool {
321 // Parallel signals that this test is to be run in parallel with (and only with)
322 // other parallel tests.
323 func (t
*T
) Parallel() {
324 t
.signal
<- (*T
)(nil) // Release main testing loop
325 <-t
.startParallel
// Wait for serial tests to finish
328 // An internal type but exported because it is cross-package; part of the implementation
329 // of the "go test" command.
330 type InternalTest
struct {
335 func tRunner(t
*T
, test
*InternalTest
) {
338 // When this goroutine is done, either because test.F(t)
339 // returned normally or because a test failure triggered
340 // a call to runtime.Goexit, record the duration and send
341 // a signal saying that the test is done.
343 t
.duration
= time
.Now().Sub(t
.start
)
344 // If the test panicked, print any test output before dying.
345 if err
:= recover(); err
!= nil {
356 // An internal function but exported because it is cross-package; part of the implementation
357 // of the "go test" command.
358 func Main(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) {
364 haveExamples
= len(examples
) > 0
365 testOk
:= RunTests(matchString
, tests
)
366 exampleOk
:= RunExamples(matchString
, examples
)
367 if !testOk ||
!exampleOk
{
373 RunBenchmarks(matchString
, benchmarks
)
377 func (t
*T
) report() {
378 tstr
:= fmt
.Sprintf("(%.2f seconds)", t
.duration
.Seconds())
379 format
:= "--- %s: %s %s\n%s"
381 fmt
.Printf(format
, "FAIL", t
.name
, tstr
, t
.output
)
384 fmt
.Printf(format
, "SKIP", t
.name
, tstr
, t
.output
)
386 fmt
.Printf(format
, "PASS", t
.name
, tstr
, t
.output
)
391 func RunTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
) (ok
bool) {
393 if len(tests
) == 0 && !haveExamples
{
394 fmt
.Fprintln(os
.Stderr
, "testing: warning: no tests to run")
397 for _
, procs
:= range cpuList
{
398 runtime
.GOMAXPROCS(procs
)
399 // We build a new channel tree for each run of the loop.
400 // collector merges in one channel all the upstream signals from parallel tests.
401 // If all tests pump to the same channel, a bug can occur where a test
402 // kicks off a goroutine that Fails, yet the test still delivers a completion signal,
403 // which skews the counting.
404 var collector
= make(chan interface{})
407 startParallel
:= make(chan bool)
409 for i
:= 0; i
< len(tests
); i
++ {
410 matched
, err
:= matchString(*match
, tests
[i
].Name
)
412 fmt
.Fprintf(os
.Stderr
, "testing: invalid regexp for -test.run: %s\n", err
)
418 testName
:= tests
[i
].Name
420 testName
= fmt
.Sprintf("%s-%d", tests
[i
].Name
, procs
)
424 signal
: make(chan interface{}),
427 startParallel
: startParallel
,
431 fmt
.Printf("=== RUN %s\n", t
.name
)
433 go tRunner(t
, &tests
[i
])
434 out
:= (<-t
.signal
).(*T
)
435 if out
== nil { // Parallel run.
437 collector
<- <-t
.signal
443 ok
= ok
&& !out
.Failed()
447 for numParallel
+running
> 0 {
448 if running
< *parallel
&& numParallel
> 0 {
449 startParallel
<- true
454 t
:= (<-collector
).(*T
)
456 ok
= ok
&& !t
.Failed()
463 // before runs before all testing.
465 if *memProfileRate
> 0 {
466 runtime
.MemProfileRate
= *memProfileRate
468 if *cpuProfile
!= "" {
469 f
, err
:= os
.Create(*cpuProfile
)
471 fmt
.Fprintf(os
.Stderr
, "testing: %s", err
)
474 if err
:= pprof
.StartCPUProfile(f
); err
!= nil {
475 fmt
.Fprintf(os
.Stderr
, "testing: can't start cpu profile: %s", err
)
479 // Could save f so after can call f.Close; not worth the effort.
481 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
482 runtime
.SetBlockProfileRate(*blockProfileRate
)
486 // after runs after all testing.
488 if *cpuProfile
!= "" {
489 pprof
.StopCPUProfile() // flushes profile to disk
491 if *memProfile
!= "" {
492 f
, err
:= os
.Create(*memProfile
)
494 fmt
.Fprintf(os
.Stderr
, "testing: %s", err
)
497 if err
= pprof
.WriteHeapProfile(f
); err
!= nil {
498 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s", *memProfile
, err
)
502 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
503 f
, err
:= os
.Create(*blockProfile
)
505 fmt
.Fprintf(os
.Stderr
, "testing: %s", err
)
508 if err
= pprof
.Lookup("block").WriteTo(f
, 0); err
!= nil {
509 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s", *blockProfile
, err
)
515 var timer
*time
.Timer
517 // startAlarm starts an alarm if requested.
520 timer
= time
.AfterFunc(*timeout
, alarm
)
524 // stopAlarm turns off the alarm.
531 // alarm is called if the timeout expires.
533 panic("test timed out")
536 func parseCpuList() {
537 if len(*cpuListStr
) == 0 {
538 cpuList
= append(cpuList
, runtime
.GOMAXPROCS(-1))
540 for _
, val
:= range strings
.Split(*cpuListStr
, ",") {
541 cpu
, err
:= strconv
.Atoi(val
)
542 if err
!= nil || cpu
<= 0 {
543 fmt
.Fprintf(os
.Stderr
, "testing: invalid value %q for -test.cpu", val
)
546 cpuList
= append(cpuList
, cpu
)