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 raceErrors int // Number of races detected during test.
615 runner string // Function name of tRunner running the test.
616 isParallel bool // Whether the test is parallel.
619 level int // Nesting depth of test or benchmark.
620 creator []uintptr // If level > 0, the stack trace at the point where the parent called t.Run.
621 name string // Name of test or benchmark.
622 start time.Time // Time test or benchmark started
623 duration time.Duration
624 barrier chan bool // To signal parallel subtests they may start. Nil when T.Parallel is not present (B) or not usable (when fuzzing).
625 signal chan bool // To signal a test is done.
626 sub []*T // Queue of subtests to be run in parallel.
634 // Short reports whether the -test.short flag is set.
637 panic("testing: Short called before Init")
639 // Catch code that calls this from TestMain without first calling flag.Parse.
641 panic("testing: Short called before Parse")
647 // testBinary is set by cmd/go to "1" if this is a binary built by "go test".
648 // The value is set to "1" by a -X option to cmd/link. We assume that
649 // because this is possible, the compiler will not optimize testBinary
650 // into a constant on the basis that it is an unexported package-scope
651 // variable that is never changed. If the compiler ever starts implementing
652 // such an optimization, we will need some technique to mark this variable
653 // as "changed by a cmd/link -X option".
656 // Testing reports whether the current code is being run in a test.
657 // This will report true in programs created by "go test",
658 // false in programs created by "go build".
659 func Testing() bool {
660 return testBinary == "1"
663 // CoverMode reports what the test coverage mode is set to. The
664 // values are "set", "count", or "atomic". The return value will be
665 // empty if test coverage is not enabled.
666 func CoverMode() string {
667 if goexperiment.CoverageRedesign {
673 // Verbose reports whether the -test.v flag is set.
674 func Verbose() bool {
677 panic("testing: Verbose called before Parse")
682 func (c *common) checkFuzzFn(name string) {
684 panic(fmt.Sprintf("testing: f.%s was called inside the fuzz target, use t.%s instead", name, name))
688 // frameSkip searches, starting after skip frames, for the first caller frame
689 // in a function not marked as a helper and returns that frame.
690 // The search stops if it finds a tRunner function that
691 // was the entry point into the test and the test is not a subtest.
692 // This function must be called with c.mu held.
693 func (c *common) frameSkip(skip int) runtime.Frame {
694 // If the search continues into the parent test, we'll have to hold
695 // its mu temporarily. If we then return, we need to unlock it.
696 shouldUnlock := false
702 var pc [maxStackLen]uintptr
703 // Skip two extra frames to account for this function
704 // and runtime.Callers itself.
705 n := runtime.Callers(skip+2, pc[:])
707 panic("testing: zero callers found")
709 frames := runtime.CallersFrames(pc[:n])
710 var firstFrame, prevFrame, frame runtime.Frame
711 for more := true; more; prevFrame = frame {
712 frame, more = frames.Next()
713 if frame.Function == "runtime.gopanic" {
716 if frame.Function == c.cleanupName {
717 frames = runtime.CallersFrames(c.cleanupPc)
720 if firstFrame.PC == 0 {
723 if frame.Function == c.runner {
724 // We've gone up all the way to the tRunner calling
725 // the test function (so the user must have
726 // called tb.Helper from inside that test function).
727 // If this is a top-level test, only skip up to the test function itself.
728 // If we're in a subtest, continue searching in the parent test,
729 // starting from the point of the call to Run which created this subtest.
731 frames = runtime.CallersFrames(c.creator)
733 // We're no longer looking at the current c after this point,
734 // so we should unlock its mu, unless it's the original receiver,
735 // in which case our caller doesn't expect us to do that.
740 // Remember to unlock c.mu when we no longer need it, either
741 // because we went up another nesting level, or because we
749 // If more helper PCs have been added since we last did the conversion
750 if c.helperNames == nil {
751 c.helperNames = make(map[string]struct{})
752 for pc := range c.helperPCs {
753 c.helperNames[pcToName(pc)] = struct{}{}
756 if _, ok := c.helperNames[frame.Function]; !ok {
757 // Found a frame that wasn't inside a helper function.
764 // decorate prefixes the string with the file and line of the call site
765 // and inserts the final newline if needed and indentation spaces for formatting.
766 // This function must be called with c.mu held.
767 func (c *common) decorate(s string, skip int) string {
768 frame := c.frameSkip(skip)
773 // If relative path, truncate file name at last file name separator.
774 } else if index := strings.LastIndexAny(file, `/\`); index >= 0 {
775 file = file[index+1:]
783 buf := new(strings.Builder)
784 // Every line is indented at least 4 spaces.
786 fmt.Fprintf(buf, "%s:%d: ", file, line)
787 lines := strings.Split(s, "\n")
788 if l := len(lines); l > 1 && lines[l-1] == "" {
791 for i, line := range lines {
793 // Second and subsequent lines are indented an additional 4 spaces.
794 buf.WriteString("\n ")
796 buf.WriteString(line)
802 // flushToParent writes c.output to the parent after first writing the header
803 // with the given format and arguments.
804 func (c *common) flushToParent(testName, format string, args ...any) {
812 if len(c.output) > 0 {
813 // Add the current c.output to the print,
814 // and then arrange for the print to replace c.output.
815 // (This displays the logged output after the --- FAIL line.)
817 args = append(args[:len(args):len(args)], c.output)
818 c.output = c.output[:0]
821 if c.chatty != nil && (p.w == c.chatty.w || c.chatty.json) {
822 // We're flushing to the actual output, so track that this output is
823 // associated with a specific test (and, specifically, that the next output
824 // is *not* associated with that test).
826 // Moreover, if c.output is non-empty it is important that this write be
827 // atomic with respect to the output of other tests, so that we don't end up
828 // with confusing '=== NAME' lines in the middle of our '--- PASS' block.
829 // Neither humans nor cmd/test2json can parse those easily.
830 // (See https://go.dev/issue/40771.)
832 // If test2json is used, we never flush to parent tests,
833 // so that the json stream shows subtests as they finish.
834 // (See https://go.dev/issue/29811.)
835 c.chatty.Updatef(testName, format, args...)
837 // We're flushing to the output buffer of the parent test, which will
838 // itself follow a test-name header when it is finally flushed to stdout.
839 fmt.Fprintf(p.w, c.chatty.prefix()+format, args...)
843 type indenter struct {
847 func (w indenter) Write(b []byte) (n int, err error) {
850 end := bytes.IndexByte(b, '\n')
856 // An indent of 4 spaces will neatly align the dashes with the status
857 // indicator of the parent.
859 if line[0] == marker {
860 w.c.output = append(w.c.output, marker)
864 w.c.output = append(w.c.output, indent...)
865 w.c.output = append(w.c.output, line...)
871 // fmtDuration returns a string representing d in the form "87.00s".
872 func fmtDuration(d time.Duration) string {
873 return fmt.Sprintf("%.2fs", d.Seconds())
876 // TB is the interface common to T, B, and F.
880 Errorf(format string, args ...any)
885 Fatalf(format string, args ...any)
888 Logf(format string, args ...any)
890 Setenv(key, value string)
893 Skipf(format string, args ...any)
897 // A private method to prevent users implementing the
898 // interface and so future additions to it will not
899 // violate Go 1 compatibility.
906 // T is a type passed to Test functions to manage test state and support formatted test logs.
908 // A test ends when its Test function returns or calls any of the methods
909 // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as
910 // the Parallel method, must be called only from the goroutine running the
913 // The other reporting methods, such as the variations of Log and Error,
914 // may be called simultaneously from multiple goroutines.
918 context *testContext // For running tests and subtests.
921 func (c *common) private() {}
923 // Name returns the name of the running (sub-) test or benchmark.
925 // The name will include the name of the test along with the names of
926 // any nested sub-tests. If two sibling sub-tests have the same name,
927 // Name will append a suffix to guarantee the returned name is unique.
928 func (c *common) Name() string {
932 func (c *common) setRan() {
941 // Fail marks the function as having failed but continues execution.
942 func (c *common) Fail() {
948 // c.done needs to be locked to synchronize checks to c.done in parent tests.
950 panic("Fail in goroutine after " + c.name + " has completed")
955 // Failed reports whether the function has failed.
956 func (c *common) Failed() bool {
960 return failed || c.raceErrors+race.Errors() > 0
963 // FailNow marks the function as having failed and stops its execution
964 // by calling runtime.Goexit (which then runs all deferred calls in the
965 // current goroutine).
966 // Execution will continue at the next test or benchmark.
967 // FailNow must be called from the goroutine running the
968 // test or benchmark function, not from other goroutines
969 // created during the test. Calling FailNow does not stop
970 // those other goroutines.
971 func (c *common) FailNow() {
972 c.checkFuzzFn("FailNow")
975 // Calling runtime.Goexit will exit the goroutine, which
976 // will run the deferred functions in this goroutine,
977 // which will eventually run the deferred lines in tRunner,
978 // which will signal to the test loop that this test is done.
980 // A previous version of this code said:
983 // c.signal <- c.self
986 // This previous version duplicated code (those lines are in
987 // tRunner no matter what), but worse the goroutine teardown
988 // implicit in runtime.Goexit was not guaranteed to complete
989 // before the test exited. If a test deferred an important cleanup
990 // function (like removing temporary files), there was no guarantee
991 // it would run on a test failure. Because we send on c.signal during
992 // a top-of-stack deferred function now, we know that the send
993 // only happens after any other stacked defers have completed.
1000 // log generates the output. It's always at the same stack depth.
1001 func (c *common) log(s string) {
1002 c.logDepth(s, 3) // logDepth + log + public function
1005 // logDepth generates the output at an arbitrary stack depth.
1006 func (c *common) logDepth(s string, depth int) {
1010 // This test has already finished. Try and log this message
1011 // with our parent. If we don't have a parent, panic.
1012 for parent := c.parent; parent != nil; parent = parent.parent {
1014 defer parent.mu.Unlock()
1016 parent.output = append(parent.output, parent.decorate(s, depth+1)...)
1020 panic("Log in goroutine after " + c.name + " has completed: " + s)
1022 if c.chatty != nil {
1024 // Benchmarks don't print === CONT, so we should skip the test
1025 // printer and just print straight to stdout.
1026 fmt.Print(c.decorate(s, depth+1))
1028 c.chatty.Printf(c.name, "%s", c.decorate(s, depth+1))
1033 c.output = append(c.output, c.decorate(s, depth+1)...)
1037 // Log formats its arguments using default formatting, analogous to Println,
1038 // and records the text in the error log. For tests, the text will be printed only if
1039 // the test fails or the -test.v flag is set. For benchmarks, the text is always
1040 // printed to avoid having performance depend on the value of the -test.v flag.
1041 func (c *common) Log(args ...any) {
1042 c.checkFuzzFn("Log")
1043 c.log(fmt.Sprintln(args...))
1046 // Logf formats its arguments according to the format, analogous to Printf, and
1047 // records the text in the error log. A final newline is added if not provided. For
1048 // tests, the text will be printed only if the test fails or the -test.v flag is
1049 // set. For benchmarks, the text is always printed to avoid having performance
1050 // depend on the value of the -test.v flag.
1051 func (c *common) Logf(format string, args ...any) {
1052 c.checkFuzzFn("Logf")
1053 c.log(fmt.Sprintf(format, args...))
1056 // Error is equivalent to Log followed by Fail.
1057 func (c *common) Error(args ...any) {
1058 c.checkFuzzFn("Error")
1059 c.log(fmt.Sprintln(args...))
1063 // Errorf is equivalent to Logf followed by Fail.
1064 func (c *common) Errorf(format string, args ...any) {
1065 c.checkFuzzFn("Errorf")
1066 c.log(fmt.Sprintf(format, args...))
1070 // Fatal is equivalent to Log followed by FailNow.
1071 func (c *common) Fatal(args ...any) {
1072 c.checkFuzzFn("Fatal")
1073 c.log(fmt.Sprintln(args...))
1077 // Fatalf is equivalent to Logf followed by FailNow.
1078 func (c *common) Fatalf(format string, args ...any) {
1079 c.checkFuzzFn("Fatalf")
1080 c.log(fmt.Sprintf(format, args...))
1084 // Skip is equivalent to Log followed by SkipNow.
1085 func (c *common) Skip(args ...any) {
1086 c.checkFuzzFn("Skip")
1087 c.log(fmt.Sprintln(args...))
1091 // Skipf is equivalent to Logf followed by SkipNow.
1092 func (c *common) Skipf(format string, args ...any) {
1093 c.checkFuzzFn("Skipf")
1094 c.log(fmt.Sprintf(format, args...))
1098 // SkipNow marks the test as having been skipped and stops its execution
1099 // by calling runtime.Goexit.
1100 // If a test fails (see Error, Errorf, Fail) and is then skipped,
1101 // it is still considered to have failed.
1102 // Execution will continue at the next test or benchmark. See also FailNow.
1103 // SkipNow must be called from the goroutine running the test, not from
1104 // other goroutines created during the test. Calling SkipNow does not stop
1105 // those other goroutines.
1106 func (c *common) SkipNow() {
1107 c.checkFuzzFn("SkipNow")
1115 // Skipped reports whether the test was skipped.
1116 func (c *common) Skipped() bool {
1118 defer c.mu.RUnlock()
1122 // Helper marks the calling function as a test helper function.
1123 // When printing file and line information, that function will be skipped.
1124 // Helper may be called simultaneously from multiple goroutines.
1125 func (c *common) Helper() {
1128 if c.helperPCs == nil {
1129 c.helperPCs = make(map[uintptr]struct{})
1131 // repeating code from callerName here to save walking a stack frame
1133 n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper
1135 panic("testing: zero callers found")
1137 if _, found := c.helperPCs[pc[0]]; !found {
1138 c.helperPCs[pc[0]] = struct{}{}
1139 c.helperNames = nil // map will be recreated next time it is needed
1143 // Cleanup registers a function to be called when the test (or subtest) and all its
1144 // subtests complete. Cleanup functions will be called in last added,
1145 // first called order.
1146 func (c *common) Cleanup(f func()) {
1147 c.checkFuzzFn("Cleanup")
1148 var pc [maxStackLen]uintptr
1149 // Skip two extra frames to account for this function and runtime.Callers itself.
1150 n := runtime.Callers(2, pc[:])
1161 name := callerName(0)
1163 c.cleanupName = name
1164 c.cleanupPc = cleanupPc
1172 c.cleanups = append(c.cleanups, fn)
1175 // TempDir returns a temporary directory for the test to use.
1176 // The directory is automatically removed when the test and
1177 // all its subtests complete.
1178 // Each subsequent call to t.TempDir returns a unique directory;
1179 // if the directory creation fails, TempDir terminates the test by calling Fatal.
1180 func (c *common) TempDir() string {
1181 c.checkFuzzFn("TempDir")
1182 // Use a single parent directory for all the temporary directories
1183 // created by a test, each numbered sequentially.
1185 var nonExistent bool
1186 if c.tempDir == "" { // Usually the case with js/wasm
1189 _, err := os.Stat(c.tempDir)
1190 nonExistent = os.IsNotExist(err)
1191 if err != nil && !nonExistent {
1192 c.Fatalf("TempDir: %v", err)
1199 // Drop unusual characters (such as path separators or
1200 // characters interacting with globs) from the directory name to
1201 // avoid surprising os.MkdirTemp behavior.
1202 mapper := func(r rune) rune {
1203 if r < utf8.RuneSelf {
1204 const allowed = "!#$%&()+,-.=@^_{}~ "
1205 if '0' <= r && r <= '9' ||
1206 'a' <= r && r <= 'z' ||
1207 'A' <= r && r <= 'Z' {
1210 if strings.ContainsRune(allowed, r) {
1213 } else if unicode.IsLetter(r) || unicode.IsNumber(r) {
1218 pattern := strings.Map(mapper, c.Name())
1219 c.tempDir, c.tempDirErr = os.MkdirTemp("", pattern)
1220 if c.tempDirErr == nil {
1222 if err := removeAll(c.tempDir); err != nil {
1223 c.Errorf("TempDir RemoveAll cleanup: %v", err)
1229 if c.tempDirErr == nil {
1233 c.tempDirMu.Unlock()
1235 if c.tempDirErr != nil {
1236 c.Fatalf("TempDir: %v", c.tempDirErr)
1239 dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)
1240 if err := os.Mkdir(dir, 0777); err != nil {
1241 c.Fatalf("TempDir: %v", err)
1246 // removeAll is like os.RemoveAll, but retries Windows "Access is denied."
1247 // errors up to an arbitrary timeout.
1249 // Those errors have been known to occur spuriously on at least the
1250 // windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur
1251 // legitimately if the test leaves behind a temp file that either is still open
1252 // or the test otherwise lacks permission to delete. In the case of legitimate
1253 // failures, a failing test may take a bit longer to fail, but once the test is
1254 // fixed the extra latency will go away.
1255 func removeAll(path string) error {
1256 const arbitraryTimeout = 2 * time.Second
1259 nextSleep = 1 * time.Millisecond
1262 err := os.RemoveAll(path)
1263 if !isWindowsRetryable(err) {
1268 } else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {
1271 time.Sleep(nextSleep)
1272 nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))
1276 // Setenv calls os.Setenv(key, value) and uses Cleanup to
1277 // restore the environment variable to its original value
1280 // Because Setenv affects the whole process, it cannot be used
1281 // in parallel tests or tests with parallel ancestors.
1282 func (c *common) Setenv(key, value string) {
1283 c.checkFuzzFn("Setenv")
1284 prevValue, ok := os.LookupEnv(key)
1286 if err := os.Setenv(key, value); err != nil {
1287 c.Fatalf("cannot set environment variable: %v", err)
1292 os.Setenv(key, prevValue)
1301 // panicHanding is an argument to runCleanup.
1302 type panicHandling int
1305 normalPanic panicHandling = iota
1306 recoverAndReturnPanic
1309 // runCleanup is called at the end of the test.
1310 // If catchPanic is true, this will catch panics, and return the recovered
1312 func (c *common) runCleanup(ph panicHandling) (panicVal any) {
1313 c.cleanupStarted.Store(true)
1314 defer c.cleanupStarted.Store(false)
1316 if ph == recoverAndReturnPanic {
1318 panicVal = recover()
1322 // Make sure that if a cleanup function panics,
1323 // we still run the remaining cleanup functions.
1326 recur := len(c.cleanups) > 0
1329 c.runCleanup(normalPanic)
1336 if len(c.cleanups) > 0 {
1337 last := len(c.cleanups) - 1
1338 cleanup = c.cleanups[last]
1339 c.cleanups = c.cleanups[:last]
1349 // callerName gives the function name (qualified with a package path)
1350 // for the caller after skip frames (where 0 means the current function).
1351 func callerName(skip int) string {
1353 n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName
1355 panic("testing: zero callers found")
1357 return pcToName(pc[0])
1360 func pcToName(pc uintptr) string {
1361 pcs := []uintptr{pc}
1362 frames := runtime.CallersFrames(pcs)
1363 frame, _ := frames.Next()
1364 return frame.Function
1367 // Parallel signals that this test is to be run in parallel with (and only with)
1368 // other parallel tests. When a test is run multiple times due to use of
1369 // -test.count or -test.cpu, multiple instances of a single test never run in
1370 // parallel with each other.
1371 func (t *T) Parallel() {
1373 panic("testing: t.Parallel called multiple times")
1376 panic("testing: t.Parallel called after t.Setenv; cannot set environment variables in parallel tests")
1379 if t.parent.barrier == nil {
1380 // T.Parallel has no effect when fuzzing.
1381 // Multiple processes may run in parallel, but only one input can run at a
1382 // time per process so we can attribute crashes to specific inputs.
1386 // We don't want to include the time we spend waiting for serial tests
1387 // in the test duration. Record the elapsed time thus far and reset the
1388 // timer afterwards.
1389 t.duration += time.Since(t.start)
1391 // Add to the list of tests to be released by the parent.
1392 t.parent.sub = append(t.parent.sub, t)
1393 t.raceErrors += race.Errors()
1395 if t.chatty != nil {
1396 t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)
1398 running.Delete(t.name)
1400 t.signal <- true // Release calling test.
1401 <-t.parent.barrier // Wait for the parent test to complete.
1402 t.context.waitParallel()
1404 if t.chatty != nil {
1405 t.chatty.Updatef(t.name, "=== CONT %s\n", t.name)
1407 running.Store(t.name, time.Now())
1409 t.start = time.Now()
1410 t.raceErrors += -race.Errors()
1413 // Setenv calls os.Setenv(key, value) and uses Cleanup to
1414 // restore the environment variable to its original value
1417 // Because Setenv affects the whole process, it cannot be used
1418 // in parallel tests or tests with parallel ancestors.
1419 func (t *T) Setenv(key, value string) {
1420 // Non-parallel subtests that have parallel ancestors may still
1421 // run in parallel with other tests: they are only non-parallel
1422 // with respect to the other subtests of the same parent.
1423 // Since SetEnv affects the whole process, we need to disallow it
1424 // if the current test or any parent is parallel.
1426 for c := &t.common; c != nil; c = c.parent {
1433 panic("testing: t.Setenv called after t.Parallel; cannot set environment variables in parallel tests")
1438 t.common.Setenv(key, value)
1441 // InternalTest is an internal type but exported because it is cross-package;
1442 // it is part of the implementation of the "go test" command.
1443 type InternalTest struct {
1448 var errNilPanicOrGoexit = errors.New("test executed panic(nil) or runtime.Goexit")
1450 func tRunner(t *T, fn func(t *T)) {
1451 t.runner = callerName(0)
1453 // When this goroutine is done, either because fn(t)
1454 // returned normally or because a test failure triggered
1455 // a call to runtime.Goexit, record the duration and send
1456 // a signal saying that the test is done.
1462 if t.raceErrors+race.Errors() > 0 {
1463 t.Errorf("race detected during execution of test")
1466 // Check if the test panicked or Goexited inappropriately.
1468 // If this happens in a normal test, print output but continue panicking.
1469 // tRunner is called in its own goroutine, so this terminates the process.
1471 // If this happens while fuzzing, recover from the panic and treat it like a
1472 // normal failure. It's important that the process keeps running in order to
1473 // find short inputs that cause panics.
1478 finished := t.finished
1480 if !finished && err == nil {
1481 err = errNilPanicOrGoexit
1482 for p := t.parent; p != nil; p = p.parent {
1484 finished = p.finished
1488 t.Errorf("%v: subtest may have called FailNow on a parent test", err)
1497 if err != nil && t.context.isFuzzing {
1499 if err == errNilPanicOrGoexit {
1502 t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack()))
1509 // Use a deferred call to ensure that we report that the test is
1510 // complete even if a cleanup function calls t.FailNow. See issue 41355.
1513 // Only report that the test is complete if it doesn't panic,
1514 // as otherwise the test binary can exit before the panic is
1515 // reported to the user. See issue 41479.
1522 running.Delete(t.name)
1526 doPanic := func(err any) {
1528 if r := t.runCleanup(recoverAndReturnPanic); r != nil {
1529 t.Logf("cleanup panicked with %v", r)
1531 // Flush the output log up to the root before dying.
1532 for root := &t.common; root.parent != nil; root = root.parent {
1534 root.duration += time.Since(root.start)
1537 root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d))
1538 if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil {
1539 fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r)
1549 t.duration += time.Since(t.start)
1552 // Run parallel subtests.
1553 // Decrease the running count for this test.
1555 // Release the parallel subtests.
1557 // Wait for subtests to complete.
1558 for _, sub := range t.sub {
1561 cleanupStart := time.Now()
1562 err := t.runCleanup(recoverAndReturnPanic)
1563 t.duration += time.Since(cleanupStart)
1568 // Reacquire the count for sequential tests. See comment in Run.
1569 t.context.waitParallel()
1571 } else if t.isParallel {
1572 // Only release the count for this test if it was run as a parallel
1573 // test. See comment in Run method.
1576 t.report() // Report after all subtests have finished.
1578 // Do not lock t.done to allow race detector to detect race in case
1579 // the user does not appropriately synchronize a goroutine.
1581 if t.parent != nil && !t.hasSub.Load() {
1586 if len(t.sub) == 0 {
1587 t.runCleanup(normalPanic)
1591 t.start = time.Now()
1592 t.raceErrors = -race.Errors()
1595 // code beyond here will not be executed when FailNow is invoked
1601 // Run runs f as a subtest of t called name. It runs f in a separate goroutine
1602 // and blocks until f returns or calls t.Parallel to become a parallel test.
1603 // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
1605 // Run may be called simultaneously from multiple goroutines, but all such calls
1606 // must return before the outer test function for t returns.
1607 func (t *T) Run(name string, f func(t *T)) bool {
1608 if t.cleanupStarted.Load() {
1609 panic("testing: t.Run called during t.Cleanup")
1612 t.hasSub.Store(true)
1613 testName, ok, _ := t.context.match.fullName(&t.common, name)
1614 if !ok || shouldFailFast() {
1617 // Record the stack trace at the point of this call so that if the subtest
1618 // function - which runs in a separate stack - is marked as a helper, we can
1619 // continue walking the stack into the parent test.
1620 var pc [maxStackLen]uintptr
1621 n := runtime.Callers(2, pc[:])
1624 barrier: make(chan bool),
1625 signal: make(chan bool, 1),
1634 t.w = indenter{&t.common}
1636 if t.chatty != nil {
1637 t.chatty.Updatef(t.name, "=== RUN %s\n", t.name)
1639 running.Store(t.name, time.Now())
1641 // Instead of reducing the running count of this test before calling the
1642 // tRunner and increasing it afterwards, we rely on tRunner keeping the
1643 // count correct. This ensures that a sequence of sequential tests runs
1644 // without being preempted, even when their parent is a parallel test. This
1645 // may especially reduce surprises if *parallel == 1.
1648 // At this point, it is likely that FailNow was called on one of the
1649 // parent tests by one of the subtests. Continue aborting up the chain.
1652 if t.chatty != nil && t.chatty.json {
1653 t.chatty.Updatef(t.parent.name, "=== NAME %s\n", t.parent.name)
1658 // Deadline reports the time at which the test binary will have
1659 // exceeded the timeout specified by the -timeout flag.
1661 // The ok result is false if the -timeout flag indicates “no timeout” (0).
1662 func (t *T) Deadline() (deadline time.Time, ok bool) {
1663 deadline = t.context.deadline
1664 return deadline, !deadline.IsZero()
1667 // testContext holds all fields that are common to all tests. This includes
1668 // synchronization primitives to run at most *parallel tests.
1669 type testContext struct {
1673 // isFuzzing is true in the context used when generating random inputs
1674 // for fuzz targets. isFuzzing is false when running normal tests and
1675 // when running fuzz tests as unit tests (without -fuzz or when -fuzz
1681 // Channel used to signal tests that are ready to be run in parallel.
1682 startParallel chan bool
1684 // running is the number of tests currently running in parallel.
1685 // This does not include tests that are waiting for subtests to complete.
1688 // numWaiting is the number tests waiting to be run in parallel.
1691 // maxParallel is a copy of the parallel flag.
1695 func newTestContext(maxParallel int, m *matcher) *testContext {
1696 return &testContext{
1698 startParallel: make(chan bool),
1699 maxParallel: maxParallel,
1700 running: 1, // Set the count to 1 for the main (sequential) test.
1704 func (c *testContext) waitParallel() {
1706 if c.running < c.maxParallel {
1716 func (c *testContext) release() {
1718 if c.numWaiting == 0 {
1725 c.startParallel <- true // Pick a waiting test to be run.
1728 // No one should be using func Main anymore.
1729 // See the doc comment on func Main and use MainStart instead.
1730 var errMain = errors.New("testing: unexpected use of func Main")
1732 type matchStringOnly func(pat, str string) (bool, error)
1734 func (f matchStringOnly) MatchString(pat, str string) (bool, error) { return f(pat, str) }
1735 func (f matchStringOnly) StartCPUProfile(w io.Writer) error { return errMain }
1736 func (f matchStringOnly) StopCPUProfile() {}
1737 func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain }
1738 func (f matchStringOnly) ImportPath() string { return "" }
1739 func (f matchStringOnly) StartTestLog(io.Writer) {}
1740 func (f matchStringOnly) StopTestLog() error { return errMain }
1741 func (f matchStringOnly) SetPanicOnExit0(bool) {}
1742 func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error {
1745 func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain }
1746 func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) {
1749 func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil }
1750 func (f matchStringOnly) ResetCoverage() {}
1751 func (f matchStringOnly) SnapshotCoverage() {}
1753 // Main is an internal function, part of the implementation of the "go test" command.
1754 // It was exported because it is cross-package and predates "internal" packages.
1755 // It is no longer used by "go test" but preserved, as much as possible, for other
1756 // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
1757 // new functionality is added to the testing package.
1758 // Systems simulating "go test" should be updated to use MainStart.
1759 func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {
1760 os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run())
1763 // M is a type passed to a TestMain function to run the actual tests.
1766 tests []InternalTest
1767 benchmarks []InternalBenchmark
1768 fuzzTargets []InternalFuzzTarget
1769 examples []InternalExample
1776 // value to pass to os.Exit, the outer test func main
1777 // harness calls os.Exit with this code. See #34129.
1781 // testDeps is an internal interface of functionality that is
1782 // passed into this package by a test's generated main package.
1783 // The canonical implementation of this interface is
1784 // testing/internal/testdeps's TestDeps.
1785 type testDeps interface {
1787 MatchString(pat, str string) (bool, error)
1788 SetPanicOnExit0(bool)
1789 StartCPUProfile(io.Writer) error
1791 StartTestLog(io.Writer)
1793 WriteProfileTo(string, io.Writer, int) error
1794 CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error
1795 RunFuzzWorker(func(corpusEntry) error) error
1796 ReadCorpus(string, []reflect.Type) ([]corpusEntry, error)
1797 CheckCorpus([]any, []reflect.Type) error
1802 // MainStart is meant for use by tests generated by 'go test'.
1803 // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
1804 // It may change signature from release to release.
1805 func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M {
1810 benchmarks: benchmarks,
1811 fuzzTargets: fuzzTargets,
1816 var testingTesting bool
1817 var realStderr *os.File
1819 // Run runs the tests. It returns an exit code to pass to os.Exit.
1820 func (m *M) Run() (code int) {
1825 // Count the number of calls to m.Run.
1826 // We only ever expected 1, but we didn't enforce that,
1827 // and now there are tests in the wild that call m.Run multiple times.
1828 // Sigh. go.dev/issue/23129.
1831 // TestMain may have already called flag.Parse.
1837 // With -v=json, stdout and stderr are pointing to the same pipe,
1838 // which is leading into test2json. In general, operating systems
1839 // do a good job of ensuring that writes to the same pipe through
1840 // different file descriptors are delivered whole, so that writing
1841 // AAA to stdout and BBB to stderr simultaneously produces
1842 // AAABBB or BBBAAA on the pipe, not something like AABBBA.
1843 // However, the exception to this is when the pipe fills: in that
1844 // case, Go's use of non-blocking I/O means that writing AAA
1845 // or BBB might be split across multiple system calls, making it
1846 // entirely possible to get output like AABBBA. The same problem
1847 // happens inside the operating system kernel if we switch to
1848 // blocking I/O on the pipe. This interleaved output can do things
1849 // like print unrelated messages in the middle of a TestFoo line,
1850 // which confuses test2json. Setting os.Stderr = os.Stdout will make
1851 // them share a single pfd, which will hold a lock for each program
1852 // write, preventing any interleaving.
1854 // It might be nice to set Stderr = Stdout always, or perhaps if
1855 // we can tell they are the same file, but for now -v=json is
1856 // a very clear signal. Making the two files the same may cause
1857 // surprises if programs close os.Stdout but expect to be able
1858 // to continue to write to os.Stderr, but it's hard to see why a
1859 // test would think it could take over global state that way.
1861 // This fix only helps programs where the output is coming directly
1862 // from Go code. It does not help programs in which a subprocess is
1863 // writing to stderr or stdout at the same time that a Go test is writing output.
1864 // It also does not help when the output is coming from the runtime,
1865 // such as when using the print/println functions, since that code writes
1866 // directly to fd 2 without any locking.
1867 // We keep realStderr around to prevent fd 2 from being closed.
1869 // See go.dev/issue/33419.
1870 realStderr = os.Stderr
1871 os.Stderr = os.Stdout
1875 fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer")
1880 if *matchFuzz != "" && *fuzzCacheDir == "" {
1881 fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set")
1887 if *matchList != "" {
1888 listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples)
1893 if *shuffle != "off" {
1896 if *shuffle == "on" {
1897 n = time.Now().UnixNano()
1899 n, err = strconv.ParseInt(*shuffle, 10, 64)
1901 fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err)
1906 fmt.Println("-test.shuffle", n)
1907 rng := rand.New(rand.NewSource(n))
1908 rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] })
1909 rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] })
1917 // Run tests, examples, and benchmarks unless this is a fuzz worker process.
1918 // Workers start after this is done by their parent process, and they should
1919 // not repeat this work.
1921 deadline := m.startAlarm()
1922 haveExamples = len(m.examples) > 0
1923 testRan, testOk := runTests(m.deps.MatchString, m.tests, deadline)
1924 fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline)
1925 exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples)
1927 if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" {
1928 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
1929 if testingTesting && *match != "^$" {
1930 // If this happens during testing of package testing it could be that
1931 // package testing's own logic for when to run a test is broken,
1932 // in which case every test will run nothing and succeed,
1933 // with no obvious way to detect this problem (since no tests are running).
1934 // So make 'no tests to run' a hard failure when testing package testing itself.
1935 fmt.Print(chatty.prefix(), "FAIL: package testing must run tests\n")
1939 if !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks) || race.Errors() > 0 {
1940 fmt.Print(chatty.prefix(), "FAIL\n")
1946 fuzzingOk := runFuzzing(m.deps, m.fuzzTargets)
1948 fmt.Print(chatty.prefix(), "FAIL\n")
1950 m.exitCode = fuzzWorkerExitCode
1959 fmt.Print(chatty.prefix(), "PASS\n")
1964 func (t *T) report() {
1965 if t.parent == nil {
1968 dstr := fmtDuration(t.duration)
1969 format := "--- %s: %s (%s)\n"
1971 t.flushToParent(t.name, format, "FAIL", t.name, dstr)
1972 } else if t.chatty != nil {
1974 t.flushToParent(t.name, format, "SKIP", t.name, dstr)
1976 t.flushToParent(t.name, format, "PASS", t.name, dstr)
1981 func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) {
1982 if _, err := matchString(*matchList, "non-empty"); err != nil {
1983 fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err)
1987 for _, test := range tests {
1988 if ok, _ := matchString(*matchList, test.Name); ok {
1989 fmt.Println(test.Name)
1992 for _, bench := range benchmarks {
1993 if ok, _ := matchString(*matchList, bench.Name); ok {
1994 fmt.Println(bench.Name)
1997 for _, fuzzTarget := range fuzzTargets {
1998 if ok, _ := matchString(*matchList, fuzzTarget.Name); ok {
1999 fmt.Println(fuzzTarget.Name)
2002 for _, example := range examples {
2003 if ok, _ := matchString(*matchList, example.Name); ok {
2004 fmt.Println(example.Name)
2009 // RunTests is an internal function but exported because it is cross-package;
2010 // it is part of the implementation of the "go test" command.
2011 func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {
2012 var deadline time.Time
2014 deadline = time.Now().Add(*timeout)
2016 ran, ok := runTests(matchString, tests, deadline)
2017 if !ran && !haveExamples {
2018 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
2023 func runTests(matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
2025 for _, procs := range cpuList {
2026 runtime.GOMAXPROCS(procs)
2027 for i := uint(0); i < *count; i++ {
2028 if shouldFailFast() {
2032 // There were no tests to run on the first
2033 // iteration. This won't change, so no reason
2037 ctx := newTestContext(*parallel, newMatcher(matchString, *match, "-test.run", *skip))
2038 ctx.deadline = deadline
2041 signal: make(chan bool, 1),
2042 barrier: make(chan bool),
2048 t.chatty = newChattyPrinter(t.w)
2050 tRunner(t, func(t *T) {
2051 for _, test := range tests {
2052 t.Run(test.Name, test.F)
2058 panic("internal error: tRunner exited without sending on t.signal")
2060 ok = ok && !t.Failed()
2067 // before runs before all testing.
2068 func (m *M) before() {
2069 if *memProfileRate > 0 {
2070 runtime.MemProfileRate = *memProfileRate
2072 if *cpuProfile != "" {
2073 f, err := os.Create(toOutputDir(*cpuProfile))
2075 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2078 if err := m.deps.StartCPUProfile(f); err != nil {
2079 fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err)
2083 // Could save f so after can call f.Close; not worth the effort.
2085 if *traceFile != "" {
2086 f, err := os.Create(toOutputDir(*traceFile))
2088 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2091 if err := trace.Start(f); err != nil {
2092 fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err)
2096 // Could save f so after can call f.Close; not worth the effort.
2098 if *blockProfile != "" && *blockProfileRate >= 0 {
2099 runtime.SetBlockProfileRate(*blockProfileRate)
2101 if *mutexProfile != "" && *mutexProfileFraction >= 0 {
2102 runtime.SetMutexProfileFraction(*mutexProfileFraction)
2104 if *coverProfile != "" && CoverMode() == "" {
2105 fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
2108 if *gocoverdir != "" && CoverMode() == "" {
2109 fmt.Fprintf(os.Stderr, "testing: cannot use -test.gocoverdir because test binary was not built with coverage enabled\n")
2113 // Note: Not using toOutputDir.
2114 // This file is for use by cmd/go, not users.
2118 f, err = os.Create(*testlog)
2120 f, err = os.OpenFile(*testlog, os.O_WRONLY, 0)
2122 f.Seek(0, io.SeekEnd)
2126 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2129 m.deps.StartTestLog(f)
2133 m.deps.SetPanicOnExit0(true)
2137 // after runs after all testing.
2138 func (m *M) after() {
2139 m.afterOnce.Do(func() {
2143 // Restore PanicOnExit0 after every run, because we set it to true before
2144 // every run. Otherwise, if m.Run is called multiple times the behavior of
2145 // os.Exit(0) will not be restored after the second run.
2147 m.deps.SetPanicOnExit0(false)
2151 func (m *M) writeProfiles() {
2153 if err := m.deps.StopTestLog(); err != nil {
2154 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
2157 if err := testlogFile.Close(); err != nil {
2158 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
2162 if *cpuProfile != "" {
2163 m.deps.StopCPUProfile() // flushes profile to disk
2165 if *traceFile != "" {
2166 trace.Stop() // flushes trace to disk
2168 if *memProfile != "" {
2169 f, err := os.Create(toOutputDir(*memProfile))
2171 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2174 runtime.GC() // materialize all statistics
2175 if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil {
2176 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err)
2181 if *blockProfile != "" && *blockProfileRate >= 0 {
2182 f, err := os.Create(toOutputDir(*blockProfile))
2184 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2187 if err = m.deps.WriteProfileTo("block", f, 0); err != nil {
2188 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err)
2193 if *mutexProfile != "" && *mutexProfileFraction >= 0 {
2194 f, err := os.Create(toOutputDir(*mutexProfile))
2196 fmt.Fprintf(os.Stderr, "testing: %s\n", err)
2199 if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil {
2200 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err)
2205 if CoverMode() != "" {
2210 // toOutputDir returns the file name relocated, if required, to outputDir.
2211 // Simple implementation to avoid pulling in path/filepath.
2212 func toOutputDir(path string) string {
2213 if *outputDir == "" || path == "" {
2216 // On Windows, it's clumsy, but we can be almost always correct
2217 // by just looking for a drive letter and a colon.
2218 // Absolute paths always have a drive letter (ignoring UNC).
2219 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
2220 // what to do, but even then path/filepath doesn't help.
2221 // TODO: Worth doing better? Probably not, because we're here only
2222 // under the management of go test.
2223 if runtime.GOOS == "windows" && len(path) >= 2 {
2224 letter, colon := path[0], path[1]
2225 if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' {
2226 // If path starts with a drive letter we're stuck with it regardless.
2230 if os.IsPathSeparator(path[0]) {
2233 return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path)
2236 // startAlarm starts an alarm if requested.
2237 func (m *M) startAlarm() time.Time {
2242 deadline := time.Now().Add(*timeout)
2243 m.timer = time.AfterFunc(*timeout, func() {
2245 debug.SetTraceback("all")
2248 if list := runningList(); len(list) > 0 {
2249 var b strings.Builder
2250 b.WriteString("\nrunning tests:")
2251 for _, name := range list {
2252 b.WriteString("\n\t")
2257 panic(fmt.Sprintf("test timed out after %v%s", *timeout, extra))
2262 // runningList returns the list of running tests.
2263 func runningList() []string {
2265 running.Range(func(k, v any) bool {
2266 list = append(list, fmt.Sprintf("%s (%v)", k.(string), time.Since(v.(time.Time)).Round(time.Second)))
2273 // stopAlarm turns off the alarm.
2274 func (m *M) stopAlarm() {
2280 func parseCpuList() {
2281 for _, val := range strings.Split(*cpuListStr, ",") {
2282 val = strings.TrimSpace(val)
2286 cpu, err := strconv.Atoi(val)
2287 if err != nil || cpu <= 0 {
2288 fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val)
2291 cpuList = append(cpuList, cpu)
2294 cpuList = append(cpuList, runtime.GOMAXPROCS(-1))
2298 func shouldFailFast() bool {
2299 return *failFast && numFailed.Load() > 0