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-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 // 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 // Run does not return until parallel subtests have completed, providing a way
182 // to clean up after a group of parallel tests:
184 // func TestTeardownParallel(t *testing.T) {
185 // // This Run will not return until the parallel tests finish.
186 // t.Run("group", func(t *testing.T) {
187 // t.Run("Test1", parallelTest1)
188 // t.Run("Test2", parallelTest2)
189 // t.Run("Test3", parallelTest3)
191 // // <tear-down code>
196 // It is sometimes necessary for a test program to do extra setup or teardown
197 // before or after testing. It is also sometimes necessary for a test to control
198 // which code runs on the main thread. To support these and other cases,
199 // if a test file contains a function:
201 // func TestMain(m *testing.M)
203 // then the generated test will call TestMain(m) instead of running the tests
204 // directly. TestMain runs in the main goroutine and can do whatever setup
205 // and teardown is necessary around a call to m.Run. It should then call
206 // os.Exit with the result of m.Run. When TestMain is called, flag.Parse has
207 // not been run. If TestMain depends on command-line flags, including those
208 // of the testing package, it should call flag.Parse explicitly.
210 // A simple implementation of TestMain is:
212 // func TestMain(m *testing.M) {
213 // // call flag.Parse() here if TestMain uses flags
238 // The short flag requests that tests run more quickly, but its functionality
239 // is provided by test writers themselves. The testing package is just its
240 // home. The all.bash installation script sets it to make installation more
241 // efficient, but by default the flag is off so a plain "go test" will do a
242 // full test of the package.
243 short
= flag
.Bool("test.short", false, "run smaller test suite to save time")
245 // The failfast flag requests that test execution stop after the first test failure.
246 failFast
= flag
.Bool("test.failfast", false, "do not start new tests after the first test failure")
248 // The directory in which to create profile files and the like. When run from
249 // "go test", the binary always runs in the source directory for the package;
250 // this flag lets "go test" tell the binary to write the files in the directory where
251 // the "go test" command is run.
252 outputDir
= flag
.String("test.outputdir", "", "write profiles to `dir`")
254 // Report as tests are run; default is silent for success.
255 chatty
= flag
.Bool("test.v", false, "verbose: print additional output")
256 count
= flag
.Uint("test.count", 1, "run tests and benchmarks `n` times")
257 coverProfile
= flag
.String("test.coverprofile", "", "write a coverage profile to `file`")
258 matchList
= flag
.String("test.list", "", "list tests, examples, and benchmarks matching `regexp` then exit")
259 match
= flag
.String("test.run", "", "run only tests and examples matching `regexp`")
260 memProfile
= flag
.String("test.memprofile", "", "write a memory profile to `file`")
261 memProfileRate
= flag
.Int("test.memprofilerate", 0, "set memory profiling `rate` (see runtime.MemProfileRate)")
262 cpuProfile
= flag
.String("test.cpuprofile", "", "write a cpu profile to `file`")
263 blockProfile
= flag
.String("test.blockprofile", "", "write a goroutine blocking profile to `file`")
264 blockProfileRate
= flag
.Int("test.blockprofilerate", 1, "set blocking profile `rate` (see runtime.SetBlockProfileRate)")
265 mutexProfile
= flag
.String("test.mutexprofile", "", "write a mutex contention profile to the named file after execution")
266 mutexProfileFraction
= flag
.Int("test.mutexprofilefraction", 1, "if >= 0, calls runtime.SetMutexProfileFraction()")
267 traceFile
= flag
.String("test.trace", "", "write an execution trace to `file`")
268 timeout
= flag
.Duration("test.timeout", 0, "panic test binary after duration `d` (default 0, timeout disabled)")
269 cpuListStr
= flag
.String("test.cpu", "", "comma-separated `list` of cpu counts to run each test with")
270 parallel
= flag
.Int("test.parallel", runtime
.GOMAXPROCS(0), "run at most `n` tests in parallel")
271 testlog
= flag
.String("test.testlogfile", "", "write test action log to `file` (for use only by cmd/go)")
273 haveExamples
bool // are there examples?
278 numFailed
uint32 // number of test failures
281 // common holds the elements common between T and B and
282 // captures common methods such as Errorf.
284 mu sync
.RWMutex
// guards this group of fields
285 output
[]byte // Output generated by test or benchmark.
286 w io
.Writer
// For flushToParent.
287 ran
bool // Test or benchmark (or one of its subtests) was executed.
288 failed
bool // Test or benchmark has failed.
289 skipped
bool // Test of benchmark has been skipped.
290 done
bool // Test is finished and all subtests have completed.
291 helpers
map[string]struct{} // functions to be skipped when writing file/line info
293 chatty
bool // A copy of the chatty flag.
294 finished
bool // Test function has completed.
295 hasSub
int32 // written atomically
296 raceErrors
int // number of races detected during test
297 runner
string // function name of tRunner running the test
300 level
int // Nesting depth of test or benchmark.
301 name
string // Name of test or benchmark.
302 start time
.Time
// Time test or benchmark started
303 duration time
.Duration
304 barrier
chan bool // To signal parallel subtests they may start.
305 signal
chan bool // To signal a test is done.
306 sub
[]*T
// Queue of subtests to be run in parallel.
309 // Short reports whether the -test.short flag is set.
314 // CoverMode reports what the test coverage mode is set to. The
315 // values are "set", "count", or "atomic". The return value will be
316 // empty if test coverage is not enabled.
317 func CoverMode() string {
321 // Verbose reports whether the -test.v flag is set.
322 func Verbose() bool {
326 // frameSkip searches, starting after skip frames, for the first caller frame
327 // in a function not marked as a helper and returns the frames to skip
328 // to reach that site. The search stops if it finds a tRunner function that
329 // was the entry point into the test.
330 // This function must be called with c.mu held.
331 func (c
*common
) frameSkip(skip
int) int {
332 if c
.helpers
== nil {
336 // Skip two extra frames to account for this function
337 // and runtime.Callers itself.
338 n
:= runtime
.Callers(skip
+2, pc
[:])
340 panic("testing: zero callers found")
342 frames
:= runtime
.CallersFrames(pc
[:n
])
343 var frame runtime
.Frame
345 for i
:= 0; more
; i
++ {
346 frame
, more
= frames
.Next()
347 if frame
.Function
== c
.runner
{
348 // We've gone up all the way to the tRunner calling
349 // the test function (so the user must have
350 // called tb.Helper from inside that test function).
351 // Only skip up to the test function itself.
354 if _
, ok
:= c
.helpers
[frame
.Function
]; !ok
{
355 // Found a frame that wasn't inside a helper function.
362 // decorate prefixes the string with the file and line of the call site
363 // and inserts the final newline if needed and indentation tabs for formatting.
364 // This function must be called with c.mu held.
365 func (c
*common
) decorate(s
string) string {
366 skip
:= c
.frameSkip(3) // decorate + log + public function.
367 _
, file
, line
, ok
:= runtime
.Caller(skip
)
369 // Truncate file name at last file name separator.
370 if index
:= strings
.LastIndex(file
, "/"); index
>= 0 {
371 file
= file
[index
+1:]
372 } else if index
= strings
.LastIndex(file
, "\\"); index
>= 0 {
373 file
= file
[index
+1:]
379 buf
:= new(bytes
.Buffer
)
380 // Every line is indented at least one tab.
382 fmt
.Fprintf(buf
, "%s:%d: ", file
, line
)
383 lines
:= strings
.Split(s
, "\n")
384 if l
:= len(lines
); l
> 1 && lines
[l
-1] == "" {
387 for i
, line
:= range lines
{
389 // Second and subsequent lines are indented an extra tab.
390 buf
.WriteString("\n\t\t")
392 buf
.WriteString(line
)
398 // flushToParent writes c.output to the parent after first writing the header
399 // with the given format and arguments.
400 func (c
*common
) flushToParent(format
string, args
...interface{}) {
405 fmt
.Fprintf(p
.w
, format
, args
...)
409 io
.Copy(p
.w
, bytes
.NewReader(c
.output
))
410 c
.output
= c
.output
[:0]
413 type indenter
struct {
417 func (w indenter
) Write(b
[]byte) (n
int, err error
) {
420 end
:= bytes
.IndexByte(b
, '\n')
426 // An indent of 4 spaces will neatly align the dashes with the status
427 // indicator of the parent.
429 w
.c
.output
= append(w
.c
.output
, indent
...)
430 w
.c
.output
= append(w
.c
.output
, b
[:end
]...)
436 // fmtDuration returns a string representing d in the form "87.00s".
437 func fmtDuration(d time
.Duration
) string {
438 return fmt
.Sprintf("%.2fs", d
.Seconds())
441 // TB is the interface common to T and B.
443 Error(args
...interface{})
444 Errorf(format
string, args
...interface{})
448 Fatal(args
...interface{})
449 Fatalf(format
string, args
...interface{})
450 Log(args
...interface{})
451 Logf(format
string, args
...interface{})
453 Skip(args
...interface{})
455 Skipf(format
string, args
...interface{})
459 // A private method to prevent users implementing the
460 // interface and so future additions to it will not
461 // violate Go 1 compatibility.
468 // T is a type passed to Test functions to manage test state and support formatted test logs.
469 // Logs are accumulated during execution and dumped to standard output when done.
471 // A test ends when its Test function returns or calls any of the methods
472 // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as
473 // the Parallel method, must be called only from the goroutine running the
476 // The other reporting methods, such as the variations of Log and Error,
477 // may be called simultaneously from multiple goroutines.
481 context
*testContext
// For running tests and subtests.
484 func (c
*common
) private() {}
486 // Name returns the name of the running test or benchmark.
487 func (c
*common
) Name() string {
491 func (c
*common
) setRan() {
500 // Fail marks the function as having failed but continues execution.
501 func (c
*common
) Fail() {
507 // c.done needs to be locked to synchronize checks to c.done in parent tests.
509 panic("Fail in goroutine after " + c
.name
+ " has completed")
514 // Failed reports whether the function has failed.
515 func (c
*common
) Failed() bool {
519 return failed || c
.raceErrors
+race
.Errors() > 0
522 // FailNow marks the function as having failed and stops its execution
523 // by calling runtime.Goexit (which then runs all deferred calls in the
524 // current goroutine).
525 // Execution will continue at the next test or benchmark.
526 // FailNow must be called from the goroutine running the
527 // test or benchmark function, not from other goroutines
528 // created during the test. Calling FailNow does not stop
529 // those other goroutines.
530 func (c
*common
) FailNow() {
533 // Calling runtime.Goexit will exit the goroutine, which
534 // will run the deferred functions in this goroutine,
535 // which will eventually run the deferred lines in tRunner,
536 // which will signal to the test loop that this test is done.
538 // A previous version of this code said:
541 // c.signal <- c.self
544 // This previous version duplicated code (those lines are in
545 // tRunner no matter what), but worse the goroutine teardown
546 // implicit in runtime.Goexit was not guaranteed to complete
547 // before the test exited. If a test deferred an important cleanup
548 // function (like removing temporary files), there was no guarantee
549 // it would run on a test failure. Because we send on c.signal during
550 // a top-of-stack deferred function now, we know that the send
551 // only happens after any other stacked defers have completed.
556 // log generates the output. It's always at the same stack depth.
557 func (c
*common
) log(s
string) {
560 c
.output
= append(c
.output
, c
.decorate(s
)...)
563 // Log formats its arguments using default formatting, analogous to Println,
564 // and records the text in the error log. For tests, the text will be printed only if
565 // the test fails or the -test.v flag is set. For benchmarks, the text is always
566 // printed to avoid having performance depend on the value of the -test.v flag.
567 func (c
*common
) Log(args
...interface{}) { c
.log(fmt
.Sprintln(args
...)) }
569 // Logf formats its arguments according to the format, analogous to Printf, and
570 // records the text in the error log. A final newline is added if not provided. For
571 // tests, the text will be printed only if the test fails or the -test.v flag is
572 // set. For benchmarks, the text is always printed to avoid having performance
573 // depend on the value of the -test.v flag.
574 func (c
*common
) Logf(format
string, args
...interface{}) { c
.log(fmt
.Sprintf(format
, args
...)) }
576 // Error is equivalent to Log followed by Fail.
577 func (c
*common
) Error(args
...interface{}) {
578 c
.log(fmt
.Sprintln(args
...))
582 // Errorf is equivalent to Logf followed by Fail.
583 func (c
*common
) Errorf(format
string, args
...interface{}) {
584 c
.log(fmt
.Sprintf(format
, args
...))
588 // Fatal is equivalent to Log followed by FailNow.
589 func (c
*common
) Fatal(args
...interface{}) {
590 c
.log(fmt
.Sprintln(args
...))
594 // Fatalf is equivalent to Logf followed by FailNow.
595 func (c
*common
) Fatalf(format
string, args
...interface{}) {
596 c
.log(fmt
.Sprintf(format
, args
...))
600 // Skip is equivalent to Log followed by SkipNow.
601 func (c
*common
) Skip(args
...interface{}) {
602 c
.log(fmt
.Sprintln(args
...))
606 // Skipf is equivalent to Logf followed by SkipNow.
607 func (c
*common
) Skipf(format
string, args
...interface{}) {
608 c
.log(fmt
.Sprintf(format
, args
...))
612 // SkipNow marks the test as having been skipped and stops its execution
613 // by calling runtime.Goexit.
614 // If a test fails (see Error, Errorf, Fail) and is then skipped,
615 // it is still considered to have failed.
616 // Execution will continue at the next test or benchmark. See also FailNow.
617 // SkipNow must be called from the goroutine running the test, not from
618 // other goroutines created during the test. Calling SkipNow does not stop
619 // those other goroutines.
620 func (c
*common
) SkipNow() {
626 func (c
*common
) skip() {
632 // Skipped reports whether the test was skipped.
633 func (c
*common
) Skipped() bool {
639 // Helper marks the calling function as a test helper function.
640 // When printing file and line information, that function will be skipped.
641 // Helper may be called simultaneously from multiple goroutines.
642 // Helper has no effect if it is called directly from a TestXxx/BenchmarkXxx
643 // function or a subtest/sub-benchmark function.
644 func (c
*common
) Helper() {
647 if c
.helpers
== nil {
648 c
.helpers
= make(map[string]struct{})
650 c
.helpers
[callerName(1)] = struct{}{}
653 // callerName gives the function name (qualified with a package path)
654 // for the caller after skip frames (where 0 means the current function).
655 func callerName(skip
int) string {
656 // Make room for the skip PC.
658 n
:= runtime
.Callers(skip
+2, pc
[:]) // skip + runtime.Callers + callerName
660 panic("testing: zero callers found")
662 frames
:= runtime
.CallersFrames(pc
[:n
])
663 frame
, _
:= frames
.Next()
664 return frame
.Function
667 // Parallel signals that this test is to be run in parallel with (and only with)
668 // other parallel tests. When a test is run multiple times due to use of
669 // -test.count or -test.cpu, multiple instances of a single test never run in
670 // parallel with each other.
671 func (t
*T
) Parallel() {
673 panic("testing: t.Parallel called multiple times")
677 // We don't want to include the time we spend waiting for serial tests
678 // in the test duration. Record the elapsed time thus far and reset the
680 t
.duration
+= time
.Since(t
.start
)
682 // Add to the list of tests to be released by the parent.
683 t
.parent
.sub
= append(t
.parent
.sub
, t
)
684 t
.raceErrors
+= race
.Errors()
687 // Print directly to root's io.Writer so there is no delay.
689 for ; root
.parent
!= nil; root
= root
.parent
{
692 fmt
.Fprintf(root
.w
, "=== PAUSE %s\n", t
.name
)
696 t
.signal
<- true // Release calling test.
697 <-t
.parent
.barrier
// Wait for the parent test to complete.
698 t
.context
.waitParallel()
701 // Print directly to root's io.Writer so there is no delay.
703 for ; root
.parent
!= nil; root
= root
.parent
{
706 fmt
.Fprintf(root
.w
, "=== CONT %s\n", t
.name
)
711 t
.raceErrors
+= -race
.Errors()
714 // An internal type but exported because it is cross-package; part of the implementation
715 // of the "go test" command.
716 type InternalTest
struct {
721 func tRunner(t
*T
, fn
func(t
*T
)) {
722 t
.runner
= callerName(0)
724 // When this goroutine is done, either because fn(t)
725 // returned normally or because a test failure triggered
726 // a call to runtime.Goexit, record the duration and send
727 // a signal saying that the test is done.
729 if t
.raceErrors
+race
.Errors() > 0 {
730 t
.Errorf("race detected during execution of test")
733 t
.duration
+= time
.Since(t
.start
)
734 // If the test panicked, print any test output before dying.
736 if !t
.finished
&& err
== nil {
737 err
= fmt
.Errorf("test executed panic(nil) or runtime.Goexit")
746 // Run parallel subtests.
747 // Decrease the running count for this test.
749 // Release the parallel subtests.
751 // Wait for subtests to complete.
752 for _
, sub
:= range t
.sub
{
756 // Reacquire the count for sequential tests. See comment in Run.
757 t
.context
.waitParallel()
759 } else if t
.isParallel
{
760 // Only release the count for this test if it was run as a parallel
761 // test. See comment in Run method.
764 t
.report() // Report after all subtests have finished.
766 // Do not lock t.done to allow race detector to detect race in case
767 // the user does not appropriately synchronizes a goroutine.
769 if t
.parent
!= nil && atomic
.LoadInt32(&t
.hasSub
) == 0 {
776 t
.raceErrors
= -race
.Errors()
780 atomic
.AddUint32(&numFailed
, 1)
785 // Run runs f as a subtest of t called name. It runs f in a separate goroutine
786 // and blocks until f returns or calls t.Parallel to become a parallel test.
787 // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
789 // Run may be called simultaneously from multiple goroutines, but all such calls
790 // must return before the outer test function for t returns.
791 func (t
*T
) Run(name
string, f
func(t
*T
)) bool {
792 atomic
.StoreInt32(&t
.hasSub
, 1)
793 testName
, ok
, _
:= t
.context
.match
.fullName(&t
.common
, name
)
794 if !ok ||
shouldFailFast() {
799 barrier
: make(chan bool),
800 signal
: make(chan bool),
808 t
.w
= indenter
{&t
.common
}
811 // Print directly to root's io.Writer so there is no delay.
813 for ; root
.parent
!= nil; root
= root
.parent
{
816 fmt
.Fprintf(root
.w
, "=== RUN %s\n", t
.name
)
819 // Instead of reducing the running count of this test before calling the
820 // tRunner and increasing it afterwards, we rely on tRunner keeping the
821 // count correct. This ensures that a sequence of sequential tests runs
822 // without being preempted, even when their parent is a parallel test. This
823 // may especially reduce surprises if *parallel == 1.
829 // testContext holds all fields that are common to all tests. This includes
830 // synchronization primitives to run at most *parallel tests.
831 type testContext
struct {
836 // Channel used to signal tests that are ready to be run in parallel.
837 startParallel
chan bool
839 // running is the number of tests currently running in parallel.
840 // This does not include tests that are waiting for subtests to complete.
843 // numWaiting is the number tests waiting to be run in parallel.
846 // maxParallel is a copy of the parallel flag.
850 func newTestContext(maxParallel
int, m
*matcher
) *testContext
{
853 startParallel
: make(chan bool),
854 maxParallel
: maxParallel
,
855 running
: 1, // Set the count to 1 for the main (sequential) test.
859 func (c
*testContext
) waitParallel() {
861 if c
.running
< c
.maxParallel
{
871 func (c
*testContext
) release() {
873 if c
.numWaiting
== 0 {
880 c
.startParallel
<- true // Pick a waiting test to be run.
883 // No one should be using func Main anymore.
884 // See the doc comment on func Main and use MainStart instead.
885 var errMain
= errors
.New("testing: unexpected use of func Main")
887 type matchStringOnly
func(pat
, str
string) (bool, error
)
889 func (f matchStringOnly
) MatchString(pat
, str
string) (bool, error
) { return f(pat
, str
) }
890 func (f matchStringOnly
) StartCPUProfile(w io
.Writer
) error
{ return errMain
}
891 func (f matchStringOnly
) StopCPUProfile() {}
892 func (f matchStringOnly
) WriteHeapProfile(w io
.Writer
) error
{ return errMain
}
893 func (f matchStringOnly
) WriteProfileTo(string, io
.Writer
, int) error
{ return errMain
}
894 func (f matchStringOnly
) ImportPath() string { return "" }
895 func (f matchStringOnly
) StartTestLog(io
.Writer
) {}
896 func (f matchStringOnly
) StopTestLog() error
{ return errMain
}
898 // Main is an internal function, part of the implementation of the "go test" command.
899 // It was exported because it is cross-package and predates "internal" packages.
900 // It is no longer used by "go test" but preserved, as much as possible, for other
901 // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
902 // new functionality is added to the testing package.
903 // Systems simulating "go test" should be updated to use MainStart.
904 func Main(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) {
905 os
.Exit(MainStart(matchStringOnly(matchString
), tests
, benchmarks
, examples
).Run())
908 // M is a type passed to a TestMain function to run the actual tests.
912 benchmarks
[]InternalBenchmark
913 examples
[]InternalExample
921 // testDeps is an internal interface of functionality that is
922 // passed into this package by a test's generated main package.
923 // The canonical implementation of this interface is
924 // testing/internal/testdeps's TestDeps.
925 type testDeps
interface {
927 MatchString(pat
, str
string) (bool, error
)
928 StartCPUProfile(io
.Writer
) error
930 StartTestLog(io
.Writer
)
932 WriteHeapProfile(io
.Writer
) error
933 WriteProfileTo(string, io
.Writer
, int) error
936 // MainStart is meant for use by tests generated by 'go test'.
937 // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
938 // It may change signature from release to release.
939 func MainStart(deps testDeps
, tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) *M
{
943 benchmarks
: benchmarks
,
948 // Run runs the tests. It returns an exit code to pass to os.Exit.
949 func (m
*M
) Run() int {
950 // Count the number of calls to m.Run.
951 // We only ever expected 1, but we didn't enforce that,
952 // and now there are tests in the wild that call m.Run multiple times.
953 // Sigh. golang.org/issue/23129.
956 // TestMain may have already called flag.Parse.
962 fmt
.Fprintln(os
.Stderr
, "testing: -parallel can only be given a positive integer")
967 if len(*matchList
) != 0 {
968 listTests(m
.deps
.MatchString
, m
.tests
, m
.benchmarks
, m
.examples
)
977 haveExamples
= len(m
.examples
) > 0
978 testRan
, testOk
:= runTests(m
.deps
.MatchString
, m
.tests
)
979 exampleRan
, exampleOk
:= runExamples(m
.deps
.MatchString
, m
.examples
)
981 if !testRan
&& !exampleRan
&& *matchBenchmarks
== "" {
982 fmt
.Fprintln(os
.Stderr
, "testing: warning: no tests to run")
984 if !testOk ||
!exampleOk ||
!runBenchmarks(m
.deps
.ImportPath(), m
.deps
.MatchString
, m
.benchmarks
) || race
.Errors() > 0 {
993 func (t
*T
) report() {
997 dstr
:= fmtDuration(t
.duration
)
998 format
:= "--- %s: %s (%s)\n"
1000 t
.flushToParent(format
, "FAIL", t
.name
, dstr
)
1001 } else if t
.chatty
{
1003 t
.flushToParent(format
, "SKIP", t
.name
, dstr
)
1005 t
.flushToParent(format
, "PASS", t
.name
, dstr
)
1010 func listTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
, benchmarks
[]InternalBenchmark
, examples
[]InternalExample
) {
1011 if _
, err
:= matchString(*matchList
, "non-empty"); err
!= nil {
1012 fmt
.Fprintf(os
.Stderr
, "testing: invalid regexp in -test.list (%q): %s\n", *matchList
, err
)
1016 for _
, test
:= range tests
{
1017 if ok
, _
:= matchString(*matchList
, test
.Name
); ok
{
1018 fmt
.Println(test
.Name
)
1021 for _
, bench
:= range benchmarks
{
1022 if ok
, _
:= matchString(*matchList
, bench
.Name
); ok
{
1023 fmt
.Println(bench
.Name
)
1026 for _
, example
:= range examples
{
1027 if ok
, _
:= matchString(*matchList
, example
.Name
); ok
{
1028 fmt
.Println(example
.Name
)
1033 // An internal function but exported because it is cross-package; part of the implementation
1034 // of the "go test" command.
1035 func RunTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
) (ok
bool) {
1036 ran
, ok
:= runTests(matchString
, tests
)
1037 if !ran
&& !haveExamples
{
1038 fmt
.Fprintln(os
.Stderr
, "testing: warning: no tests to run")
1043 func runTests(matchString
func(pat
, str
string) (bool, error
), tests
[]InternalTest
) (ran
, ok
bool) {
1045 for _
, procs
:= range cpuList
{
1046 runtime
.GOMAXPROCS(procs
)
1047 for i
:= uint(0); i
< *count
; i
++ {
1048 if shouldFailFast() {
1051 ctx
:= newTestContext(*parallel
, newMatcher(matchString
, *match
, "-test.run"))
1054 signal
: make(chan bool),
1055 barrier
: make(chan bool),
1061 tRunner(t
, func(t
*T
) {
1062 for _
, test
:= range tests
{
1063 t
.Run(test
.Name
, test
.F
)
1065 // Run catching the signal rather than the tRunner as a separate
1066 // goroutine to avoid adding a goroutine during the sequential
1067 // phase as this pollutes the stacktrace output when aborting.
1068 go func() { <-t
.signal
}()
1070 ok
= ok
&& !t
.Failed()
1077 // before runs before all testing.
1078 func (m
*M
) before() {
1079 if *memProfileRate
> 0 {
1080 runtime
.MemProfileRate
= *memProfileRate
1082 if *cpuProfile
!= "" {
1083 f
, err
:= os
.Create(toOutputDir(*cpuProfile
))
1085 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1088 if err
:= m
.deps
.StartCPUProfile(f
); err
!= nil {
1089 fmt
.Fprintf(os
.Stderr
, "testing: can't start cpu profile: %s\n", err
)
1093 // Could save f so after can call f.Close; not worth the effort.
1095 if *traceFile
!= "" {
1096 f
, err
:= os
.Create(toOutputDir(*traceFile
))
1098 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1101 if err
:= trace
.Start(f
); err
!= nil {
1102 fmt
.Fprintf(os
.Stderr
, "testing: can't start tracing: %s\n", err
)
1106 // Could save f so after can call f.Close; not worth the effort.
1108 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
1109 runtime
.SetBlockProfileRate(*blockProfileRate
)
1111 if *mutexProfile
!= "" && *mutexProfileFraction
>= 0 {
1112 runtime
.SetMutexProfileFraction(*mutexProfileFraction
)
1114 if *coverProfile
!= "" && cover
.Mode
== "" {
1115 fmt
.Fprintf(os
.Stderr
, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
1119 // Note: Not using toOutputDir.
1120 // This file is for use by cmd/go, not users.
1124 f
, err
= os
.Create(*testlog
)
1126 f
, err
= os
.OpenFile(*testlog
, os
.O_WRONLY
, 0)
1128 f
.Seek(0, io
.SeekEnd
)
1132 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1135 m
.deps
.StartTestLog(f
)
1140 // after runs after all testing.
1141 func (m
*M
) after() {
1142 m
.afterOnce
.Do(func() {
1147 func (m
*M
) writeProfiles() {
1149 if err
:= m
.deps
.StopTestLog(); err
!= nil {
1150 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *testlog
, err
)
1153 if err
:= testlogFile
.Close(); err
!= nil {
1154 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *testlog
, err
)
1158 if *cpuProfile
!= "" {
1159 m
.deps
.StopCPUProfile() // flushes profile to disk
1161 if *traceFile
!= "" {
1162 trace
.Stop() // flushes trace to disk
1164 if *memProfile
!= "" {
1165 f
, err
:= os
.Create(toOutputDir(*memProfile
))
1167 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1170 runtime
.GC() // materialize all statistics
1171 if err
= m
.deps
.WriteHeapProfile(f
); err
!= nil {
1172 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *memProfile
, err
)
1177 if *blockProfile
!= "" && *blockProfileRate
>= 0 {
1178 f
, err
:= os
.Create(toOutputDir(*blockProfile
))
1180 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1183 if err
= m
.deps
.WriteProfileTo("block", f
, 0); err
!= nil {
1184 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *blockProfile
, err
)
1189 if *mutexProfile
!= "" && *mutexProfileFraction
>= 0 {
1190 f
, err
:= os
.Create(toOutputDir(*mutexProfile
))
1192 fmt
.Fprintf(os
.Stderr
, "testing: %s\n", err
)
1195 if err
= m
.deps
.WriteProfileTo("mutex", f
, 0); err
!= nil {
1196 fmt
.Fprintf(os
.Stderr
, "testing: can't write %s: %s\n", *blockProfile
, err
)
1201 if cover
.Mode
!= "" {
1206 // toOutputDir returns the file name relocated, if required, to outputDir.
1207 // Simple implementation to avoid pulling in path/filepath.
1208 func toOutputDir(path
string) string {
1209 if *outputDir
== "" || path
== "" {
1212 if runtime
.GOOS
== "windows" {
1213 // On Windows, it's clumsy, but we can be almost always correct
1214 // by just looking for a drive letter and a colon.
1215 // Absolute paths always have a drive letter (ignoring UNC).
1216 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
1217 // what to do, but even then path/filepath doesn't help.
1218 // TODO: Worth doing better? Probably not, because we're here only
1219 // under the management of go test.
1221 letter
, colon
:= path
[0], path
[1]
1222 if ('a' <= letter
&& letter
<= 'z' ||
'A' <= letter
&& letter
<= 'Z') && colon
== ':' {
1223 // If path starts with a drive letter we're stuck with it regardless.
1228 if os
.IsPathSeparator(path
[0]) {
1231 return fmt
.Sprintf("%s%c%s", *outputDir
, os
.PathSeparator
, path
)
1234 // startAlarm starts an alarm if requested.
1235 func (m
*M
) startAlarm() {
1237 m
.timer
= time
.AfterFunc(*timeout
, func() {
1239 debug
.SetTraceback("all")
1240 panic(fmt
.Sprintf("test timed out after %v", *timeout
))
1245 // stopAlarm turns off the alarm.
1246 func (m
*M
) stopAlarm() {
1252 func parseCpuList() {
1253 for _
, val
:= range strings
.Split(*cpuListStr
, ",") {
1254 val
= strings
.TrimSpace(val
)
1258 cpu
, err
:= strconv
.Atoi(val
)
1259 if err
!= nil || cpu
<= 0 {
1260 fmt
.Fprintf(os
.Stderr
, "testing: invalid value %q for -test.cpu\n", val
)
1263 cpuList
= append(cpuList
, cpu
)
1266 cpuList
= append(cpuList
, runtime
.GOMAXPROCS(-1))
1270 func shouldFailFast() bool {
1271 return *failFast
&& atomic
.LoadUint32(&numFailed
) > 0