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 does not start with a lowercase letter. The function name
10 // 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 // https://golang.org/cmd/go/#hdr-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 // During benchmark execution, b.N is adjusted 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 // The comment prefix "Unordered output:" is like "Output:", but matches any
101 // func ExamplePerm() {
102 // for _, value := range Perm(4) {
103 // fmt.Println(value)
105 // // Unordered output: 4
112 // Example functions without output comments are compiled but not executed.
114 // The naming convention to declare examples for the package, a function F, a type T and
115 // method M on type T are:
117 // func Example() { ... }
118 // func ExampleF() { ... }
119 // func ExampleT() { ... }
120 // func ExampleT_M() { ... }
122 // Multiple example functions for a package/type/function/method may be provided by
123 // appending a distinct suffix to the name. The suffix must start with a
124 // lower-case letter.
126 // func Example_suffix() { ... }
127 // func ExampleF_suffix() { ... }
128 // func ExampleT_suffix() { ... }
129 // func ExampleT_M_suffix() { ... }
131 // The entire test file is presented as the example when it contains a single
132 // example function, at least one other function, type, variable, or constant
133 // declaration, and no test or benchmark functions.
135 // Subtests and Sub-benchmarks
137 // The Run methods of T and B allow defining subtests and sub-benchmarks,
138 // without having to define separate functions for each. This enables uses
139 // like table-driven benchmarks and creating hierarchical tests.
140 // It also provides a way to share common setup and tear-down code:
142 // func TestFoo(t *testing.T) {
144 // t.Run("A=1", func(t *testing.T) { ... })
145 // t.Run("A=2", func(t *testing.T) { ... })
146 // t.Run("B=1", func(t *testing.T) { ... })
147 // // <tear-down code>
150 // Each subtest and sub-benchmark has a unique name: the combination of the name
151 // of the top-level test and the sequence of names passed to Run, separated by
152 // slashes, with an optional trailing sequence number for disambiguation.
154 // The argument to the -run and -bench command-line flags is an unanchored regular
155 // expression that matches the test's name. For tests with multiple slash-separated
156 // elements, such as subtests, the argument is itself slash-separated, with
157 // expressions matching each name element in turn. Because it is unanchored, an
158 // empty expression matches any string.
159 // For example, using "matching" to mean "whose name contains":
161 // go test -run '' # Run all tests.
162 // go test -run Foo # Run top-level tests matching "Foo", such as "TestFooBar".
163 // go test -run Foo/A= # For top-level tests matching "Foo", run subtests matching "A=".
164 // go test -run /A=1 # For all top-level tests, run subtests matching "A=1".
166 // Subtests can also be used to control parallelism. A parent test will only
167 // complete once all of its subtests complete. In this example, all tests are
168 // run in parallel with each other, and only with each other, regardless of
169 // other top-level tests that may be defined:
171 // func TestGroupedParallel(t *testing.T) {
172 // for _, tc := range tests {
173 // tc := tc // capture range variable
174 // t.Run(tc.Name, func(t *testing.T) {
181 // The race detector kills the program if it exceeds 8192 concurrent goroutines,
182 // so use care when running parallel tests with the -race flag set.
184 // Run does not return until parallel subtests have completed, providing a way
185 // to clean up after a group of parallel tests:
187 // func TestTeardownParallel(t *testing.T) {
188 // // This Run will not return until the parallel tests finish.
189 // t.Run("group", func(t *testing.T) {
190 // t.Run("Test1", parallelTest1)
191 // t.Run("Test2", parallelTest2)
192 // t.Run("Test3", parallelTest3)
194 // // <tear-down code>
199 // It is sometimes necessary for a test program to do extra setup or teardown
200 // before or after testing. It is also sometimes necessary for a test to control
201 // which code runs on the main thread. To support these and other cases,
202 // if a test file contains a function:
204 // func TestMain(m *testing.M)
206 // then the generated test will call TestMain(m) instead of running the tests
207 // directly. TestMain runs in the main goroutine and can do whatever setup
208 // and teardown is necessary around a call to m.Run. It should then call
209 // os.Exit with the result of m.Run. When TestMain is called, flag.Parse has
210 // not been run. If TestMain depends on command-line flags, including those
211 // of the testing package, it should call flag.Parse explicitly.
213 // A simple implementation of TestMain is:
215 // func TestMain(m *testing.M) {
216 // // call flag.Parse() here if TestMain uses flags
241 // The short flag requests that tests run more quickly, but its functionality
242 // is provided by test writers themselves. The testing package is just its
243 // home. The all.bash installation script sets it to make installation more
244 // efficient, but by default the flag is off so a plain "go test" will do a
245 // full test of the package.
246 short
= flag
.Bool("test.short", false, "run smaller test suite to save time")
248 // The failfast flag requests that test execution stop after the first test failure.
249 failFast
= flag
.Bool("test.failfast", false, "do not start new tests after the first test failure")
251 // The directory in which to create profile files and the like. When run from
252 // "go test", the binary always runs in the source directory for the package;
253 // this flag lets "go test" tell the binary to write the files in the directory where
254 // the "go test" command is run.
255 outputDir
= flag
.String("test.outputdir", "", "write profiles to `dir`")
257 // Report as tests are run; default is silent for success.
258 chatty
= flag
.Bool("test.v", false, "verbose: print additional output")
259 count
= flag
.Uint("test.count", 1, "run tests and benchmarks `n` times")
260 coverProfile
= flag
.String("test.coverprofile", "", "write a coverage profile to `file`")
261 matchList
= flag
.String("test.list", "", "list tests, examples, and benchmarks matching `regexp` then exit")
262 match
= flag
.String("test.run", "", "run only tests and examples matching `regexp`")
263 memProfile
= flag
.String("test.memprofile", "", "write an allocation profile to `file`")
264 memProfileRate
= flag
.Int("test.memprofilerate", 0, "set memory allocation profiling `rate` (see runtime.MemProfileRate)")
265 cpuProfile
= flag
.String("test.cpuprofile", "", "write a cpu profile to `file`")
266 blockProfile
= flag
.String("test.blockprofile", "", "write a goroutine blocking profile to `file`")
267 blockProfileRate
= flag
.Int("test.blockprofilerate", 1, "set blocking profile `rate` (see runtime.SetBlockProfileRate)")
268 mutexProfile
= flag
.String("test.mutexprofile", "", "write a mutex contention profile to the named file after execution")
269 mutexProfileFraction
= flag
.Int("test.mutexprofilefraction", 1, "if >= 0, calls runtime.SetMutexProfileFraction()")
270 traceFile
= flag
.String("test.trace", "", "write an execution trace to `file`")
271 timeout
= flag
.Duration("test.timeout", 0, "panic test binary after duration `d` (default 0, timeout disabled)")
272 cpuListStr
= flag
.String("test.cpu", "", "comma-separated `list` of cpu counts to run each test with")
273 parallel
= flag
.Int("test.parallel", runtime
.GOMAXPROCS(0), "run at most `n` tests in parallel")
274 testlog
= flag
.String("test.testlogfile", "", "write test action log to `file` (for use only by cmd/go)")
276 haveExamples
bool // are there examples?
281 numFailed
uint32 // number of test failures
284 // The maximum number of stack frames to go through when skipping helper functions for
285 // the purpose of decorating log messages.
286 const maxStackLen
= 50
288 // common holds the elements common between T and B and
289 // captures common methods such as Errorf.
291 mu sync
.RWMutex
// guards this group of fields
292 output
[]byte // Output generated by test or benchmark.
293 w io
.Writer
// For flushToParent.
294 ran
bool // Test or benchmark (or one of its subtests) was executed.
295 failed
bool // Test or benchmark has failed.
296 skipped
bool // Test of benchmark has been skipped.
297 done
bool // Test is finished and all subtests have completed.
298 helpers
map[string]struct{} // functions to be skipped when writing file/line info
300 chatty
bool // A copy of the chatty flag.
301 finished
bool // Test function has completed.
302 hasSub
int32 // written atomically
303 raceErrors
int // number of races detected during test
304 runner
string // function name of tRunner running the test
307 level
int // Nesting depth of test or benchmark.
308 creator
[]uintptr // If level > 0, the stack trace at the point where the parent called t.Run.
309 name
string // Name of test or benchmark.
310 start time
.Time
// Time test or benchmark started
311 duration time
.Duration
312 barrier
chan bool // To signal parallel subtests they may start.
313 signal
chan bool // To signal a test is done.
314 sub
[]*T
// Queue of subtests to be run in parallel.
317 // Short reports whether the -test.short flag is set.
322 // CoverMode reports what the test coverage mode is set to. The
323 // values are "set", "count", or "atomic". The return value will be
324 // empty if test coverage is not enabled.
325 func CoverMode() string {
329 // Verbose reports whether the -test.v flag is set.
330 func Verbose() bool {
334 // frameSkip searches, starting after skip frames, for the first caller frame
335 // in a function not marked as a helper and returns that frame.
336 // The search stops if it finds a tRunner function that
337 // was the entry point into the test and the test is not a subtest.
338 // This function must be called with c.mu held.
339 func (c
*common
) frameSkip(skip
int) runtime
.Frame
{
340 // If the search continues into the parent test, we'll have to hold
341 // its mu temporarily. If we then return, we need to unlock it.
342 shouldUnlock
:= false
348 var pc
[maxStackLen
]uintptr
349 // Skip two extra frames to account for this function
350 // and runtime.Callers itself.
351 n
:= runtime
.Callers(skip
+2, pc
[:])
353 panic("testing: zero callers found")
355 frames
:= runtime
.CallersFrames(pc
[:n
])
356 var firstFrame
, prevFrame
, frame runtime
.Frame
357 for more
:= true; more
; prevFrame
= frame
{
358 frame
, more
= frames
.Next()
359 if firstFrame
.PC
== 0 {
362 if frame
.Function
== c
.runner
{
363 // We've gone up all the way to the tRunner calling
364 // the test function (so the user must have
365 // called tb.Helper from inside that test function).
366 // If this is a top-level test, only skip up to the test function itself.
367 // If we're in a subtest, continue searching in the parent test,
368 // starting from the point of the call to Run which created this subtest.
370 frames
= runtime
.CallersFrames(c
.creator
)
372 // We're no longer looking at the current c after this point,
373 // so we should unlock its mu, unless it's the original receiver,
374 // in which case our caller doesn't expect us to do that.
379 // Remember to unlock c.mu when we no longer need it, either
380 // because we went up another nesting level, or because we
388 if _
, ok
:= c
.helpers
[frame
.Function
]; !ok
{
389 // Found a frame that wasn't inside a helper function.
396 // decorate prefixes the string with the file and line of the call site
397 // and inserts the final newline if needed and indentation spaces for formatting.
398 // This function must be called with c.mu held.
399 func (c
*common
) decorate(s
string) string {
400 frame
:= c
.frameSkip(3) // decorate + log + public function.
404 // Truncate file name at last file name separator.
405 if index
:= strings
.LastIndex(file
, "/"); index
>= 0 {
406 file
= file
[index
+1:]
407 } else if index
= strings
.LastIndex(file
, "\\"); index
>= 0 {
408 file
= file
[index
+1:]
416 buf
:= new(strings
.Builder
)
417 // Every line is indented at least 4 spaces.
419 fmt
.Fprintf(buf
, "%s:%d: ", file
, line
)
420 lines
:= strings
.Split(s
, "\n")
421 if l
:= len(lines
); l
> 1 && lines
[l
-1] == "" {
424 for i
, line
:= range lines
{
426 // Second and subsequent lines are indented an additional 4 spaces.
427 buf
.WriteString("\n ")
429 buf
.WriteString(line
)
435 // flushToParent writes c.output to the parent after first writing the header
436 // with the given format and arguments.
437 func (c
*common
) flushToParent(format
string, args
...interface{}) {
442 fmt
.Fprintf(p
.w
, format
, args
...)
446 io
.Copy(p
.w
, bytes
.NewReader(c
.output
))
447 c
.output
= c
.output
[:0]
450 type indenter
struct {
454 func (w indenter
) Write(b
[]byte) (n
int, err error
) {
457 end
:= bytes
.IndexByte(b
, '\n')
463 // An indent of 4 spaces will neatly align the dashes with the status
464 // indicator of the parent.
466 w
.c
.output
= append(w
.c
.output
, indent
...)
467 w
.c
.output
= append(w
.c
.output
, b
[:end
]...)
473 // fmtDuration returns a string representing d in the form "87.00s".
474 func fmtDuration(d time
.Duration
) string {
475 return fmt
.Sprintf("%.2fs", d
.Seconds())
478 // TB is the interface common to T and B.
480 Error(args
...interface{})
481 Errorf(format
string, args
...interface{})
485 Fatal(args
...interface{})
486 Fatalf(format
string, args
...interface{})
487 Log(args
...interface{})
488 Logf(format
string, args
...interface{})
490 Skip(args
...interface{})
492 Skipf(format
string, args
...interface{})
496 // A private method to prevent users implementing the
497 // interface and so future additions to it will not
498 // violate Go 1 compatibility.
505 // T is a type passed to Test functions to manage test state and support formatted test logs.
506 // Logs are accumulated during execution and dumped to standard output when done.
508 // A test ends when its Test function returns or calls any of the methods
509 // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as
510 // the Parallel method, must be called only from the goroutine running the
513 // The other reporting methods, such as the variations of Log and Error,
514 // may be called simultaneously from multiple goroutines.
518 context
*testContext
// For running tests and subtests.
521 func (c
*common
) private() {}
523 // Name returns the name of the running test or benchmark.
524 func (c
*common
) Name() string {
528 func (c
*common
) setRan() {
537 // Fail marks the function as having failed but continues execution.
538 func (c
*common
) Fail() {
544 // c.done needs to be locked to synchronize checks to c.done in parent tests.
546 panic("Fail in goroutine after " + c
.name
+ " has completed")
551 // Failed reports whether the function has failed.
552 func (c
*common
) Failed() bool {
556 return failed || c
.raceErrors
+race
.Errors() > 0
559 // FailNow marks the function as having failed and stops its execution
560 // by calling runtime.Goexit (which then runs all deferred calls in the
561 // current goroutine).
562 // Execution will continue at the next test or benchmark.
563 // FailNow must be called from the goroutine running the
564 // test or benchmark function, not from other goroutines
565 // created during the test. Calling FailNow does not stop
566 // those other goroutines.
567 func (c
*common
) FailNow() {
570 // Calling runtime.Goexit will exit the goroutine, which
571 // will run the deferred functions in this goroutine,
572 // which will eventually run the deferred lines in tRunner,
573 // which will signal to the test loop that this test is done.
575 // A previous version of this code said:
578 // c.signal <- c.self
581 // This previous version duplicated code (those lines are in
582 // tRunner no matter what), but worse the goroutine teardown
583 // implicit in runtime.Goexit was not guaranteed to complete
584 // before the test exited. If a test deferred an important cleanup
585 // function (like removing temporary files), there was no guarantee
586 // it would run on a test failure. Because we send on c.signal during
587 // a top-of-stack deferred function now, we know that the send
588 // only happens after any other stacked defers have completed.
593 // log generates the output. It's always at the same stack depth.
594 func (c
*common
) log(s
string) {
597 c
.output
= append(c
.output
, c
.decorate(s
)...)
600 // Log formats its arguments using default formatting, analogous to Println,
601 // and records the text in the error log. For tests, the text will be printed only if
602 // the test fails or the -test.v flag is set. For benchmarks, the text is always
603 // printed to avoid having performance depend on the value of the -test.v flag.
604 func (c
*common
) Log(args
...interface{}) { c
.log(fmt
.Sprintln(args
...)) }
606 // Logf formats its arguments according to the format, analogous to Printf, and
607 // records the text in the error log. A final newline is added if not provided. For
608 // tests, the text will be printed only if the test fails or the -test.v flag is
609 // set. For benchmarks, the text is always printed to avoid having performance
610 // depend on the value of the -test.v flag.
611 func (c
*common
) Logf(format
string, args
...interface{}) { c
.log(fmt
.Sprintf(format
, args
...)) }
613 // Error is equivalent to Log followed by Fail.
614 func (c
*common
) Error(args
...interface{}) {
615 c
.log(fmt
.Sprintln(args
...))
619 // Errorf is equivalent to Logf followed by Fail.
620 func (c
*common
) Errorf(format
string, args
...interface{}) {
621 c
.log(fmt
.Sprintf(format
, args
...))
625 // Fatal is equivalent to Log followed by FailNow.
626 func (c
*common
) Fatal(args
...interface{}) {
627 c
.log(fmt
.Sprintln(args
...))
631 // Fatalf is equivalent to Logf followed by FailNow.
632 func (c
*common
) Fatalf(format
string, args
...interface{}) {
633 c
.log(fmt
.Sprintf(format
, args
...))
637 // Skip is equivalent to Log followed by SkipNow.
638 func (c
*common
) Skip(args
...interface{}) {
639 c
.log(fmt
.Sprintln(args
...))
643 // Skipf is equivalent to Logf followed by SkipNow.
644 func (c
*common
) Skipf(format
string, args
...interface{}) {
645 c
.log(fmt
.Sprintf(format
, args
...))
649 // SkipNow marks the test as having been skipped and stops its execution
650 // by calling runtime.Goexit.
651 // If a test fails (see Error, Errorf, Fail) and is then skipped,
652 // it is still considered to have failed.
653 // Execution will continue at the next test or benchmark. See also FailNow.
654 // SkipNow must be called from the goroutine running the test, not from
655 // other goroutines created during the test. Calling SkipNow does not stop
656 // those other goroutines.
657 func (c
*common
) SkipNow() {
663 func (c
*common
) skip() {
669 // Skipped reports whether the test was skipped.
670 func (c
*common
) Skipped() bool {
676 // Helper marks the calling function as a test helper function.
677 // When printing file and line information, that function will be skipped.
678 // Helper may be called simultaneously from multiple goroutines.
679 func (c
*common
) Helper() {
682 if c
.helpers
== nil {
683 c
.helpers
= make(map[string]struct{})
685 c
.helpers
[callerName(1)] = struct{}{}
688 // callerName gives the function name (qualified with a package path)
689 // for the caller after skip frames (where 0 means the current function).
690 func callerName(skip
int) string {
691 // Make room for the skip PC.
693 n
:= runtime
.Callers(skip
+2, pc
[:]) // skip + runtime.Callers + callerName
695 panic("testing: zero callers found")
697 frames
:= runtime
.CallersFrames(pc
[:n
])
698 frame
, _
:= frames
.Next()
699 return frame
.Function
702 // Parallel signals that this test is to be run in parallel with (and only with)
703 // other parallel tests. When a test is run multiple times due to use of
704 // -test.count or -test.cpu, multiple instances of a single test never run in
705 // parallel with each other.
706 func (t
*T
) Parallel() {
708 panic("testing: t.Parallel called multiple times")
712 // We don't want to include the time we spend waiting for serial tests
713 // in the test duration. Record the elapsed time thus far and reset the
715 t
.duration
+= time
.Since(t
.start
)
717 // Add to the list of tests to be released by the parent.
718 t
.parent
.sub
= append(t
.parent
.sub
, t
)
719 t
.raceErrors
+= race
.Errors()
722 // Print directly to root's io.Writer so there is no delay.
724 for ; root
.parent
!= nil; root
= root
.parent
{
727 fmt
.Fprintf(root
.w
, "=== PAUSE %s\n", t
.name
)
731 t
.signal
<- true // Release calling test.
732 <-t
.parent
.barrier
// Wait for the parent test to complete.
733 t
.context
.waitParallel()
736 // Print directly to root's io.Writer so there is no delay.
738 for ; root
.parent
!= nil; root
= root
.parent
{
741 fmt
.Fprintf(root
.w
, "=== CONT %s\n", t
.name
)
746 t
.raceErrors
+= -race
.Errors()
749 // An internal type but exported because it is cross-package; part of the implementation
750 // of the "go test" command.
751 type InternalTest
struct {
756 var errNilPanicOrGoexit
= errors
.New("test executed panic(nil) or runtime.Goexit")
758 func tRunner(t
*T
, fn
func(t
*T
)) {
759 t
.runner
= callerName(0)
761 // When this goroutine is done, either because fn(t)
762 // returned normally or because a test failure triggered
763 // a call to runtime.Goexit, record the duration and send
764 // a signal saying that the test is done.
767 atomic
.AddUint32(&numFailed
, 1)
770 if t
.raceErrors
+race
.Errors() > 0 {
771 t
.Errorf("race detected during execution of test")
774 t
.duration
+= time
.Since(t
.start
)
775 // If the test panicked, print any test output before dying.
778 if !t
.finished
&& err
== nil {
779 err
= errNilPanicOrGoexit
780 for p
:= t
.parent
; p
!= nil; p
= p
.parent
{
782 t
.Errorf("%v: subtest may have called FailNow on a parent test", err
)
796 // Run parallel subtests.
797 // Decrease the running count for this test.
799 // Release the parallel subtests.
801 // Wait for subtests to complete.
802 for _
, sub
:= range t
.sub
{
806 // Reacquire the count for sequential tests. See comment in Run.
807 t
.context
.waitParallel()
809 } else if t
.isParallel
{
810 // Only release the count for this test if it was run as a parallel
811 // test. See comment in Run method.
814 t
.report() // Report after all subtests have finished.
816 // Do not lock t.done to allow race detector to detect race in case
817 // the user does not appropriately synchronizes a goroutine.
819 if t
.parent
!= nil && atomic
.LoadInt32(&t
.hasSub
) == 0 {
826 t
.raceErrors
= -race
.Errors()
829 // code beyond here will not be executed when FailNow is invoked
833 // Run runs f as a subtest of t called name. It runs f in a separate goroutine
834 // and blocks until f returns or calls t.Parallel to become a parallel test.
835 // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
837 // Run may be called simultaneously from multiple goroutines, but all such calls
838 // must return before the outer test function for t returns.
839 func (t
*T
) Run(name
string, f
func(t
*T
)) bool {
840 atomic
.StoreInt32(&t
.hasSub
, 1)
841 testName
, ok
, _
:= t
.context
.match
.fullName(&t
.common
, name
)
842 if !ok ||
shouldFailFast() {
845 // Record the stack trace at the point of this call so that if the subtest
846 // function - which runs in a separate stack - is marked as a helper, we can
847 // continue walking the stack into the parent test.
848 var pc
[maxStackLen
]uintptr
849 n
:= runtime
.Callers(2, pc
[:])
852 barrier
: make(chan bool),
853 signal
: make(chan bool),
862 t
.w
= indenter
{&t
.common
}
865 // Print directly to root's io.Writer so there is no delay.
867 for ; root
.parent
!= nil; root
= root
.parent
{
870 fmt
.Fprintf(root
.w
, "=== RUN %s\n", t
.name
)
873 // Instead of reducing the running count of this test before calling the
874 // tRunner and increasing it afterwards, we rely on tRunner keeping the
875 // count correct. This ensures that a sequence of sequential tests runs
876 // without being preempted, even when their parent is a parallel test. This
877 // may especially reduce surprises if *parallel == 1.
880 // At this point, it is likely that FailNow was called on one of the
881 // parent tests by one of the subtests. Continue aborting up the chain.
887 // testContext holds all fields that are common to all tests. This includes
888 // synchronization primitives to run at most *parallel tests.
889 type testContext
struct {
894 // Channel used to signal tests that are ready to be run in parallel.
895 startParallel
chan bool
897 // running is the number of tests currently running in parallel.
898 // This does not include tests that are waiting for subtests to complete.
901 // numWaiting is the number tests waiting to be run in parallel.
904 // maxParallel is a copy of the parallel flag.
908 func newTestContext(maxParallel
int, m
*matcher
) *testContext
{
911 startParallel
: make(chan bool),
912 maxParallel
: maxParallel
,
913 running
: 1, // Set the count to 1 for the main (sequential) test.
917 func (c
*testContext
) waitParallel() {
919 if c
.running
< c
.maxParallel
{
929 func (c
*testContext
) release() {
931 if c
.numWaiting
== 0 {
938 c
.startParallel
<- true // Pick a waiting test to be run.
941 // No one should be using func Main anymore.
942 // See the doc comment on func Main and use MainStart instead.
943 var errMain
= errors
.New("testing: unexpected use of func Main")
945 type matchStringOnly
func(pat
, str
string) (bool, error
)
947 func (f matchStringOnly
) MatchString(pat
, str
string) (bool, error
) { return f(pat
, str
) }
948 func (f matchStringOnly
) StartCPUProfile(w io
.Writer
) error
{ return errMain
}
949 func (f matchStringOnly
) StopCPUProfile() {}
950 func (f matchStringOnly
) WriteProfileTo(string, io
.Writer
, int) error
{ return errMain
}
951 func (f matchStringOnly
) ImportPath() string { return "" }
952 func (f matchStringOnly
) StartTestLog(io
.Writer
) {}
953 func (f matchStringOnly
) StopTestLog() error
{ return errMain
}
955 // Main is an internal function, part of the implementation of the "go test" command.
956 // It was exported because it is cross-package and predates "internal" packages.
957 // It is no longer used by "go test" but preserved, as much as possible, for other
958 // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
959 // new functionality is added to the testing package.
960 // Systems simulating "go test" should be updated to use MainStart.
961 func Main(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) {
962 os
.Exit(MainStart(matchStringOnly(matchString
), tests
, benchmarks
, examples
).Run())
965 // M is a type passed to a TestMain function to run the actual tests.
969 benchmarks
[]InternalBenchmark
970 examples
[]InternalExample
978 // testDeps is an internal interface of functionality that is
979 // passed into this package by a test's generated main package.
980 // The canonical implementation of this interface is
981 // testing/internal/testdeps's TestDeps.
982 type testDeps
interface {
984 MatchString(pat
, str
string) (bool, error
)
985 StartCPUProfile(io
.Writer
) error
987 StartTestLog(io
.Writer
)
989 WriteProfileTo(string, io
.Writer
, int) error
992 // MainStart is meant for use by tests generated by 'go test'.
993 // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
994 // It may change signature from release to release.
995 func MainStart(deps testDeps
, tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) *M
{
999 benchmarks
: benchmarks
,
1004 // Run runs the tests. It returns an exit code to pass to os.Exit.
1005 func (m
*M
) Run() int {
1006 // Count the number of calls to m.Run.
1007 // We only ever expected 1, but we didn't enforce that,
1008 // and now there are tests in the wild that call m.Run multiple times.
1009 // Sigh. golang.org/issue/23129.
1012 // TestMain may have already called flag.Parse.
1018 fmt
.Fprintln(os
.Stderr
, "testing: -parallel can only be given a positive integer")
1023 if len(*matchList
) != 0 {
1024 listTests(m
.deps
.MatchString
, m
.tests
, m
.benchmarks
, m
.examples
)
1033 haveExamples
= len(m
.examples
) > 0
1034 testRan
, testOk
:= runTests(m
.deps
.MatchString
, m
.tests
)
1035 exampleRan
, exampleOk
:= runExamples(m
.deps
.MatchString
, m
.examples
)
1037 if !testRan
&& !exampleRan
&& *matchBenchmarks
== "" {
1038 fmt
.Fprintln(os
.Stderr
, "testing: warning: no tests to run")
1040 if !testOk ||
!exampleOk ||
!runBenchmarks(m
.deps
.ImportPath(), m
.deps
.MatchString
, m
.benchmarks
) || race
.Errors() > 0 {
1049 func (t
*T
) report() {
1050 if t
.parent
== nil {
1053 dstr
:= fmtDuration(t
.duration
)
1054 format
:= "--- %s: %s (%s)\n"
1056 t
.flushToParent(format
, "FAIL", t
.name
, dstr
)
1057 } else if t
.chatty
{
1059 t
.flushToParent(format
, "SKIP", t
.name
, dstr
)
1061 t
.flushToParent(format
, "PASS", t
.name
, dstr
)
1066 func listTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) {
1067 if _
, err
:= matchString(*matchList
, "non-empty"); err
!= nil {
1068 fmt
.Fprintf(os
.Stderr
, "testing: invalid regexp in -test.list (%q): %s\n", *matchList
, err
)
1072 for _
, test
:= range tests
{
1073 if ok
, _
:= matchString(*matchList
, test
.Name
); ok
{
1074 fmt
.Println(test
.Name
)
1077 for _
, bench
:= range benchmarks
{
1078 if ok
, _
:= matchString(*matchList
, bench
.Name
); ok
{
1079 fmt
.Println(bench
.Name
)
1082 for _
, example
:= range examples
{
1083 if ok
, _
:= matchString(*matchList
, example
.Name
); ok
{
1084 fmt
.Println(example
.Name
)
1089 // An internal function but exported because it is cross-package; part of the implementation
1090 // of the "go test" command.
1091 func RunTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
) (ok
bool) {
1092 ran
, ok
:= runTests(matchString
, tests
)
1093 if !ran
&& !haveExamples
{
1094 fmt
.Fprintln(os
.Stderr
, "testing: warning: no tests to run")
1099 func runTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
) (ran
, ok
bool) {
1101 for _
, procs
:= range cpuList
{
1102 runtime
.GOMAXPROCS(procs
)
1103 for i
:= uint(0); i
< *count
; i
++ {
1104 if shouldFailFast() {
1107 ctx
:= newTestContext(*parallel
, newMatcher(matchString
, *match
, "-test.run"))
1110 signal
: make(chan bool),
1111 barrier
: make(chan bool),
1117 tRunner(t
, func(t
*T
) {
1118 for _
, test
:= range tests
{
1119 t
.Run(test
.Name
, test
.F
)
1121 // Run catching the signal rather than the tRunner as a separate
1122 // goroutine to avoid adding a goroutine during the sequential
1123 // phase as this pollutes the stacktrace output when aborting.
1124 go func() { <-t
.signal
}()
1126 ok
= ok
&& !t
.Failed()
1133 // before runs before all testing.
1134 func (m
*M
) before() {
1135 if *memProfileRate
> 0 {
1136 runtime
.MemProfileRate
= *memProfileRate
1138 if *cpuProfile
!= "" {
1139 f
, err
:= os
.Create(toOutputDir(*cpuProfile
))
1141 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1144 if err
:= m
.deps
.StartCPUProfile(f
); err
!= nil {
1145 fmt
.Fprintf(os
.Stderr
, "testing: can't start cpu profile: %s\n", err
)
1149 // Could save f so after can call f.Close; not worth the effort.
1151 if *traceFile
!= "" {
1152 f
, err
:= os
.Create(toOutputDir(*traceFile
))
1154 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1157 if err
:= trace
.Start(f
); err
!= nil {
1158 fmt
.Fprintf(os
.Stderr
, "testing: can't start tracing: %s\n", err
)
1162 // Could save f so after can call f.Close; not worth the effort.
1164 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
1165 runtime
.SetBlockProfileRate(*blockProfileRate
)
1167 if *mutexProfile
!= "" && *mutexProfileFraction
>= 0 {
1168 runtime
.SetMutexProfileFraction(*mutexProfileFraction
)
1170 if *coverProfile
!= "" && cover
.Mode
== "" {
1171 fmt
.Fprintf(os
.Stderr
, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
1175 // Note: Not using toOutputDir.
1176 // This file is for use by cmd/go, not users.
1180 f
, err
= os
.Create(*testlog
)
1182 f
, err
= os
.OpenFile(*testlog
, os
.O_WRONLY
, 0)
1184 f
.Seek(0, io
.SeekEnd
)
1188 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1191 m
.deps
.StartTestLog(f
)
1196 // after runs after all testing.
1197 func (m
*M
) after() {
1198 m
.afterOnce
.Do(func() {
1203 func (m
*M
) writeProfiles() {
1205 if err
:= m
.deps
.StopTestLog(); err
!= nil {
1206 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *testlog
, err
)
1209 if err
:= testlogFile
.Close(); err
!= nil {
1210 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *testlog
, err
)
1214 if *cpuProfile
!= "" {
1215 m
.deps
.StopCPUProfile() // flushes profile to disk
1217 if *traceFile
!= "" {
1218 trace
.Stop() // flushes trace to disk
1220 if *memProfile
!= "" {
1221 f
, err
:= os
.Create(toOutputDir(*memProfile
))
1223 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1226 runtime
.GC() // materialize all statistics
1227 if err
= m
.deps
.WriteProfileTo("allocs", f
, 0); err
!= nil {
1228 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *memProfile
, err
)
1233 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
1234 f
, err
:= os
.Create(toOutputDir(*blockProfile
))
1236 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1239 if err
= m
.deps
.WriteProfileTo("block", f
, 0); err
!= nil {
1240 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *blockProfile
, err
)
1245 if *mutexProfile
!= "" && *mutexProfileFraction
>= 0 {
1246 f
, err
:= os
.Create(toOutputDir(*mutexProfile
))
1248 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1251 if err
= m
.deps
.WriteProfileTo("mutex", f
, 0); err
!= nil {
1252 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *blockProfile
, err
)
1257 if cover
.Mode
!= "" {
1262 // toOutputDir returns the file name relocated, if required, to outputDir.
1263 // Simple implementation to avoid pulling in path/filepath.
1264 func toOutputDir(path
string) string {
1265 if *outputDir
== "" || path
== "" {
1268 if runtime
.GOOS
== "windows" {
1269 // On Windows, it's clumsy, but we can be almost always correct
1270 // by just looking for a drive letter and a colon.
1271 // Absolute paths always have a drive letter (ignoring UNC).
1272 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
1273 // what to do, but even then path/filepath doesn't help.
1274 // TODO: Worth doing better? Probably not, because we're here only
1275 // under the management of go test.
1277 letter
, colon
:= path
[0], path
[1]
1278 if ('a' <= letter
&& letter
<= 'z' ||
'A' <= letter
&& letter
<= 'Z') && colon
== ':' {
1279 // If path starts with a drive letter we're stuck with it regardless.
1284 if os
.IsPathSeparator(path
[0]) {
1287 return fmt
.Sprintf("%s%c%s", *outputDir
, os
.PathSeparator
, path
)
1290 // startAlarm starts an alarm if requested.
1291 func (m
*M
) startAlarm() {
1293 m
.timer
= time
.AfterFunc(*timeout
, func() {
1295 debug
.SetTraceback("all")
1296 panic(fmt
.Sprintf("test timed out after %v", *timeout
))
1301 // stopAlarm turns off the alarm.
1302 func (m
*M
) stopAlarm() {
1308 func parseCpuList() {
1309 for _
, val
:= range strings
.Split(*cpuListStr
, ",") {
1310 val
= strings
.TrimSpace(val
)
1314 cpu
, err
:= strconv
.Atoi(val
)
1315 if err
!= nil || cpu
<= 0 {
1316 fmt
.Fprintf(os
.Stderr
, "testing: invalid value %q for -test.cpu\n", val
)
1319 cpuList
= append(cpuList
, cpu
)
1322 cpuList
= append(cpuList
, runtime
.GOMAXPROCS(-1))
1326 func shouldFailFast() bool {
1327 return *failFast
&& atomic
.LoadUint32(&numFailed
) > 0