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.
12 // Within these functions, use the Error, Fail or related methods to signal failure.
14 // To write a new test suite, create a file whose name ends _test.go that
15 // contains the TestXxx functions as described here. Put the file in the same
16 // package as the one being tested. The file will be excluded from regular
17 // package builds but will be included when the ``go test'' command is run.
18 // For more detail, run ``go help test'' and ``go help testflag''.
20 // Tests and benchmarks may be skipped if not applicable with a call to
21 // the Skip method of *T and *B:
22 // func TestTimeConsuming(t *testing.T) {
23 // if testing.Short() {
24 // t.Skip("skipping test in short mode.")
31 // Functions of the form
32 // func BenchmarkXxx(*testing.B)
33 // are considered benchmarks, and are executed by the "go test" command when
34 // its -bench flag is provided. Benchmarks are run sequentially.
36 // For a description of the testing flags, see
37 // http://golang.org/cmd/go/#hdr-Description_of_testing_flags.
39 // A sample benchmark function looks like this:
40 // func BenchmarkHello(b *testing.B) {
41 // for i := 0; i < b.N; i++ {
42 // fmt.Sprintf("hello")
46 // The benchmark function must run the target code b.N times.
47 // The benchmark package will vary b.N until the benchmark function lasts
48 // long enough to be timed reliably. The output
49 // BenchmarkHello 10000000 282 ns/op
50 // means that the loop ran 10000000 times at a speed of 282 ns per loop.
52 // If a benchmark needs some expensive setup before running, the timer
55 // func BenchmarkBigLen(b *testing.B) {
58 // for i := 0; i < b.N; i++ {
63 // If a benchmark needs to test performance in a parallel setting, it may use
64 // the RunParallel helper function; such benchmarks are intended to be used with
65 // the go test -cpu flag:
67 // func BenchmarkTemplateParallel(b *testing.B) {
68 // templ := template.Must(template.New("test").Parse("Hello, {{.}}!"))
69 // b.RunParallel(func(pb *testing.PB) {
70 // var buf bytes.Buffer
73 // templ.Execute(&buf, "World")
80 // The package also runs and verifies example code. Example functions may
81 // include a concluding line comment that begins with "Output:" and is compared with
82 // the standard output of the function when the tests are run. (The comparison
83 // ignores leading and trailing space.) These are examples of an example:
85 // func ExampleHello() {
86 // fmt.Println("hello")
90 // func ExampleSalutations() {
91 // fmt.Println("hello, and")
92 // fmt.Println("goodbye")
98 // Example functions without output comments are compiled but not executed.
100 // The naming convention to declare examples for the package, a function F, a type T and
101 // method M on type T are:
103 // func Example() { ... }
104 // func ExampleF() { ... }
105 // func ExampleT() { ... }
106 // func ExampleT_M() { ... }
108 // Multiple example functions for a package/type/function/method may be provided by
109 // appending a distinct suffix to the name. The suffix must start with a
110 // lower-case letter.
112 // func Example_suffix() { ... }
113 // func ExampleF_suffix() { ... }
114 // func ExampleT_suffix() { ... }
115 // func ExampleT_M_suffix() { ... }
117 // The entire test file is presented as the example when it contains a single
118 // example function, at least one other function, type, variable, or constant
119 // declaration, and no test or benchmark functions.
123 // It is sometimes necessary for a test program to do extra setup or teardown
124 // before or after testing. It is also sometimes necessary for a test to control
125 // which code runs on the main thread. To support these and other cases,
126 // if a test file contains a function:
128 // func TestMain(m *testing.M)
130 // then the generated test will call TestMain(m) instead of running the tests
131 // directly. TestMain runs in the main goroutine and can do whatever setup
132 // and teardown is necessary around a call to m.Run. It should then call
133 // os.Exit with the result of m.Run.
135 // The minimal implementation of TestMain is:
137 // func TestMain(m *testing.M) { os.Exit(m.Run()) }
139 // In effect, that is the implementation used when no TestMain is explicitly defined.
156 // The short flag requests that tests run more quickly, but its functionality
157 // is provided by test writers themselves. The testing package is just its
158 // home. The all.bash installation script sets it to make installation more
159 // efficient, but by default the flag is off so a plain "go test" will do a
160 // full test of the package.
161 short
= flag
.Bool("test.short", false, "run smaller test suite to save time")
163 // The directory in which to create profile files and the like. When run from
164 // "go test", the binary always runs in the source directory for the package;
165 // this flag lets "go test" tell the binary to write the files in the directory where
166 // the "go test" command is run.
167 outputDir
= flag
.String("test.outputdir", "", "directory in which to write profiles")
169 // Report as tests are run; default is silent for success.
170 chatty
= flag
.Bool("test.v", false, "verbose: print additional output")
171 coverProfile
= flag
.String("test.coverprofile", "", "write a coverage profile to the named file after execution")
172 match
= flag
.String("test.run", "", "regular expression to select tests and examples to run")
173 memProfile
= flag
.String("test.memprofile", "", "write a memory profile to the named file after execution")
174 memProfileRate
= flag
.Int("test.memprofilerate", 0, "if >=0, sets runtime.MemProfileRate")
175 cpuProfile
= flag
.String("test.cpuprofile", "", "write a cpu profile to the named file during execution")
176 blockProfile
= flag
.String("test.blockprofile", "", "write a goroutine blocking profile to the named file after execution")
177 blockProfileRate
= flag
.Int("test.blockprofilerate", 1, "if >= 0, calls runtime.SetBlockProfileRate()")
178 timeout
= flag
.Duration("test.timeout", 0, "if positive, sets an aggregate time limit for all tests")
179 cpuListStr
= flag
.String("test.cpu", "", "comma-separated list of number of CPUs to use for each test")
180 parallel
= flag
.Int("test.parallel", runtime
.GOMAXPROCS(0), "maximum test parallelism")
182 haveExamples
bool // are there examples?
187 // common holds the elements common between T and B and
188 // captures common methods such as Errorf.
190 mu sync
.RWMutex
// guards output and failed
191 output
[]byte // Output generated by test or benchmark.
192 failed
bool // Test or benchmark has failed.
193 skipped
bool // Test of benchmark has been skipped.
196 start time
.Time
// Time test or benchmark started
197 duration time
.Duration
198 self
interface{} // To be sent on signal channel when done.
199 signal
chan interface{} // Output for serial tests.
202 // Short reports whether the -test.short flag is set.
207 // Verbose reports whether the -test.v flag is set.
208 func Verbose() bool {
212 // decorate prefixes the string with the file and line of the call site
213 // and inserts the final newline if needed and indentation tabs for formatting.
214 func decorate(s
string) string {
215 _
, file
, line
, ok
:= runtime
.Caller(3) // decorate + log + public function.
217 // Truncate file name at last file name separator.
218 if index
:= strings
.LastIndex(file
, "/"); index
>= 0 {
219 file
= file
[index
+1:]
220 } else if index
= strings
.LastIndex(file
, "\\"); index
>= 0 {
221 file
= file
[index
+1:]
227 buf
:= new(bytes
.Buffer
)
228 // Every line is indented at least one tab.
230 fmt
.Fprintf(buf
, "%s:%d: ", file
, line
)
231 lines
:= strings
.Split(s
, "\n")
232 if l
:= len(lines
); l
> 1 && lines
[l
-1] == "" {
235 for i
, line
:= range lines
{
237 // Second and subsequent lines are indented an extra tab.
238 buf
.WriteString("\n\t\t")
240 buf
.WriteString(line
)
246 // TB is the interface common to T and B.
248 Error(args
...interface{})
249 Errorf(format
string, args
...interface{})
253 Fatal(args
...interface{})
254 Fatalf(format
string, args
...interface{})
255 Log(args
...interface{})
256 Logf(format
string, args
...interface{})
257 Skip(args
...interface{})
259 Skipf(format
string, args
...interface{})
262 // A private method to prevent users implementing the
263 // interface and so future additions to it will not
264 // violate Go 1 compatibility.
271 // T is a type passed to Test functions to manage test state and support formatted test logs.
272 // Logs are accumulated during execution and dumped to standard error when done.
275 name
string // Name of test.
276 startParallel
chan bool // Parallel tests will wait on this.
279 func (c
*common
) private() {}
281 // Fail marks the function as having failed but continues execution.
282 func (c
*common
) Fail() {
288 // Failed reports whether the function has failed.
289 func (c
*common
) Failed() bool {
295 // FailNow marks the function as having failed and stops its execution.
296 // Execution will continue at the next test or benchmark.
297 // FailNow must be called from the goroutine running the
298 // test or benchmark function, not from other goroutines
299 // created during the test. Calling FailNow does not stop
300 // those other goroutines.
301 func (c
*common
) FailNow() {
304 // Calling runtime.Goexit will exit the goroutine, which
305 // will run the deferred functions in this goroutine,
306 // which will eventually run the deferred lines in tRunner,
307 // which will signal to the test loop that this test is done.
309 // A previous version of this code said:
312 // c.signal <- c.self
315 // This previous version duplicated code (those lines are in
316 // tRunner no matter what), but worse the goroutine teardown
317 // implicit in runtime.Goexit was not guaranteed to complete
318 // before the test exited. If a test deferred an important cleanup
319 // function (like removing temporary files), there was no guarantee
320 // it would run on a test failure. Because we send on c.signal during
321 // a top-of-stack deferred function now, we know that the send
322 // only happens after any other stacked defers have completed.
327 // log generates the output. It's always at the same stack depth.
328 func (c
*common
) log(s
string) {
331 c
.output
= append(c
.output
, decorate(s
)...)
334 // Log formats its arguments using default formatting, analogous to Println,
335 // and records the text in the error log. The text will be printed only if
336 // the test fails or the -test.v flag is set.
337 func (c
*common
) Log(args
...interface{}) { c
.log(fmt
.Sprintln(args
...)) }
339 // Logf formats its arguments according to the format, analogous to Printf,
340 // and records the text in the error log. The text will be printed only if
341 // the test fails or the -test.v flag is set.
342 func (c
*common
) Logf(format
string, args
...interface{}) { c
.log(fmt
.Sprintf(format
, args
...)) }
344 // Error is equivalent to Log followed by Fail.
345 func (c
*common
) Error(args
...interface{}) {
346 c
.log(fmt
.Sprintln(args
...))
350 // Errorf is equivalent to Logf followed by Fail.
351 func (c
*common
) Errorf(format
string, args
...interface{}) {
352 c
.log(fmt
.Sprintf(format
, args
...))
356 // Fatal is equivalent to Log followed by FailNow.
357 func (c
*common
) Fatal(args
...interface{}) {
358 c
.log(fmt
.Sprintln(args
...))
362 // Fatalf is equivalent to Logf followed by FailNow.
363 func (c
*common
) Fatalf(format
string, args
...interface{}) {
364 c
.log(fmt
.Sprintf(format
, args
...))
368 // Skip is equivalent to Log followed by SkipNow.
369 func (c
*common
) Skip(args
...interface{}) {
370 c
.log(fmt
.Sprintln(args
...))
374 // Skipf is equivalent to Logf followed by SkipNow.
375 func (c
*common
) Skipf(format
string, args
...interface{}) {
376 c
.log(fmt
.Sprintf(format
, args
...))
380 // SkipNow marks the test as having been skipped and stops its execution.
381 // Execution will continue at the next test or benchmark. See also FailNow.
382 // SkipNow must be called from the goroutine running the test, not from
383 // other goroutines created during the test. Calling SkipNow does not stop
384 // those other goroutines.
385 func (c
*common
) SkipNow() {
391 func (c
*common
) skip() {
397 // Skipped reports whether the test was skipped.
398 func (c
*common
) Skipped() bool {
404 // Parallel signals that this test is to be run in parallel with (and only with)
405 // other parallel tests.
406 func (t
*T
) Parallel() {
407 t
.signal
<- (*T
)(nil) // Release main testing loop
408 <-t
.startParallel
// Wait for serial tests to finish
409 // Assuming Parallel is the first thing a test does, which is reasonable,
410 // reinitialize the test's start time because it's actually starting now.
414 // An internal type but exported because it is cross-package; part of the implementation
415 // of the "go test" command.
416 type InternalTest
struct {
421 func tRunner(t
*T
, test
*InternalTest
) {
422 // When this goroutine is done, either because test.F(t)
423 // returned normally or because a test failure triggered
424 // a call to runtime.Goexit, record the duration and send
425 // a signal saying that the test is done.
427 t
.duration
= time
.Now().Sub(t
.start
)
428 // If the test panicked, print any test output before dying.
430 if !t
.finished
&& err
== nil {
431 err
= fmt
.Errorf("test executed panic(nil) or runtime.Goexit")
446 // An internal function but exported because it is cross-package; part of the implementation
447 // of the "go test" command.
448 func Main(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) {
449 os
.Exit(MainStart(matchString
, tests
, benchmarks
, examples
).Run())
452 // M is a type passed to a TestMain function to run the actual tests.
454 matchString
func(pat
, str
string) (bool, error
)
456 benchmarks
[]InternalBenchmark
457 examples
[]InternalExample
460 // MainStart is meant for use by tests generated by 'go test'.
461 // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
462 // It may change signature from release to release.
463 func MainStart(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) *M
{
465 matchString
: matchString
,
467 benchmarks
: benchmarks
,
472 // Run runs the tests. It returns an exit code to pass to os.Exit.
473 func (m
*M
) Run() int {
479 haveExamples
= len(m
.examples
) > 0
480 testOk
:= RunTests(m
.matchString
, m
.tests
)
481 exampleOk
:= RunExamples(m
.matchString
, m
.examples
)
483 if !testOk ||
!exampleOk
{
489 RunBenchmarks(m
.matchString
, m
.benchmarks
)
494 func (t
*T
) report() {
495 tstr
:= fmt
.Sprintf("(%.2f seconds)", t
.duration
.Seconds())
496 format
:= "--- %s: %s %s\n%s"
498 fmt
.Printf(format
, "FAIL", t
.name
, tstr
, t
.output
)
501 fmt
.Printf(format
, "SKIP", t
.name
, tstr
, t
.output
)
503 fmt
.Printf(format
, "PASS", t
.name
, tstr
, t
.output
)
508 func RunTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
) (ok
bool) {
510 if len(tests
) == 0 && !haveExamples
{
511 fmt
.Fprintln(os
.Stderr
, "testing: warning: no tests to run")
514 for _
, procs
:= range cpuList
{
515 runtime
.GOMAXPROCS(procs
)
516 // We build a new channel tree for each run of the loop.
517 // collector merges in one channel all the upstream signals from parallel tests.
518 // If all tests pump to the same channel, a bug can occur where a test
519 // kicks off a goroutine that Fails, yet the test still delivers a completion signal,
520 // which skews the counting.
521 var collector
= make(chan interface{})
524 startParallel
:= make(chan bool)
526 for i
:= 0; i
< len(tests
); i
++ {
527 matched
, err
:= matchString(*match
, tests
[i
].Name
)
529 fmt
.Fprintf(os
.Stderr
, "testing: invalid regexp for -test.run: %s\n", err
)
535 testName
:= tests
[i
].Name
537 testName
= fmt
.Sprintf("%s-%d", tests
[i
].Name
, procs
)
541 signal
: make(chan interface{}),
544 startParallel
: startParallel
,
548 fmt
.Printf("=== RUN %s\n", t
.name
)
550 go tRunner(t
, &tests
[i
])
551 out
:= (<-t
.signal
).(*T
)
552 if out
== nil { // Parallel run.
554 collector
<- <-t
.signal
560 ok
= ok
&& !out
.Failed()
564 for numParallel
+running
> 0 {
565 if running
< *parallel
&& numParallel
> 0 {
566 startParallel
<- true
571 t
:= (<-collector
).(*T
)
573 ok
= ok
&& !t
.Failed()
580 // before runs before all testing.
582 if *memProfileRate
> 0 {
583 runtime
.MemProfileRate
= *memProfileRate
585 if *cpuProfile
!= "" {
586 f
, err
:= os
.Create(toOutputDir(*cpuProfile
))
588 fmt
.Fprintf(os
.Stderr
, "testing: %s", err
)
591 if err
:= pprof
.StartCPUProfile(f
); err
!= nil {
592 fmt
.Fprintf(os
.Stderr
, "testing: can't start cpu profile: %s", err
)
596 // Could save f so after can call f.Close; not worth the effort.
598 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
599 runtime
.SetBlockProfileRate(*blockProfileRate
)
601 if *coverProfile
!= "" && cover
.Mode
== "" {
602 fmt
.Fprintf(os
.Stderr
, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
607 // after runs after all testing.
609 if *cpuProfile
!= "" {
610 pprof
.StopCPUProfile() // flushes profile to disk
612 if *memProfile
!= "" {
613 f
, err
:= os
.Create(toOutputDir(*memProfile
))
615 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
618 if err
= pprof
.WriteHeapProfile(f
); err
!= nil {
619 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *memProfile
, err
)
624 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
625 f
, err
:= os
.Create(toOutputDir(*blockProfile
))
627 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
630 if err
= pprof
.Lookup("block").WriteTo(f
, 0); err
!= nil {
631 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *blockProfile
, err
)
636 if cover
.Mode
!= "" {
641 // toOutputDir returns the file name relocated, if required, to outputDir.
642 // Simple implementation to avoid pulling in path/filepath.
643 func toOutputDir(path
string) string {
644 if *outputDir
== "" || path
== "" {
647 if runtime
.GOOS
== "windows" {
648 // On Windows, it's clumsy, but we can be almost always correct
649 // by just looking for a drive letter and a colon.
650 // Absolute paths always have a drive letter (ignoring UNC).
651 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
652 // what to do, but even then path/filepath doesn't help.
653 // TODO: Worth doing better? Probably not, because we're here only
654 // under the management of go test.
656 letter
, colon
:= path
[0], path
[1]
657 if ('a' <= letter
&& letter
<= 'z' ||
'A' <= letter
&& letter
<= 'Z') && colon
== ':' {
658 // If path starts with a drive letter we're stuck with it regardless.
663 if os
.IsPathSeparator(path
[0]) {
666 return fmt
.Sprintf("%s%c%s", *outputDir
, os
.PathSeparator
, path
)
669 var timer
*time
.Timer
671 // startAlarm starts an alarm if requested.
674 timer
= time
.AfterFunc(*timeout
, func() {
675 panic(fmt
.Sprintf("test timed out after %v", *timeout
))
680 // stopAlarm turns off the alarm.
687 func parseCpuList() {
688 for _
, val
:= range strings
.Split(*cpuListStr
, ",") {
689 val
= strings
.TrimSpace(val
)
693 cpu
, err
:= strconv
.Atoi(val
)
694 if err
!= nil || cpu
<= 0 {
695 fmt
.Fprintf(os
.Stderr
, "testing: invalid value %q for -test.cpu\n", val
)
698 cpuList
= append(cpuList
, cpu
)
701 cpuList
= append(cpuList
, runtime
.GOMAXPROCS(-1))