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
9 // func TestXxx(*testing.T)
11 // where Xxx does not start with a lowercase letter. The function name
12 // serves to identify the test routine.
14 // Within these functions, use the Error, Fail or related methods to signal failure.
16 // To write a new test suite, create a file that
17 // contains the TestXxx functions as described here,
18 // and give that file a name ending in "_test.go".
19 // The file will be excluded from regular
20 // package builds but will be included when the "go test" command is run.
22 // The test file can be in the same package as the one being tested,
23 // or in a corresponding package with the suffix "_test".
25 // If the test file is in the same package, it may refer to unexported
26 // identifiers within the package, as in this example:
32 // func TestAbs(t *testing.T) {
35 // t.Errorf("Abs(-1) = %d; want 1", got)
39 // If the file is in a separate "_test" package, the package being tested
40 // must be imported explicitly and only its exported identifiers may be used.
41 // This is known as "black box" testing.
51 // func TestAbs(t *testing.T) {
54 // t.Errorf("Abs(-1) = %d; want 1", got)
58 // For more detail, run "go help test" and "go help testflag".
62 // Functions of the form
64 // func BenchmarkXxx(*testing.B)
66 // are considered benchmarks, and are executed by the "go test" command when
67 // its -bench flag is provided. Benchmarks are run sequentially.
69 // For a description of the testing flags, see
70 // https://golang.org/cmd/go/#hdr-Testing_flags.
72 // A sample benchmark function looks like this:
74 // func BenchmarkRandInt(b *testing.B) {
75 // for i := 0; i < b.N; i++ {
80 // The benchmark function must run the target code b.N times.
81 // During benchmark execution, b.N is adjusted until the benchmark function lasts
82 // long enough to be timed reliably. The output
84 // BenchmarkRandInt-8 68453040 17.8 ns/op
86 // means that the loop ran 68453040 times at a speed of 17.8 ns per loop.
88 // If a benchmark needs some expensive setup before running, the timer
91 // func BenchmarkBigLen(b *testing.B) {
94 // for i := 0; i < b.N; i++ {
99 // If a benchmark needs to test performance in a parallel setting, it may use
100 // the RunParallel helper function; such benchmarks are intended to be used with
101 // the go test -cpu flag:
103 // func BenchmarkTemplateParallel(b *testing.B) {
104 // templ := template.Must(template.New("test").Parse("Hello, {{.}}!"))
105 // b.RunParallel(func(pb *testing.PB) {
106 // var buf bytes.Buffer
109 // templ.Execute(&buf, "World")
114 // A detailed specification of the benchmark results format is given
115 // in https://golang.org/design/14313-benchmark-format.
117 // There are standard tools for working with benchmark results at
118 // https://golang.org/x/perf/cmd.
119 // In particular, https://golang.org/x/perf/cmd/benchstat performs
120 // statistically robust A/B comparisons.
124 // The package also runs and verifies example code. Example functions may
125 // include a concluding line comment that begins with "Output:" and is compared with
126 // the standard output of the function when the tests are run. (The comparison
127 // ignores leading and trailing space.) These are examples of an example:
129 // func ExampleHello() {
130 // fmt.Println("hello")
134 // func ExampleSalutations() {
135 // fmt.Println("hello, and")
136 // fmt.Println("goodbye")
142 // The comment prefix "Unordered output:" is like "Output:", but matches any
145 // func ExamplePerm() {
146 // for _, value := range Perm(5) {
147 // fmt.Println(value)
149 // // Unordered output: 4
156 // Example functions without output comments are compiled but not executed.
158 // The naming convention to declare examples for the package, a function F, a type T and
159 // method M on type T are:
161 // func Example() { ... }
162 // func ExampleF() { ... }
163 // func ExampleT() { ... }
164 // func ExampleT_M() { ... }
166 // Multiple example functions for a package/type/function/method may be provided by
167 // appending a distinct suffix to the name. The suffix must start with a
168 // lower-case letter.
170 // func Example_suffix() { ... }
171 // func ExampleF_suffix() { ... }
172 // func ExampleT_suffix() { ... }
173 // func ExampleT_M_suffix() { ... }
175 // The entire test file is presented as the example when it contains a single
176 // example function, at least one other function, type, variable, or constant
177 // declaration, and no test or benchmark functions.
181 // 'go test' and the testing package support fuzzing, a testing technique where
182 // a function is called with randomly generated inputs to find bugs not
183 // anticipated by unit tests.
185 // Functions of the form
187 // func FuzzXxx(*testing.F)
189 // are considered fuzz tests.
193 // func FuzzHex(f *testing.F) {
194 // for _, seed := range [][]byte{{}, {0}, {9}, {0xa}, {0xf}, {1, 2, 3, 4}} {
197 // f.Fuzz(func(t *testing.T, in []byte) {
198 // enc := hex.EncodeToString(in)
199 // out, err := hex.DecodeString(enc)
201 // t.Fatalf("%v: decode: %v", in, err)
203 // if !bytes.Equal(in, out) {
204 // t.Fatalf("%v: not equal after round trip: %v", in, out)
209 // A fuzz test maintains a seed corpus, or a set of inputs which are run by
210 // default, and can seed input generation. Seed inputs may be registered by
211 // calling (*F).Add or by storing files in the directory testdata/fuzz/<Name>
212 // (where <Name> is the name of the fuzz test) within the package containing
213 // the fuzz test. Seed inputs are optional, but the fuzzing engine may find
214 // bugs more efficiently when provided with a set of small seed inputs with good
215 // code coverage. These seed inputs can also serve as regression tests for bugs
216 // identified through fuzzing.
218 // The function passed to (*F).Fuzz within the fuzz test is considered the fuzz
219 // target. A fuzz target must accept a *T parameter, followed by one or more
220 // parameters for random inputs. The types of arguments passed to (*F).Add must
221 // be identical to the types of these parameters. The fuzz target may signal
222 // that it's found a problem the same way tests do: by calling T.Fail (or any
223 // method that calls it like T.Error or T.Fatal) or by panicking.
225 // When fuzzing is enabled (by setting the -fuzz flag to a regular expression
226 // that matches a specific fuzz test), the fuzz target is called with arguments
227 // generated by repeatedly making random changes to the seed inputs. On
228 // supported platforms, 'go test' compiles the test executable with fuzzing
229 // coverage instrumentation. The fuzzing engine uses that instrumentation to
230 // find and cache inputs that expand coverage, increasing the likelihood of
231 // finding bugs. If the fuzz target fails for a given input, the fuzzing engine
232 // writes the inputs that caused the failure to a file in the directory
233 // testdata/fuzz/<Name> within the package directory. This file later serves as
234 // a seed input. If the file can't be written at that location (for example,
235 // because the directory is read-only), the fuzzing engine writes the file to
236 // the fuzz cache directory within the build cache instead.
238 // When fuzzing is disabled, the fuzz target is called with the seed inputs
239 // registered with F.Add and seed inputs from testdata/fuzz/<Name>. In this
240 // mode, the fuzz test acts much like a regular test, with subtests started
241 // with F.Fuzz instead of T.Run.
243 // See https://go.dev/doc/fuzz for documentation about fuzzing.
247 // Tests or benchmarks may be skipped at run time with a call to
248 // the Skip method of *T or *B:
250 // func TestTimeConsuming(t *testing.T) {
251 // if testing.Short() {
252 // t.Skip("skipping test in short mode.")
257 // The Skip method of *T can be used in a fuzz target if the input is invalid,
258 // but should not be considered a failing input. For example:
260 // func FuzzJSONMarshaling(f *testing.F) {
261 // f.Fuzz(func(t *testing.T, b []byte) {
263 // if err := json.Unmarshal(b, &v); err != nil {
266 // if _, err := json.Marshal(v); err != nil {
267 // t.Errorf("Marshal: %v", err)
272 // # Subtests and Sub-benchmarks
274 // The Run methods of T and B allow defining subtests and sub-benchmarks,
275 // without having to define separate functions for each. This enables uses
276 // like table-driven benchmarks and creating hierarchical tests.
277 // It also provides a way to share common setup and tear-down code:
279 // func TestFoo(t *testing.T) {
281 // t.Run("A=1", func(t *testing.T) { ... })
282 // t.Run("A=2", func(t *testing.T) { ... })
283 // t.Run("B=1", func(t *testing.T) { ... })
284 // // <tear-down code>
287 // Each subtest and sub-benchmark has a unique name: the combination of the name
288 // of the top-level test and the sequence of names passed to Run, separated by
289 // slashes, with an optional trailing sequence number for disambiguation.
291 // The argument to the -run, -bench, and -fuzz command-line flags is an unanchored regular
292 // expression that matches the test's name. For tests with multiple slash-separated
293 // elements, such as subtests, the argument is itself slash-separated, with
294 // expressions matching each name element in turn. Because it is unanchored, an
295 // empty expression matches any string.
296 // For example, using "matching" to mean "whose name contains":
298 // go test -run '' # Run all tests.
299 // go test -run Foo # Run top-level tests matching "Foo", such as "TestFooBar".
300 // go test -run Foo/A= # For top-level tests matching "Foo", run subtests matching "A=".
301 // go test -run /A=1 # For all top-level tests, run subtests matching "A=1".
302 // go test -fuzz FuzzFoo # Fuzz the target matching "FuzzFoo"
304 // The -run argument can also be used to run a specific value in the seed
305 // corpus, for debugging. For example:
307 // go test -run=FuzzFoo/9ddb952d9814
309 // The -fuzz and -run flags can both be set, in order to fuzz a target but
310 // skip the execution of all other tests.
312 // Subtests can also be used to control parallelism. A parent test will only
313 // complete once all of its subtests complete. In this example, all tests are
314 // run in parallel with each other, and only with each other, regardless of
315 // other top-level tests that may be defined:
317 // func TestGroupedParallel(t *testing.T) {
318 // for _, tc := range tests {
319 // tc := tc // capture range variable
320 // t.Run(tc.Name, func(t *testing.T) {
327 // Run does not return until parallel subtests have completed, providing a way
328 // to clean up after a group of parallel tests:
330 // func TestTeardownParallel(t *testing.T) {
331 // // This Run will not return until the parallel tests finish.
332 // t.Run("group", func(t *testing.T) {
333 // t.Run("Test1", parallelTest1)
334 // t.Run("Test2", parallelTest2)
335 // t.Run("Test3", parallelTest3)
337 // // <tear-down code>
342 // It is sometimes necessary for a test or benchmark program to do extra setup or teardown
343 // before or after it executes. It is also sometimes necessary to control
344 // which code runs on the main thread. To support these and other cases,
345 // if a test file contains a function:
347 // func TestMain(m *testing.M)
349 // then the generated test will call TestMain(m) instead of running the tests or benchmarks
350 // directly. TestMain runs in the main goroutine and can do whatever setup
351 // and teardown is necessary around a call to m.Run. m.Run will return an exit
352 // code that may be passed to os.Exit. If TestMain returns, the test wrapper
353 // will pass the result of m.Run to os.Exit itself.
355 // When TestMain is called, flag.Parse has not been run. If TestMain depends on
356 // command-line flags, including those of the testing package, it should call
357 // flag.Parse explicitly. Command line flags are always parsed by the time test
358 // or benchmark functions run.
360 // A simple implementation of TestMain is:
362 // func TestMain(m *testing.M) {
363 // // call flag.Parse() here if TestMain uses flags
367 // TestMain is a low-level primitive and should not be necessary for casual
368 // testing needs, where ordinary test functions suffice.
376 "internal/goexperiment"
397 // Init registers testing flags. These flags are automatically registered by
398 // the "go test" command before running test functions, so Init is only needed
399 // when calling functions such as Benchmark without using "go test".
401 // Init is not safe to call concurrently. It has no effect if it was already called.
407 // The short flag requests that tests run more quickly, but its functionality
408 // is provided by test writers themselves. The testing package is just its
409 // home. The all.bash installation script sets it to make installation more
410 // efficient, but by default the flag is off so a plain "go test" will do a
411 // full test of the package.
412 short = flag.Bool("test.short", false, "run smaller test suite to save time")
414 // The failfast flag requests that test execution stop after the first test failure.
415 failFast = flag.Bool("test.failfast", false, "do not start new tests after the first test failure")
417 // The directory in which to create profile files and the like. When run from
418 // "go test", the binary always runs in the source directory for the package;
419 // this flag lets "go test" tell the binary to write the files in the directory where
420 // the "go test" command is run.
421 outputDir = flag.String("test.outputdir", "", "write profiles to `dir`")
422 // Report as tests are run; default is silent for success.
423 flag.Var(&chatty, "test.v", "verbose: print additional output")
424 count = flag.Uint("test.count", 1, "run tests and benchmarks `n` times")
425 coverProfile = flag.String("test.coverprofile", "", "write a coverage profile to `file`")
426 gocoverdir = flag.String("test.gocoverdir", "", "write coverage intermediate files to this directory")
427 matchList = flag.String("test.list", "", "list tests, examples, and benchmarks matching `regexp` then exit")
428 match = flag.String("test.run", "", "run only tests and examples matching `regexp`")
429 skip = flag.String("test.skip", "", "do not list or run tests matching `regexp`")
430 memProfile = flag.String("test.memprofile", "", "write an allocation profile to `file`")
431 memProfileRate = flag.Int("test.memprofilerate", 0, "set memory allocation profiling `rate` (see runtime.MemProfileRate)")
432 cpuProfile = flag.String("test.cpuprofile", "", "write a cpu profile to `file`")
433 blockProfile = flag.String("test.blockprofile", "", "write a goroutine blocking profile to `file`")
434 blockProfileRate = flag.Int("test.blockprofilerate", 1, "set blocking profile `rate` (see runtime.SetBlockProfileRate)")
435 mutexProfile = flag.String("test.mutexprofile", "", "write a mutex contention profile to the named file after execution")
436 mutexProfileFraction = flag.Int("test.mutexprofilefraction", 1, "if >= 0, calls runtime.SetMutexProfileFraction()")
437 panicOnExit0 = flag.Bool("test.paniconexit0", false, "panic on call to os.Exit(0)")
438 traceFile = flag.String("test.trace", "", "write an execution trace to `file`")
439 timeout = flag.Duration("test.timeout", 0, "panic test binary after duration `d` (default 0, timeout disabled)")
440 cpuListStr = flag.String("test.cpu", "", "comma-separated `list` of cpu counts to run each test with")
441 parallel = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "run at most `n` tests in parallel")
442 testlog = flag.String("test.testlogfile", "", "write test action log to `file` (for use only by cmd/go)")
443 shuffle = flag.String("test.shuffle", "off", "randomize the execution order of tests and benchmarks")
444 fullPath = flag.Bool("test.fullpath", false, "show full file names in error messages")
451 // Flags, registered during Init.
466 blockProfileRate *int
468 mutexProfileFraction *int
471 timeout *time.Duration
478 haveExamples bool // are there examples?
483 numFailed atomic.Uint32 // number of test failures
485 running sync.Map // map[string]time.Time of running, unpaused tests
488 type chattyFlag struct {
489 on bool // -v is set in some form
490 json bool // -v=test2json is set, to make output better for test2json
493 func (*chattyFlag) IsBoolFlag() bool { return true }
495 func (f *chattyFlag) Set(arg string) error {
498 return fmt.Errorf("invalid flag -test.v=%s", arg)
499 case "true", "test2json":
501 f.json = arg == "test2json"
509 func (f *chattyFlag) String() string {
519 func (f *chattyFlag) Get() any {
526 const marker = byte(0x16) // ^V for framing
528 func (f *chattyFlag) prefix() string {
530 return string(marker)
535 type chattyPrinter struct {
537 lastNameMu sync.Mutex // guards lastName
538 lastName string // last printed test name in chatty mode
539 json bool // -v=json output mode
542 func newChattyPrinter(w io.Writer) *chattyPrinter {
543 return &chattyPrinter{w: w, json: chatty.json}
546 // prefix is like chatty.prefix but using p.json instead of chatty.json.
547 // Using p.json allows tests to check the json behavior without modifying
548 // the global variable. For convenience, we allow p == nil and treat
549 // that as not in json mode (because it's not chatty at all).
550 func (p *chattyPrinter) prefix() string {
551 if p != nil && p.json {
552 return string(marker)
557 // Updatef prints a message about the status of the named test to w.
559 // The formatted message must include the test name itself.
560 func (p *chattyPrinter) Updatef(testName, format string, args ...any) {
562 defer p.lastNameMu.Unlock()
564 // Since the message already implies an association with a specific new test,
565 // we don't need to check what the old test name was or log an extra NAME line
566 // for it. (We're updating it anyway, and the current message already includes
568 p.lastName = testName
569 fmt.Fprintf(p.w, p.prefix()+format, args...)
572 // Printf prints a message, generated by the named test, that does not
573 // necessarily mention that tests's name itself.
574 func (p *chattyPrinter) Printf(testName, format string, args ...any) {
576 defer p.lastNameMu.Unlock()
578 if p.lastName == "" {
579 p.lastName = testName
580 } else if p.lastName != testName {
581 fmt.Fprintf(p.w, "%s=== NAME %s\n", p.prefix(), testName)
582 p.lastName = testName
585 fmt.Fprintf(p.w, format, args...)
588 // The maximum number of stack frames to go through when skipping helper functions for
589 // the purpose of decorating log messages.
590 const maxStackLen = 50
592 // common holds the elements common between T and B and
593 // captures common methods such as Errorf.
595 mu sync.RWMutex // guards this group of fields
596 output []byte // Output generated by test or benchmark.
597 w io.Writer // For flushToParent.
598 ran bool // Test or benchmark (or one of its subtests) was executed.
599 failed bool // Test or benchmark has failed.
600 skipped bool // Test or benchmark has been skipped.
601 done bool // Test is finished and all subtests have completed.
602 helperPCs map[uintptr]struct{} // functions to be skipped when writing file/line info
603 helperNames map[string]struct{} // helperPCs converted to function names
604 cleanups []func() // optional functions to be called at the end of the test
605 cleanupName string // Name of the cleanup function.
606 cleanupPc []uintptr // The stack trace at the point where Cleanup was called.
607 finished bool // Test function has completed.
608 inFuzzFn bool // Whether the fuzz target, if this is one, is running.
610 chatty *chattyPrinter // A copy of chattyPrinter, if the chatty flag is set.
611 bench bool // Whether the current test is a benchmark.
612 hasSub atomic.Bool // whether there are sub-benchmarks.
613 cleanupStarted atomic.Bool // Registered cleanup callbacks have started to execute
614 runner string // Function name of tRunner running the test.
615 isParallel bool // Whether the test is parallel.
618 level int // Nesting depth of test or benchmark.
619 creator []uintptr // If level > 0, the stack trace at the point where the parent called t.Run.
620 name string // Name of test or benchmark.
621 start time.Time // Time test or benchmark started
622 duration time.Duration
623 barrier chan bool // To signal parallel subtests they may start. Nil when T.Parallel is not present (B) or not usable (when fuzzing).
624 signal chan bool // To signal a test is done.
625 sub []*T // Queue of subtests to be run in parallel.
627 lastRaceErrors atomic.Int64 // Max value of race.Errors seen during the test or its subtests.
628 raceErrorLogged atomic.Bool
636 // Short reports whether the -test.short flag is set.
639 panic("testing: Short called before Init")
641 // Catch code that calls this from TestMain without first calling flag.Parse.
643 panic("testing: Short called before Parse")
649 // testBinary is set by cmd/go to "1" if this is a binary built by "go test".
650 // The value is set to "1" by a -X option to cmd/link. We assume that
651 // because this is possible, the compiler will not optimize testBinary
652 // into a constant on the basis that it is an unexported package-scope
653 // variable that is never changed. If the compiler ever starts implementing
654 // such an optimization, we will need some technique to mark this variable
655 // as "changed by a cmd/link -X option".
658 // Testing reports whether the current code is being run in a test.
659 // This will report true in programs created by "go test",
660 // false in programs created by "go build".
661 func Testing() bool {
662 return testBinary == "1"
665 // CoverMode reports what the test coverage mode is set to. The
666 // values are "set", "count", or "atomic". The return value will be
667 // empty if test coverage is not enabled.
668 func CoverMode() string {
669 if goexperiment.CoverageRedesign {
675 // Verbose reports whether the -test.v flag is set.
676 func Verbose() bool {
679 panic("testing: Verbose called before Parse")
684 func (c *common) checkFuzzFn(name string) {
686 panic(fmt.Sprintf("testing: f.%s was called inside the fuzz target, use t.%s instead", name, name))
690 // frameSkip searches, starting after skip frames, for the first caller frame
691 // in a function not marked as a helper and returns that frame.
692 // The search stops if it finds a tRunner function that
693 // was the entry point into the test and the test is not a subtest.
694 // This function must be called with c.mu held.
695 func (c *common) frameSkip(skip int) runtime.Frame {
696 // If the search continues into the parent test, we'll have to hold
697 // its mu temporarily. If we then return, we need to unlock it.
698 shouldUnlock := false
704 var pc [maxStackLen]uintptr
705 // Skip two extra frames to account for this function
706 // and runtime.Callers itself.
707 n := runtime.Callers(skip+2, pc[:])
709 panic("testing: zero callers found")
711 frames := runtime.CallersFrames(pc[:n])
712 var firstFrame, prevFrame, frame runtime.Frame
713 for more := true; more; prevFrame = frame {
714 frame, more = frames.Next()
715 if frame.Function == "runtime.gopanic" {
718 if frame.Function == c.cleanupName {
719 frames = runtime.CallersFrames(c.cleanupPc)
722 if firstFrame.PC == 0 {
725 if frame.Function == c.runner {
726 // We've gone up all the way to the tRunner calling
727 // the test function (so the user must have
728 // called tb.Helper from inside that test function).
729 // If this is a top-level test, only skip up to the test function itself.
730 // If we're in a subtest, continue searching in the parent test,
731 // starting from the point of the call to Run which created this subtest.
733 frames = runtime.CallersFrames(c.creator)
735 // We're no longer looking at the current c after this point,
736 // so we should unlock its mu, unless it's the original receiver,
737 // in which case our caller doesn't expect us to do that.
742 // Remember to unlock c.mu when we no longer need it, either
743 // because we went up another nesting level, or because we
751 // If more helper PCs have been added since we last did the conversion
752 if c.helperNames == nil {
753 c.helperNames = make(map[string]struct{})
754 for pc := range c.helperPCs {
755 c.helperNames[pcToName(pc)] = struct{}{}
758 if _, ok := c.helperNames[frame.Function]; !ok {
759 // Found a frame that wasn't inside a helper function.
766 // decorate prefixes the string with the file and line of the call site
767 // and inserts the final newline if needed and indentation spaces for formatting.
768 // This function must be called with c.mu held.
769 func (c *common) decorate(s string, skip int) string {
770 frame := c.frameSkip(skip)
775 // If relative path, truncate file name at last file name separator.
776 } else if index := strings.LastIndexAny(file, `/\`); index >= 0 {
777 file = file[index+1:]
785 buf := new(strings.Builder)
786 // Every line is indented at least 4 spaces.
788 fmt.Fprintf(buf, "%s:%d: ", file, line)
789 lines := strings.Split(s, "\n")
790 if l := len(lines); l > 1 && lines[l-1] == "" {
793 for i, line := range lines {
795 // Second and subsequent lines are indented an additional 4 spaces.
796 buf.WriteString("\n ")
798 buf.WriteString(line)
804 // flushToParent writes c.output to the parent after first writing the header
805 // with the given format and arguments.
806 func (c *common) flushToParent(testName, format string, args ...any) {
814 if len(c.output) > 0 {
815 // Add the current c.output to the print,
816 // and then arrange for the print to replace c.output.
817 // (This displays the logged output after the --- FAIL line.)
819 args = append(args[:len(args):len(args)], c.output)
820 c.output = c.output[:0]
823 if c.chatty != nil && (p.w == c.chatty.w || c.chatty.json) {
824 // We're flushing to the actual output, so track that this output is
825 // associated with a specific test (and, specifically, that the next output
826 // is *not* associated with that test).
828 // Moreover, if c.output is non-empty it is important that this write be
829 // atomic with respect to the output of other tests, so that we don't end up
830 // with confusing '=== NAME' lines in the middle of our '--- PASS' block.
831 // Neither humans nor cmd/test2json can parse those easily.
832 // (See https://go.dev/issue/40771.)
834 // If test2json is used, we never flush to parent tests,
835 // so that the json stream shows subtests as they finish.
836 // (See https://go.dev/issue/29811.)
837 c.chatty.Updatef(testName, format, args...)
839 // We're flushing to the output buffer of the parent test, which will
840 // itself follow a test-name header when it is finally flushed to stdout.
841 fmt.Fprintf(p.w, c.chatty.prefix()+format, args...)
845 type indenter struct {
849 func (w indenter) Write(b []byte) (n int, err error) {
852 end := bytes.IndexByte(b, '\n')
858 // An indent of 4 spaces will neatly align the dashes with the status
859 // indicator of the parent.
861 if line[0] == marker {
862 w.c.output = append(w.c.output, marker)
866 w.c.output = append(w.c.output, indent...)
867 w.c.output = append(w.c.output, line...)
873 // fmtDuration returns a string representing d in the form "87.00s".
874 func fmtDuration(d time.Duration) string {
875 return fmt.Sprintf("%.2fs", d.Seconds())
878 // TB is the interface common to T, B, and F.
882 Errorf(format string, args ...any)
887 Fatalf(format string, args ...any)
890 Logf(format string, args ...any)
892 Setenv(key, value string)
895 Skipf(format string, args ...any)
899 // A private method to prevent users implementing the
900 // interface and so future additions to it will not
901 // violate Go 1 compatibility.
908 // T is a type passed to Test functions to manage test state and support formatted test logs.
910 // A test ends when its Test function returns or calls any of the methods
911 // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as
912 // the Parallel method, must be called only from the goroutine running the
915 // The other reporting methods, such as the variations of Log and Error,
916 // may be called simultaneously from multiple goroutines.
920 context *testContext // For running tests and subtests.
923 func (c *common) private() {}
925 // Name returns the name of the running (sub-) test or benchmark.
927 // The name will include the name of the test along with the names of
928 // any nested sub-tests. If two sibling sub-tests have the same name,
929 // Name will append a suffix to guarantee the returned name is unique.
930 func (c *common) Name() string {
934 func (c *common) setRan() {
943 // Fail marks the function as having failed but continues execution.
944 func (c *common) Fail() {
950 // c.done needs to be locked to synchronize checks to c.done in parent tests.
952 panic("Fail in goroutine after " + c.name + " has completed")
957 // Failed reports whether the function has failed.
958 func (c *common) Failed() bool {
962 if !c.done && int64(race.Errors()) > c.lastRaceErrors.Load() {
971 // FailNow marks the function as having failed and stops its execution
972 // by calling runtime.Goexit (which then runs all deferred calls in the
973 // current goroutine).
974 // Execution will continue at the next test or benchmark.
975 // FailNow must be called from the goroutine running the
976 // test or benchmark function, not from other goroutines
977 // created during the test. Calling FailNow does not stop
978 // those other goroutines.
979 func (c *common) FailNow() {
980 c.checkFuzzFn("FailNow")
983 // Calling runtime.Goexit will exit the goroutine, which
984 // will run the deferred functions in this goroutine,
985 // which will eventually run the deferred lines in tRunner,
986 // which will signal to the test loop that this test is done.
988 // A previous version of this code said:
991 // c.signal <- c.self
994 // This previous version duplicated code (those lines are in
995 // tRunner no matter what), but worse the goroutine teardown
996 // implicit in runtime.Goexit was not guaranteed to complete
997 // before the test exited. If a test deferred an important cleanup
998 // function (like removing temporary files), there was no guarantee
999 // it would run on a test failure. Because we send on c.signal during
1000 // a top-of-stack deferred function now, we know that the send
1001 // only happens after any other stacked defers have completed.
1008 // log generates the output. It's always at the same stack depth.
1009 func (c *common) log(s string) {
1010 c.logDepth(s, 3) // logDepth + log + public function
1013 // logDepth generates the output at an arbitrary stack depth.
1014 func (c *common) logDepth(s string, depth int) {
1018 // This test has already finished. Try and log this message
1019 // with our parent. If we don't have a parent, panic.
1020 for parent := c.parent; parent != nil; parent = parent.parent {
1022 defer parent.mu.Unlock()
1024 parent.output = append(parent.output, parent.decorate(s, depth+1)...)
1028 panic("Log in goroutine after " + c.name + " has completed: " + s)
1030 if c.chatty != nil {
1032 // Benchmarks don't print === CONT, so we should skip the test
1033 // printer and just print straight to stdout.
1034 fmt.Print(c.decorate(s, depth+1))
1036 c.chatty.Printf(c.name, "%s", c.decorate(s, depth+1))
1041 c.output = append(c.output, c.decorate(s, depth+1)...)
1045 // Log formats its arguments using default formatting, analogous to Println,
1046 // and records the text in the error log. For tests, the text will be printed only if
1047 // the test fails or the -test.v flag is set. For benchmarks, the text is always
1048 // printed to avoid having performance depend on the value of the -test.v flag.
1049 func (c *common) Log(args ...any) {
1050 c.checkFuzzFn("Log")
1051 c.log(fmt.Sprintln(args...))
1054 // Logf formats its arguments according to the format, analogous to Printf, and
1055 // records the text in the error log. A final newline is added if not provided. For
1056 // tests, the text will be printed only if the test fails or the -test.v flag is
1057 // set. For benchmarks, the text is always printed to avoid having performance
1058 // depend on the value of the -test.v flag.
1059 func (c *common) Logf(format string, args ...any) {
1060 c.checkFuzzFn("Logf")
1061 c.log(fmt.Sprintf(format, args...))
1064 // Error is equivalent to Log followed by Fail.
1065 func (c *common) Error(args ...any) {
1066 c.checkFuzzFn("Error")
1067 c.log(fmt.Sprintln(args...))
1071 // Errorf is equivalent to Logf followed by Fail.
1072 func (c *common) Errorf(format string, args ...any) {
1073 c.checkFuzzFn("Errorf")
1074 c.log(fmt.Sprintf(format, args...))
1078 // Fatal is equivalent to Log followed by FailNow.
1079 func (c *common) Fatal(args ...any) {
1080 c.checkFuzzFn("Fatal")
1081 c.log(fmt.Sprintln(args...))
1085 // Fatalf is equivalent to Logf followed by FailNow.
1086 func (c *common) Fatalf(format string, args ...any) {
1087 c.checkFuzzFn("Fatalf")
1088 c.log(fmt.Sprintf(format, args...))
1092 // Skip is equivalent to Log followed by SkipNow.
1093 func (c *common) Skip(args ...any) {
1094 c.checkFuzzFn("Skip")
1095 c.log(fmt.Sprintln(args...))
1099 // Skipf is equivalent to Logf followed by SkipNow.
1100 func (c *common) Skipf(format string, args ...any) {
1101 c.checkFuzzFn("Skipf")
1102 c.log(fmt.Sprintf(format, args...))
1106 // SkipNow marks the test as having been skipped and stops its execution
1107 // by calling [runtime.Goexit].
1108 // If a test fails (see Error, Errorf, Fail) and is then skipped,
1109 // it is still considered to have failed.
1110 // Execution will continue at the next test or benchmark. See also FailNow.
1111 // SkipNow must be called from the goroutine running the test, not from
1112 // other goroutines created during the test. Calling SkipNow does not stop
1113 // those other goroutines.
1114 func (c *common) SkipNow() {
1115 c.checkFuzzFn("SkipNow")
1123 // Skipped reports whether the test was skipped.
1124 func (c *common) Skipped() bool {
1126 defer c.mu.RUnlock()
1130 // Helper marks the calling function as a test helper function.
1131 // When printing file and line information, that function will be skipped.
1132 // Helper may be called simultaneously from multiple goroutines.
1133 func (c *common) Helper() {
1136 if c.helperPCs == nil {
1137 c.helperPCs = make(map[uintptr]struct{})
1139 // repeating code from callerName here to save walking a stack frame
1141 n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper
1143 panic("testing: zero callers found")
1145 if _, found := c.helperPCs[pc[0]]; !found {
1146 c.helperPCs[pc[0]] = struct{}{}
1147 c.helperNames = nil // map will be recreated next time it is needed
1151 // Cleanup registers a function to be called when the test (or subtest) and all its
1152 // subtests complete. Cleanup functions will be called in last added,
1153 // first called order.
1154 func (c *common) Cleanup(f func()) {
1155 c.checkFuzzFn("Cleanup")
1156 var pc [maxStackLen]uintptr
1157 // Skip two extra frames to account for this function and runtime.Callers itself.
1158 n := runtime.Callers(2, pc[:])
1169 name := callerName(0)
1171 c.cleanupName = name
1172 c.cleanupPc = cleanupPc
1180 c.cleanups = append(c.cleanups, fn)
1183 // TempDir returns a temporary directory for the test to use.
1184 // The directory is automatically removed when the test and
1185 // all its subtests complete.
1186 // Each subsequent call to t.TempDir returns a unique directory;
1187 // if the directory creation fails, TempDir terminates the test by calling Fatal.
1188 func (c *common) TempDir() string {
1189 c.checkFuzzFn("TempDir")
1190 // Use a single parent directory for all the temporary directories
1191 // created by a test, each numbered sequentially.
1193 var nonExistent bool
1194 if c.tempDir == "" { // Usually the case with js/wasm
1197 _, err := os.Stat(c.tempDir)
1198 nonExistent = os.IsNotExist(err)
1199 if err != nil && !nonExistent {
1200 c.Fatalf("TempDir: %v", err)
1207 // Drop unusual characters (such as path separators or
1208 // characters interacting with globs) from the directory name to
1209 // avoid surprising os.MkdirTemp behavior.
1210 mapper := func(r rune) rune {
1211 if r < utf8.RuneSelf {
1212 const allowed = "!#$%&()+,-.=@^_{}~ "
1213 if '0' <= r && r <= '9' ||
1214 'a' <= r && r <= 'z' ||
1215 'A' <= r && r <= 'Z' {
1218 if strings.ContainsRune(allowed, r) {
1221 } else if unicode.IsLetter(r) || unicode.IsNumber(r) {
1226 pattern := strings.Map(mapper, c.Name())
1227 c.tempDir, c.tempDirErr = os.MkdirTemp("", pattern)
1228 if c.tempDirErr == nil {
1230 if err := removeAll(c.tempDir); err != nil {
1231 c.Errorf("TempDir RemoveAll cleanup: %v", err)
1237 if c.tempDirErr == nil {
1241 c.tempDirMu.Unlock()
1243 if c.tempDirErr != nil {
1244 c.Fatalf("TempDir: %v", c.tempDirErr)
1247 dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)
1248 if err := os.Mkdir(dir, 0777); err != nil {
1249 c.Fatalf("TempDir: %v", err)
1254 // removeAll is like os.RemoveAll, but retries Windows "Access is denied."
1255 // errors up to an arbitrary timeout.
1257 // Those errors have been known to occur spuriously on at least the
1258 // windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur
1259 // legitimately if the test leaves behind a temp file that either is still open
1260 // or the test otherwise lacks permission to delete. In the case of legitimate
1261 // failures, a failing test may take a bit longer to fail, but once the test is
1262 // fixed the extra latency will go away.
1263 func removeAll(path string) error {
1264 const arbitraryTimeout = 2 * time.Second
1267 nextSleep = 1 * time.Millisecond
1270 err := os.RemoveAll(path)
1271 if !isWindowsRetryable(err) {
1276 } else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {
1279 time.Sleep(nextSleep)
1280 nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))
1284 // Setenv calls os.Setenv(key, value) and uses Cleanup to
1285 // restore the environment variable to its original value
1288 // Because Setenv affects the whole process, it cannot be used
1289 // in parallel tests or tests with parallel ancestors.
1290 func (c *common) Setenv(key, value string) {
1291 c.checkFuzzFn("Setenv")
1292 prevValue, ok := os.LookupEnv(key)
1294 if err := os.Setenv(key, value); err != nil {
1295 c.Fatalf("cannot set environment variable: %v", err)
1300 os.Setenv(key, prevValue)
1309 // panicHanding controls the panic handling used by runCleanup.
1310 type panicHandling int
1313 normalPanic panicHandling = iota
1314 recoverAndReturnPanic
1317 // runCleanup is called at the end of the test.
1318 // If ph is recoverAndReturnPanic, it will catch panics, and return the
1319 // recovered value if any.
1320 func (c *common) runCleanup(ph panicHandling) (panicVal any) {
1321 c.cleanupStarted.Store(true)
1322 defer c.cleanupStarted.Store(false)
1324 if ph == recoverAndReturnPanic {
1326 panicVal = recover()
1330 // Make sure that if a cleanup function panics,
1331 // we still run the remaining cleanup functions.
1334 recur := len(c.cleanups) > 0
1337 c.runCleanup(normalPanic)
1344 if len(c.cleanups) > 0 {
1345 last := len(c.cleanups) - 1
1346 cleanup = c.cleanups[last]
1347 c.cleanups = c.cleanups[:last]
1357 // resetRaces updates c.parent's count of data race errors (or the global count,
1358 // if c has no parent), and updates c.lastRaceErrors to match.
1360 // Any races that occurred prior to this call to resetRaces will
1361 // not be attributed to c.
1362 func (c *common) resetRaces() {
1363 if c.parent == nil {
1364 c.lastRaceErrors.Store(int64(race.Errors()))
1366 c.lastRaceErrors.Store(c.parent.checkRaces())
1370 // checkRaces checks whether the global count of data race errors has increased
1371 // since c's count was last reset.
1373 // If so, it marks c as having failed due to those races (logging an error for
1374 // the first such race), and updates the race counts for the parents of c so
1375 // that if they are currently suspended (such as in a call to T.Run) they will
1376 // not log separate errors for the race(s).
1378 // Note that multiple tests may be marked as failed due to the same race if they
1379 // are executing in parallel.
1380 func (c *common) checkRaces() (raceErrors int64) {
1381 raceErrors = int64(race.Errors())
1383 last := c.lastRaceErrors.Load()
1384 if raceErrors <= last {
1385 // All races have already been reported.
1388 if c.lastRaceErrors.CompareAndSwap(last, raceErrors) {
1393 if c.raceErrorLogged.CompareAndSwap(false, true) {
1394 // This is the first race we've encountered for this test.
1395 // Mark the test as failed, and log the reason why only once.
1396 // (Note that the race detector itself will still write a goroutine
1397 // dump for any further races it detects.)
1398 c.Errorf("race detected during execution of test")
1401 // Update the parent(s) of this test so that they don't re-report the race.
1405 last := parent.lastRaceErrors.Load()
1406 if raceErrors <= last {
1407 // This race was already reported by another (likely parallel) subtest.
1410 if parent.lastRaceErrors.CompareAndSwap(last, raceErrors) {
1414 parent = parent.parent
1420 // callerName gives the function name (qualified with a package path)
1421 // for the caller after skip frames (where 0 means the current function).
1422 func callerName(skip int) string {
1424 n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName
1426 panic("testing: zero callers found")
1428 return pcToName(pc[0])
1431 func pcToName(pc uintptr) string {
1432 pcs := []uintptr{pc}
1433 frames := runtime.CallersFrames(pcs)
1434 frame, _ := frames.Next()
1435 return frame.Function
1438 // Parallel signals that this test is to be run in parallel with (and only with)
1439 // other parallel tests. When a test is run multiple times due to use of
1440 // -test.count or -test.cpu, multiple instances of a single test never run in
1441 // parallel with each other.
1442 func (t *T) Parallel() {
1444 panic("testing: t.Parallel called multiple times")
1447 panic("testing: t.Parallel called after t.Setenv; cannot set environment variables in parallel tests")
1450 if t.parent.barrier == nil {
1451 // T.Parallel has no effect when fuzzing.
1452 // Multiple processes may run in parallel, but only one input can run at a
1453 // time per process so we can attribute crashes to specific inputs.
1457 // We don't want to include the time we spend waiting for serial tests
1458 // in the test duration. Record the elapsed time thus far and reset the
1459 // timer afterwards.
1460 t.duration += time.Since(t.start)
1462 // Add to the list of tests to be released by the parent.
1463 t.parent.sub = append(t.parent.sub, t)
1465 // Report any races during execution of this test up to this point.
1467 // We will assume that any races that occur between here and the point where
1468 // we unblock are not caused by this subtest. That assumption usually holds,
1469 // although it can be wrong if the test spawns a goroutine that races in the
1470 // background while the rest of the test is blocked on the call to Parallel.
1471 // If that happens, we will misattribute the background race to some other
1472 // test, or to no test at all — but that false-negative is so unlikely that it
1473 // is not worth adding race-report noise for the common case where the test is
1474 // completely suspended during the call to Parallel.
1477 if t.chatty != nil {
1478 t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)
1480 running.Delete(t.name)
1482 t.signal <- true // Release calling test.
1483 <-t.parent.barrier // Wait for the parent test to complete.
1484 t.context.waitParallel()
1486 if t.chatty != nil {
1487 t.chatty.Updatef(t.name, "=== CONT %s\n", t.name)
1489 running.Store(t.name, time.Now())
1490 t.start = time.Now()
1492 // Reset the local race counter to ignore any races that happened while this
1493 // goroutine was blocked, such as in the parent test or in other parallel
1496 // (Note that we don't call parent.checkRaces here:
1497 // if other parallel subtests have already introduced races, we want to
1498 // let them report those races instead of attributing them to the parent.)
1499 t.lastRaceErrors.Store(int64(race.Errors()))
1502 // Setenv calls os.Setenv(key, value) and uses Cleanup to
1503 // restore the environment variable to its original value
1506 // Because Setenv affects the whole process, it cannot be used
1507 // in parallel tests or tests with parallel ancestors.
1508 func (t *T) Setenv(key, value string) {
1509 // Non-parallel subtests that have parallel ancestors may still
1510 // run in parallel with other tests: they are only non-parallel
1511 // with respect to the other subtests of the same parent.
1512 // Since SetEnv affects the whole process, we need to disallow it
1513 // if the current test or any parent is parallel.
1515 for c := &t.common; c != nil; c = c.parent {
1522 panic("testing: t.Setenv called after t.Parallel; cannot set environment variables in parallel tests")
1527 t.common.Setenv(key, value)
1530 // InternalTest is an internal type but exported because it is cross-package;
1531 // it is part of the implementation of the "go test" command.
1532 type InternalTest struct {
1537 var errNilPanicOrGoexit = errors.New("test executed panic(nil) or runtime.Goexit")
1539 func tRunner(t *T, fn func(t *T)) {
1540 t.runner = callerName(0)
1542 // When this goroutine is done, either because fn(t)
1543 // returned normally or because a test failure triggered
1544 // a call to runtime.Goexit, record the duration and send
1545 // a signal saying that the test is done.
1549 // TODO(#61034): This is the wrong place for this check.
1554 // Check if the test panicked or Goexited inappropriately.
1556 // If this happens in a normal test, print output but continue panicking.
1557 // tRunner is called in its own goroutine, so this terminates the process.
1559 // If this happens while fuzzing, recover from the panic and treat it like a
1560 // normal failure. It's important that the process keeps running in order to
1561 // find short inputs that cause panics.
1566 finished := t.finished
1568 if !finished && err == nil {
1569 err = errNilPanicOrGoexit
1570 for p := t.parent; p != nil; p = p.parent {
1572 finished = p.finished
1576 t.Errorf("%v: subtest may have called FailNow on a parent test", err)
1585 if err != nil && t.context.isFuzzing {
1587 if err == errNilPanicOrGoexit {
1590 t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack()))
1597 // Use a deferred call to ensure that we report that the test is
1598 // complete even if a cleanup function calls t.FailNow. See issue 41355.
1601 // Only report that the test is complete if it doesn't panic,
1602 // as otherwise the test binary can exit before the panic is
1603 // reported to the user. See issue 41479.
1610 running.Delete(t.name)
1614 doPanic := func(err any) {
1616 if r := t.runCleanup(recoverAndReturnPanic); r != nil {
1617 t.Logf("cleanup panicked with %v", r)
1619 // Flush the output log up to the root before dying.
1620 for root := &t.common; root.parent != nil; root = root.parent {
1622 root.duration += time.Since(root.start)
1625 root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d))
1626 if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil {
1627 fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r)
1637 t.duration += time.Since(t.start)
1640 // Run parallel subtests.
1641 // Decrease the running count for this test.
1643 // Release the parallel subtests.
1645 // Wait for subtests to complete.
1646 for _, sub := range t.sub {
1649 cleanupStart := time.Now()
1650 err := t.runCleanup(recoverAndReturnPanic)
1651 t.duration += time.Since(cleanupStart)
1657 // Reacquire the count for sequential tests. See comment in Run.
1658 t.context.waitParallel()
1660 } else if t.isParallel {
1661 // Only release the count for this test if it was run as a parallel
1662 // test. See comment in Run method.
1665 t.report() // Report after all subtests have finished.
1667 // Do not lock t.done to allow race detector to detect race in case
1668 // the user does not appropriately synchronize a goroutine.
1670 if t.parent != nil && !t.hasSub.Load() {
1675 if len(t.sub) == 0 {
1676 t.runCleanup(normalPanic)
1680 t.start = time.Now()
1684 // code beyond here will not be executed when FailNow is invoked
1690 // Run runs f as a subtest of t called name. It runs f in a separate goroutine
1691 // and blocks until f returns or calls t.Parallel to become a parallel test.
1692 // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
1694 // Run may be called simultaneously from multiple goroutines, but all such calls
1695 // must return before the outer test function for t returns.
1696 func (t *T) Run(name string, f func(t *T)) bool {
1697 if t.cleanupStarted.Load() {
1698 panic("testing: t.Run called during t.Cleanup")
1701 t.hasSub.Store(true)
1702 testName, ok, _ := t.context.match.fullName(&t.common, name)
1703 if !ok || shouldFailFast() {
1706 // Record the stack trace at the point of this call so that if the subtest
1707 // function - which runs in a separate stack - is marked as a helper, we can
1708 // continue walking the stack into the parent test.
1709 var pc [maxStackLen]uintptr
1710 n := runtime.Callers(2, pc[:])
1713 barrier: make(chan bool),
1714 signal: make(chan bool, 1),
1723 t.w = indenter{&t.common}
1725 if t.chatty != nil {
1726 t.chatty.Updatef(t.name, "=== RUN %s\n", t.name)
1728 running.Store(t.name, time.Now())
1730 // Instead of reducing the running count of this test before calling the
1731 // tRunner and increasing it afterwards, we rely on tRunner keeping the
1732 // count correct. This ensures that a sequence of sequential tests runs
1733 // without being preempted, even when their parent is a parallel test. This
1734 // may especially reduce surprises if *parallel == 1.
1737 // At this point, it is likely that FailNow was called on one of the
1738 // parent tests by one of the subtests. Continue aborting up the chain.
1741 if t.chatty != nil && t.chatty.json {
1742 t.chatty.Updatef(t.parent.name, "=== NAME %s\n", t.parent.name)
1747 // Deadline reports the time at which the test binary will have
1748 // exceeded the timeout specified by the -timeout flag.
1750 // The ok result is false if the -timeout flag indicates “no timeout” (0).
1751 func (t *T) Deadline() (deadline time.Time, ok bool) {
1752 deadline = t.context.deadline
1753 return deadline, !deadline.IsZero()
1756 // testContext holds all fields that are common to all tests. This includes
1757 // synchronization primitives to run at most *parallel tests.
1758 type testContext struct {
1762 // isFuzzing is true in the context used when generating random inputs
1763 // for fuzz targets. isFuzzing is false when running normal tests and
1764 // when running fuzz tests as unit tests (without -fuzz or when -fuzz
1770 // Channel used to signal tests that are ready to be run in parallel.
1771 startParallel chan bool
1773 // running is the number of tests currently running in parallel.
1774 // This does not include tests that are waiting for subtests to complete.
1777 // numWaiting is the number tests waiting to be run in parallel.
1780 // maxParallel is a copy of the parallel flag.
1784 func newTestContext(maxParallel int, m *matcher) *testContext {
1785 return &testContext{
1787 startParallel: make(chan bool),
1788 maxParallel: maxParallel,
1789 running: 1, // Set the count to 1 for the main (sequential) test.
1793 func (c *testContext) waitParallel() {
1795 if c.running < c.maxParallel {
1805 func (c *testContext) release() {
1807 if c.numWaiting == 0 {
1814 c.startParallel <- true // Pick a waiting test to be run.
1817 // No one should be using func Main anymore.
1818 // See the doc comment on func Main and use MainStart instead.
1819 var errMain = errors.New("testing: unexpected use of func Main")
1821 type matchStringOnly func(pat, str string) (bool, error)
1823 func (f matchStringOnly) MatchString(pat, str string) (bool, error) { return f(pat, str) }
1824 func (f matchStringOnly) StartCPUProfile(w io.Writer) error { return errMain }
1825 func (f matchStringOnly) StopCPUProfile() {}
1826 func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain }
1827 func (f matchStringOnly) ImportPath() string { return "" }
1828 func (f matchStringOnly) StartTestLog(io.Writer) {}
1829 func (f matchStringOnly) StopTestLog() error { return errMain }
1830 func (f matchStringOnly) SetPanicOnExit0(bool) {}
1831 func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error {
1834 func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain }
1835 func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) {
1838 func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil }
1839 func (f matchStringOnly) ResetCoverage() {}
1840 func (f matchStringOnly) SnapshotCoverage() {}
1842 // Main is an internal function, part of the implementation of the "go test" command.
1843 // It was exported because it is cross-package and predates "internal" packages.
1844 // It is no longer used by "go test" but preserved, as much as possible, for other
1845 // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
1846 // new functionality is added to the testing package.
1847 // Systems simulating "go test" should be updated to use MainStart.
1848 func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {
1849 os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run())
1852 // M is a type passed to a TestMain function to run the actual tests.
1855 tests []InternalTest
1856 benchmarks []InternalBenchmark
1857 fuzzTargets []InternalFuzzTarget
1858 examples []InternalExample
1865 // value to pass to os.Exit, the outer test func main
1866 // harness calls os.Exit with this code. See #34129.
1870 // testDeps is an internal interface of functionality that is
1871 // passed into this package by a test's generated main package.
1872 // The canonical implementation of this interface is
1873 // testing/internal/testdeps's TestDeps.
1874 type testDeps interface {
1876 MatchString(pat, str string) (bool, error)
1877 SetPanicOnExit0(bool)
1878 StartCPUProfile(io.Writer) error
1880 StartTestLog(io.Writer)
1882 WriteProfileTo(string, io.Writer, int) error
1883 CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error
1884 RunFuzzWorker(func(corpusEntry) error) error
1885 ReadCorpus(string, []reflect.Type) ([]corpusEntry, error)
1886 CheckCorpus([]any, []reflect.Type) error
1891 // MainStart is meant for use by tests generated by 'go test'.
1892 // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
1893 // It may change signature from release to release.
1894 func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M {
1899 benchmarks: benchmarks,
1900 fuzzTargets: fuzzTargets,
1905 var testingTesting bool
1906 var realStderr *os.File
1908 // Run runs the tests. It returns an exit code to pass to os.Exit.
1909 func (m *M) Run() (code int) {
1914 // Count the number of calls to m.Run.
1915 // We only ever expected 1, but we didn't enforce that,
1916 // and now there are tests in the wild that call m.Run multiple times.
1917 // Sigh. go.dev/issue/23129.
1920 // TestMain may have already called flag.Parse.
1926 // With -v=json, stdout and stderr are pointing to the same pipe,
1927 // which is leading into test2json. In general, operating systems
1928 // do a good job of ensuring that writes to the same pipe through
1929 // different file descriptors are delivered whole, so that writing
1930 // AAA to stdout and BBB to stderr simultaneously produces
1931 // AAABBB or BBBAAA on the pipe, not something like AABBBA.
1932 // However, the exception to this is when the pipe fills: in that
1933 // case, Go's use of non-blocking I/O means that writing AAA
1934 // or BBB might be split across multiple system calls, making it
1935 // entirely possible to get output like AABBBA. The same problem
1936 // happens inside the operating system kernel if we switch to
1937 // blocking I/O on the pipe. This interleaved output can do things
1938 // like print unrelated messages in the middle of a TestFoo line,
1939 // which confuses test2json. Setting os.Stderr = os.Stdout will make
1940 // them share a single pfd, which will hold a lock for each program
1941 // write, preventing any interleaving.
1943 // It might be nice to set Stderr = Stdout always, or perhaps if
1944 // we can tell they are the same file, but for now -v=json is
1945 // a very clear signal. Making the two files the same may cause
1946 // surprises if programs close os.Stdout but expect to be able
1947 // to continue to write to os.Stderr, but it's hard to see why a
1948 // test would think it could take over global state that way.
1950 // This fix only helps programs where the output is coming directly
1951 // from Go code. It does not help programs in which a subprocess is
1952 // writing to stderr or stdout at the same time that a Go test is writing output.
1953 // It also does not help when the output is coming from the runtime,
1954 // such as when using the print/println functions, since that code writes
1955 // directly to fd 2 without any locking.
1956 // We keep realStderr around to prevent fd 2 from being closed.
1958 // See go.dev/issue/33419.
1959 realStderr = os.Stderr
1960 os.Stderr = os.Stdout
1964 fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer")
1969 if *matchFuzz != "" && *fuzzCacheDir == "" {
1970 fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set")
1976 if *matchList != "" {
1977 listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples)
1982 if *shuffle != "off" {
1985 if *shuffle == "on" {
1986 n = time.Now().UnixNano()
1988 n, err = strconv.ParseInt(*shuffle, 10, 64)
1990 fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err)
1995 fmt.Println("-test.shuffle", n)
1996 rng := rand.New(rand.NewSource(n))
1997 rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] })
1998 rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] })
2006 // Run tests, examples, and benchmarks unless this is a fuzz worker process.
2007 // Workers start after this is done by their parent process, and they should
2008 // not repeat this work.
2010 deadline := m.startAlarm()
2011 haveExamples = len(m.examples) > 0
2012 testRan, testOk := runTests(m.deps.MatchString, m.tests, deadline)
2013 fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline)
2014 exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples)
2016 if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" {
2017 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
2018 if testingTesting && *match != "^$" {
2019 // If this happens during testing of package testing it could be that
2020 // package testing's own logic for when to run a test is broken,
2021 // in which case every test will run nothing and succeed,
2022 // with no obvious way to detect this problem (since no tests are running).
2023 // So make 'no tests to run' a hard failure when testing package testing itself.
2024 fmt.Print(chatty.prefix(), "FAIL: package testing must run tests\n")
2028 anyFailed := !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks)
2029 if !anyFailed && race.Errors() > 0 {
2030 fmt.Print(chatty.prefix(), "testing: race detected outside of test execution\n")
2034 fmt.Print(chatty.prefix(), "FAIL\n")
2040 fuzzingOk := runFuzzing(m.deps, m.fuzzTargets)
2042 fmt.Print(chatty.prefix(), "FAIL\n")
2044 m.exitCode = fuzzWorkerExitCode
2053 fmt.Print(chatty.prefix(), "PASS\n")
2058 func (t *T) report() {
2059 if t.parent == nil {
2062 dstr := fmtDuration(t.duration)
2063 format := "--- %s: %s (%s)\n"
2065 t.flushToParent(t.name, format, "FAIL", t.name, dstr)
2066 } else if t.chatty != nil {
2068 t.flushToParent(t.name, format, "SKIP", t.name, dstr)
2070 t.flushToParent(t.name, format, "PASS", t.name, dstr)
2075 func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) {
2076 if _, err := matchString(*matchList, "non-empty"); err != nil {
2077 fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err)
2081 for _, test := range tests {
2082 if ok, _ := matchString(*matchList, test.Name); ok {
2083 fmt.Println(test.Name)
2086 for _, bench := range benchmarks {
2087 if ok, _ := matchString(*matchList, bench.Name); ok {
2088 fmt.Println(bench.Name)
2091 for _, fuzzTarget := range fuzzTargets {
2092 if ok, _ := matchString(*matchList, fuzzTarget.Name); ok {
2093 fmt.Println(fuzzTarget.Name)
2096 for _, example := range examples {
2097 if ok, _ := matchString(*matchList, example.Name); ok {
2098 fmt.Println(example.Name)
2103 // RunTests is an internal function but exported because it is cross-package;
2104 // it is part of the implementation of the "go test" command.
2105 func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {
2106 var deadline time.Time
2108 deadline = time.Now().Add(*timeout)
2110 ran, ok := runTests(matchString, tests, deadline)
2111 if !ran && !haveExamples {
2112 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
2117 func runTests(matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
2119 for _, procs := range cpuList {
2120 runtime.GOMAXPROCS(procs)
2121 for i := uint(0); i < *count; i++ {
2122 if shouldFailFast() {
2126 // There were no tests to run on the first
2127 // iteration. This won't change, so no reason
2131 ctx := newTestContext(*parallel, newMatcher(matchString, *match, "-test.run", *skip))
2132 ctx.deadline = deadline
2135 signal: make(chan bool, 1),
2136 barrier: make(chan bool),
2142 t.chatty = newChattyPrinter(t.w)
2144 tRunner(t, func(t *T) {
2145 for _, test := range tests {
2146 t.Run(test.Name, test.F)
2152 panic("internal error: tRunner exited without sending on t.signal")
2154 ok = ok && !t.Failed()
2161 // before runs before all testing.
2162 func (m *M) before() {
2163 if *memProfileRate > 0 {
2164 runtime.MemProfileRate = *memProfileRate
2166 if *cpuProfile != "" {
2167 f, err := os.Create(toOutputDir(*cpuProfile))
2169 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2172 if err := m.deps.StartCPUProfile(f); err != nil {
2173 fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err)
2177 // Could save f so after can call f.Close; not worth the effort.
2179 if *traceFile != "" {
2180 f, err := os.Create(toOutputDir(*traceFile))
2182 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2185 if err := trace.Start(f); err != nil {
2186 fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err)
2190 // Could save f so after can call f.Close; not worth the effort.
2192 if *blockProfile != "" && *blockProfileRate >= 0 {
2193 runtime.SetBlockProfileRate(*blockProfileRate)
2195 if *mutexProfile != "" && *mutexProfileFraction >= 0 {
2196 runtime.SetMutexProfileFraction(*mutexProfileFraction)
2198 if *coverProfile != "" && CoverMode() == "" {
2199 fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
2202 if *gocoverdir != "" && CoverMode() == "" {
2203 fmt.Fprintf(os.Stderr, "testing: cannot use -test.gocoverdir because test binary was not built with coverage enabled\n")
2207 // Note: Not using toOutputDir.
2208 // This file is for use by cmd/go, not users.
2212 f, err = os.Create(*testlog)
2214 f, err = os.OpenFile(*testlog, os.O_WRONLY, 0)
2216 f.Seek(0, io.SeekEnd)
2220 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2223 m.deps.StartTestLog(f)
2227 m.deps.SetPanicOnExit0(true)
2231 // after runs after all testing.
2232 func (m *M) after() {
2233 m.afterOnce.Do(func() {
2237 // Restore PanicOnExit0 after every run, because we set it to true before
2238 // every run. Otherwise, if m.Run is called multiple times the behavior of
2239 // os.Exit(0) will not be restored after the second run.
2241 m.deps.SetPanicOnExit0(false)
2245 func (m *M) writeProfiles() {
2247 if err := m.deps.StopTestLog(); err != nil {
2248 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
2251 if err := testlogFile.Close(); err != nil {
2252 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
2256 if *cpuProfile != "" {
2257 m.deps.StopCPUProfile() // flushes profile to disk
2259 if *traceFile != "" {
2260 trace.Stop() // flushes trace to disk
2262 if *memProfile != "" {
2263 f, err := os.Create(toOutputDir(*memProfile))
2265 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2268 runtime.GC() // materialize all statistics
2269 if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil {
2270 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err)
2275 if *blockProfile != "" && *blockProfileRate >= 0 {
2276 f, err := os.Create(toOutputDir(*blockProfile))
2278 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2281 if err = m.deps.WriteProfileTo("block", f, 0); err != nil {
2282 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err)
2287 if *mutexProfile != "" && *mutexProfileFraction >= 0 {
2288 f, err := os.Create(toOutputDir(*mutexProfile))
2290 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2293 if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil {
2294 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err)
2299 if CoverMode() != "" {
2304 // toOutputDir returns the file name relocated, if required, to outputDir.
2305 // Simple implementation to avoid pulling in path/filepath.
2306 func toOutputDir(path string) string {
2307 if *outputDir == "" || path == "" {
2310 // On Windows, it's clumsy, but we can be almost always correct
2311 // by just looking for a drive letter and a colon.
2312 // Absolute paths always have a drive letter (ignoring UNC).
2313 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
2314 // what to do, but even then path/filepath doesn't help.
2315 // TODO: Worth doing better? Probably not, because we're here only
2316 // under the management of go test.
2317 if runtime.GOOS == "windows" && len(path) >= 2 {
2318 letter, colon := path[0], path[1]
2319 if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' {
2320 // If path starts with a drive letter we're stuck with it regardless.
2324 if os.IsPathSeparator(path[0]) {
2327 return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path)
2330 // startAlarm starts an alarm if requested.
2331 func (m *M) startAlarm() time.Time {
2336 deadline := time.Now().Add(*timeout)
2337 m.timer = time.AfterFunc(*timeout, func() {
2339 debug.SetTraceback("all")
2342 if list := runningList(); len(list) > 0 {
2343 var b strings.Builder
2344 b.WriteString("\nrunning tests:")
2345 for _, name := range list {
2346 b.WriteString("\n\t")
2351 panic(fmt.Sprintf("test timed out after %v%s", *timeout, extra))
2356 // runningList returns the list of running tests.
2357 func runningList() []string {
2359 running.Range(func(k, v any) bool {
2360 list = append(list, fmt.Sprintf("%s (%v)", k.(string), time.Since(v.(time.Time)).Round(time.Second)))
2367 // stopAlarm turns off the alarm.
2368 func (m *M) stopAlarm() {
2374 func parseCpuList() {
2375 for _, val := range strings.Split(*cpuListStr, ",") {
2376 val = strings.TrimSpace(val)
2380 cpu, err := strconv.Atoi(val)
2381 if err != nil || cpu <= 0 {
2382 fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val)
2385 cpuList = append(cpuList, cpu)
2388 cpuList = append(cpuList, runtime.GOMAXPROCS(-1))
2392 func shouldFailFast() bool {
2393 return *failFast && numFailed.Load() > 0