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. 4 5// Package testing provides support for automated testing of Go packages. 6// It is intended to be used in concert with the "go test" command, which automates 7// execution of any function of the form 8// func TestXxx(*testing.T) 9// where Xxx does not start with a lowercase letter. The function name 10// serves to identify the test routine. 11// 12// Within these functions, use the Error, Fail or related methods to signal failure. 13// 14// To write a new test suite, create a file whose name ends _test.go that 15// contains the TestXxx functions as described here. Put the file in the same 16// package as the one being tested. The file will be excluded from regular 17// package builds but will be included when the "go test" command is run. 18// For more detail, run "go help test" and "go help testflag". 19// 20// A simple test function looks like this: 21// 22// func TestAbs(t *testing.T) { 23// got := Abs(-1) 24// if got != 1 { 25// t.Errorf("Abs(-1) = %d; want 1", got) 26// } 27// } 28// 29// Benchmarks 30// 31// Functions of the form 32// func BenchmarkXxx(*testing.B) 33// are considered benchmarks, and are executed by the "go test" command when 34// its -bench flag is provided. Benchmarks are run sequentially. 35// 36// For a description of the testing flags, see 37// https://golang.org/cmd/go/#hdr-Testing_flags. 38// 39// A sample benchmark function looks like this: 40// func BenchmarkRandInt(b *testing.B) { 41// for i := 0; i < b.N; i++ { 42// rand.Int() 43// } 44// } 45// 46// The benchmark function must run the target code b.N times. 47// During benchmark execution, b.N is adjusted until the benchmark function lasts 48// long enough to be timed reliably. The output 49// BenchmarkRandInt-8 68453040 17.8 ns/op 50// means that the loop ran 68453040 times at a speed of 17.8 ns per loop. 51// 52// If a benchmark needs some expensive setup before running, the timer 53// may be reset: 54// 55// func BenchmarkBigLen(b *testing.B) { 56// big := NewBig() 57// b.ResetTimer() 58// for i := 0; i < b.N; i++ { 59// big.Len() 60// } 61// } 62// 63// If a benchmark needs to test performance in a parallel setting, it may use 64// the RunParallel helper function; such benchmarks are intended to be used with 65// the go test -cpu flag: 66// 67// func BenchmarkTemplateParallel(b *testing.B) { 68// templ := template.Must(template.New("test").Parse("Hello, {{.}}!")) 69// b.RunParallel(func(pb *testing.PB) { 70// var buf bytes.Buffer 71// for pb.Next() { 72// buf.Reset() 73// templ.Execute(&buf, "World") 74// } 75// }) 76// } 77// 78// A detailed specification of the benchmark results format is given 79// in https://golang.org/design/14313-benchmark-format. 80// 81// There are standard tools for working with benchmark results at 82// https://golang.org/x/perf/cmd. 83// In particular, https://golang.org/x/perf/cmd/benchstat performs 84// statistically robust A/B comparisons. 85// 86// Examples 87// 88// The package also runs and verifies example code. Example functions may 89// include a concluding line comment that begins with "Output:" and is compared with 90// the standard output of the function when the tests are run. (The comparison 91// ignores leading and trailing space.) These are examples of an example: 92// 93// func ExampleHello() { 94// fmt.Println("hello") 95// // Output: hello 96// } 97// 98// func ExampleSalutations() { 99// fmt.Println("hello, and") 100// fmt.Println("goodbye") 101// // Output: 102// // hello, and 103// // goodbye 104// } 105// 106// The comment prefix "Unordered output:" is like "Output:", but matches any 107// line order: 108// 109// func ExamplePerm() { 110// for _, value := range Perm(5) { 111// fmt.Println(value) 112// } 113// // Unordered output: 4 114// // 2 115// // 1 116// // 3 117// // 0 118// } 119// 120// Example functions without output comments are compiled but not executed. 121// 122// The naming convention to declare examples for the package, a function F, a type T and 123// method M on type T are: 124// 125// func Example() { ... } 126// func ExampleF() { ... } 127// func ExampleT() { ... } 128// func ExampleT_M() { ... } 129// 130// Multiple example functions for a package/type/function/method may be provided by 131// appending a distinct suffix to the name. The suffix must start with a 132// lower-case letter. 133// 134// func Example_suffix() { ... } 135// func ExampleF_suffix() { ... } 136// func ExampleT_suffix() { ... } 137// func ExampleT_M_suffix() { ... } 138// 139// The entire test file is presented as the example when it contains a single 140// example function, at least one other function, type, variable, or constant 141// declaration, and no test or benchmark functions. 142// 143// Fuzzing 144// 145// 'go test' and the testing package support fuzzing, a testing technique where 146// a function is called with randomly generated inputs to find bugs not 147// anticipated by unit tests. 148// 149// Functions of the form 150// func FuzzXxx(*testing.F) 151// are considered fuzz tests. 152// 153// For example: 154// 155// func FuzzHex(f *testing.F) { 156// for _, seed := range [][]byte{{}, {0}, {9}, {0xa}, {0xf}, {1, 2, 3, 4}} { 157// f.Add(seed) 158// } 159// f.Fuzz(func(t *testing.T, in []byte) { 160// enc := hex.EncodeToString(in) 161// out, err := hex.DecodeString(enc) 162// if err != nil { 163// t.Fatalf("%v: decode: %v", in, err) 164// } 165// if !bytes.Equal(in, out) { 166// t.Fatalf("%v: not equal after round trip: %v", in, out) 167// } 168// }) 169// } 170// 171// A fuzz test maintains a seed corpus, or a set of inputs which are run by 172// default, and can seed input generation. Seed inputs may be registered by 173// calling (*F).Add or by storing files in the directory testdata/fuzz/<Name> 174// (where <Name> is the name of the fuzz test) within the package containing 175// the fuzz test. Seed inputs are optional, but the fuzzing engine may find 176// bugs more efficiently when provided with a set of small seed inputs with good 177// code coverage. These seed inputs can also serve as regression tests for bugs 178// identified through fuzzing. 179// 180// The function passed to (*F).Fuzz within the fuzz test is considered the fuzz 181// target. A fuzz target must accept a *T parameter, followed by one or more 182// parameters for random inputs. The types of arguments passed to (*F).Add must 183// be identical to the types of these parameters. The fuzz target may signal 184// that it's found a problem the same way tests do: by calling T.Fail (or any 185// method that calls it like T.Error or T.Fatal) or by panicking. 186// 187// When fuzzing is enabled (by setting the -fuzz flag to a regular expression 188// that matches a specific fuzz test), the fuzz target is called with arguments 189// generated by repeatedly making random changes to the seed inputs. On 190// supported platforms, 'go test' compiles the test executable with fuzzing 191// coverage instrumentation. The fuzzing engine uses that instrumentation to 192// find and cache inputs that expand coverage, increasing the likelihood of 193// finding bugs. If the fuzz target fails for a given input, the fuzzing engine 194// writes the inputs that caused the failure to a file in the directory 195// testdata/fuzz/<Name> within the package directory. This file later serves as 196// a seed input. If the file can't be written at that location (for example, 197// because the directory is read-only), the fuzzing engine writes the file to 198// the fuzz cache directory within the build cache instead. 199// 200// When fuzzing is disabled, the fuzz target is called with the seed inputs 201// registered with F.Add and seed inputs from testdata/fuzz/<Name>. In this 202// mode, the fuzz test acts much like a regular test, with subtests started 203// with F.Fuzz instead of T.Run. 204// 205// TODO(#48255): write and link to documentation that will be helpful to users 206// who are unfamiliar with fuzzing. 207// 208// Skipping 209// 210// Tests or benchmarks may be skipped at run time with a call to 211// the Skip method of *T or *B: 212// 213// func TestTimeConsuming(t *testing.T) { 214// if testing.Short() { 215// t.Skip("skipping test in short mode.") 216// } 217// ... 218// } 219// 220// The Skip method of *T can be used in a fuzz target if the input is invalid, 221// but should not be considered a failing input. For example: 222// 223// func FuzzJSONMarshalling(f *testing.F) { 224// f.Fuzz(func(t *testing.T, b []byte) { 225// var v interface{} 226// if err := json.Unmarshal(b, &v); err != nil { 227// t.Skip() 228// } 229// if _, err := json.Marshal(v); err != nil { 230// t.Error("Marshal: %v", err) 231// } 232// }) 233// } 234// 235// Subtests and Sub-benchmarks 236// 237// The Run methods of T and B allow defining subtests and sub-benchmarks, 238// without having to define separate functions for each. This enables uses 239// like table-driven benchmarks and creating hierarchical tests. 240// It also provides a way to share common setup and tear-down code: 241// 242// func TestFoo(t *testing.T) { 243// // <setup code> 244// t.Run("A=1", func(t *testing.T) { ... }) 245// t.Run("A=2", func(t *testing.T) { ... }) 246// t.Run("B=1", func(t *testing.T) { ... }) 247// // <tear-down code> 248// } 249// 250// Each subtest and sub-benchmark has a unique name: the combination of the name 251// of the top-level test and the sequence of names passed to Run, separated by 252// slashes, with an optional trailing sequence number for disambiguation. 253// 254// The argument to the -run, -bench, and -fuzz command-line flags is an unanchored regular 255// expression that matches the test's name. For tests with multiple slash-separated 256// elements, such as subtests, the argument is itself slash-separated, with 257// expressions matching each name element in turn. Because it is unanchored, an 258// empty expression matches any string. 259// For example, using "matching" to mean "whose name contains": 260// 261// go test -run '' # Run all tests. 262// go test -run Foo # Run top-level tests matching "Foo", such as "TestFooBar". 263// go test -run Foo/A= # For top-level tests matching "Foo", run subtests matching "A=". 264// go test -run /A=1 # For all top-level tests, run subtests matching "A=1". 265// go test -fuzz FuzzFoo # Fuzz the target matching "FuzzFoo" 266// 267// The -run argument can also be used to run a specific value in the seed 268// corpus, for debugging. For example: 269// go test -run=FuzzFoo/9ddb952d9814 270// 271// The -fuzz and -run flags can both be set, in order to fuzz a target but 272// skip the execution of all other tests. 273// 274// Subtests can also be used to control parallelism. A parent test will only 275// complete once all of its subtests complete. In this example, all tests are 276// run in parallel with each other, and only with each other, regardless of 277// other top-level tests that may be defined: 278// 279// func TestGroupedParallel(t *testing.T) { 280// for _, tc := range tests { 281// tc := tc // capture range variable 282// t.Run(tc.Name, func(t *testing.T) { 283// t.Parallel() 284// ... 285// }) 286// } 287// } 288// 289// The race detector kills the program if it exceeds 8128 concurrent goroutines, 290// so use care when running parallel tests with the -race flag set. 291// 292// Run does not return until parallel subtests have completed, providing a way 293// to clean up after a group of parallel tests: 294// 295// func TestTeardownParallel(t *testing.T) { 296// // This Run will not return until the parallel tests finish. 297// t.Run("group", func(t *testing.T) { 298// t.Run("Test1", parallelTest1) 299// t.Run("Test2", parallelTest2) 300// t.Run("Test3", parallelTest3) 301// }) 302// // <tear-down code> 303// } 304// 305// Main 306// 307// It is sometimes necessary for a test or benchmark program to do extra setup or teardown 308// before or after it executes. It is also sometimes necessary to control 309// which code runs on the main thread. To support these and other cases, 310// if a test file contains a function: 311// 312// func TestMain(m *testing.M) 313// 314// then the generated test will call TestMain(m) instead of running the tests or benchmarks 315// directly. TestMain runs in the main goroutine and can do whatever setup 316// and teardown is necessary around a call to m.Run. m.Run will return an exit 317// code that may be passed to os.Exit. If TestMain returns, the test wrapper 318// will pass the result of m.Run to os.Exit itself. 319// 320// When TestMain is called, flag.Parse has not been run. If TestMain depends on 321// command-line flags, including those of the testing package, it should call 322// flag.Parse explicitly. Command line flags are always parsed by the time test 323// or benchmark functions run. 324// 325// A simple implementation of TestMain is: 326// 327// func TestMain(m *testing.M) { 328// // call flag.Parse() here if TestMain uses flags 329// os.Exit(m.Run()) 330// } 331// 332// TestMain is a low-level primitive and should not be necessary for casual 333// testing needs, where ordinary test functions suffice. 334package testing 335 336import ( 337 "bytes" 338 "errors" 339 "flag" 340 "fmt" 341 "internal/race" 342 "io" 343 "math/rand" 344 "os" 345 "reflect" 346 "runtime" 347 "runtime/debug" 348 "runtime/trace" 349 "strconv" 350 "strings" 351 "sync" 352 "sync/atomic" 353 "time" 354 "unicode" 355 "unicode/utf8" 356) 357 358var initRan bool 359 360// Init registers testing flags. These flags are automatically registered by 361// the "go test" command before running test functions, so Init is only needed 362// when calling functions such as Benchmark without using "go test". 363// 364// Init has no effect if it was already called. 365func Init() { 366 if initRan { 367 return 368 } 369 initRan = true 370 // The short flag requests that tests run more quickly, but its functionality 371 // is provided by test writers themselves. The testing package is just its 372 // home. The all.bash installation script sets it to make installation more 373 // efficient, but by default the flag is off so a plain "go test" will do a 374 // full test of the package. 375 short = flag.Bool("test.short", false, "run smaller test suite to save time") 376 377 // The failfast flag requests that test execution stop after the first test failure. 378 failFast = flag.Bool("test.failfast", false, "do not start new tests after the first test failure") 379 380 // The directory in which to create profile files and the like. When run from 381 // "go test", the binary always runs in the source directory for the package; 382 // this flag lets "go test" tell the binary to write the files in the directory where 383 // the "go test" command is run. 384 outputDir = flag.String("test.outputdir", "", "write profiles to `dir`") 385 // Report as tests are run; default is silent for success. 386 chatty = flag.Bool("test.v", false, "verbose: print additional output") 387 count = flag.Uint("test.count", 1, "run tests and benchmarks `n` times") 388 coverProfile = flag.String("test.coverprofile", "", "write a coverage profile to `file`") 389 matchList = flag.String("test.list", "", "list tests, examples, and benchmarks matching `regexp` then exit") 390 match = flag.String("test.run", "", "run only tests and examples matching `regexp`") 391 memProfile = flag.String("test.memprofile", "", "write an allocation profile to `file`") 392 memProfileRate = flag.Int("test.memprofilerate", 0, "set memory allocation profiling `rate` (see runtime.MemProfileRate)") 393 cpuProfile = flag.String("test.cpuprofile", "", "write a cpu profile to `file`") 394 blockProfile = flag.String("test.blockprofile", "", "write a goroutine blocking profile to `file`") 395 blockProfileRate = flag.Int("test.blockprofilerate", 1, "set blocking profile `rate` (see runtime.SetBlockProfileRate)") 396 mutexProfile = flag.String("test.mutexprofile", "", "write a mutex contention profile to the named file after execution") 397 mutexProfileFraction = flag.Int("test.mutexprofilefraction", 1, "if >= 0, calls runtime.SetMutexProfileFraction()") 398 panicOnExit0 = flag.Bool("test.paniconexit0", false, "panic on call to os.Exit(0)") 399 traceFile = flag.String("test.trace", "", "write an execution trace to `file`") 400 timeout = flag.Duration("test.timeout", 0, "panic test binary after duration `d` (default 0, timeout disabled)") 401 cpuListStr = flag.String("test.cpu", "", "comma-separated `list` of cpu counts to run each test with") 402 parallel = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "run at most `n` tests in parallel") 403 testlog = flag.String("test.testlogfile", "", "write test action log to `file` (for use only by cmd/go)") 404 shuffle = flag.String("test.shuffle", "off", "randomize the execution order of tests and benchmarks") 405 406 initBenchmarkFlags() 407 initFuzzFlags() 408} 409 410var ( 411 // Flags, registered during Init. 412 short *bool 413 failFast *bool 414 outputDir *string 415 chatty *bool 416 count *uint 417 coverProfile *string 418 matchList *string 419 match *string 420 memProfile *string 421 memProfileRate *int 422 cpuProfile *string 423 blockProfile *string 424 blockProfileRate *int 425 mutexProfile *string 426 mutexProfileFraction *int 427 panicOnExit0 *bool 428 traceFile *string 429 timeout *time.Duration 430 cpuListStr *string 431 parallel *int 432 shuffle *string 433 testlog *string 434 435 haveExamples bool // are there examples? 436 437 cpuList []int 438 testlogFile *os.File 439 440 numFailed uint32 // number of test failures 441) 442 443type chattyPrinter struct { 444 w io.Writer 445 lastNameMu sync.Mutex // guards lastName 446 lastName string // last printed test name in chatty mode 447} 448 449func newChattyPrinter(w io.Writer) *chattyPrinter { 450 return &chattyPrinter{w: w} 451} 452 453// Updatef prints a message about the status of the named test to w. 454// 455// The formatted message must include the test name itself. 456func (p *chattyPrinter) Updatef(testName, format string, args ...any) { 457 p.lastNameMu.Lock() 458 defer p.lastNameMu.Unlock() 459 460 // Since the message already implies an association with a specific new test, 461 // we don't need to check what the old test name was or log an extra CONT line 462 // for it. (We're updating it anyway, and the current message already includes 463 // the test name.) 464 p.lastName = testName 465 fmt.Fprintf(p.w, format, args...) 466} 467 468// Printf prints a message, generated by the named test, that does not 469// necessarily mention that tests's name itself. 470func (p *chattyPrinter) Printf(testName, format string, args ...any) { 471 p.lastNameMu.Lock() 472 defer p.lastNameMu.Unlock() 473 474 if p.lastName == "" { 475 p.lastName = testName 476 } else if p.lastName != testName { 477 fmt.Fprintf(p.w, "=== CONT %s\n", testName) 478 p.lastName = testName 479 } 480 481 fmt.Fprintf(p.w, format, args...) 482} 483 484// The maximum number of stack frames to go through when skipping helper functions for 485// the purpose of decorating log messages. 486const maxStackLen = 50 487 488// common holds the elements common between T and B and 489// captures common methods such as Errorf. 490type common struct { 491 mu sync.RWMutex // guards this group of fields 492 output []byte // Output generated by test or benchmark. 493 w io.Writer // For flushToParent. 494 ran bool // Test or benchmark (or one of its subtests) was executed. 495 failed bool // Test or benchmark has failed. 496 skipped bool // Test or benchmark has been skipped. 497 done bool // Test is finished and all subtests have completed. 498 helperPCs map[uintptr]struct{} // functions to be skipped when writing file/line info 499 helperNames map[string]struct{} // helperPCs converted to function names 500 cleanups []func() // optional functions to be called at the end of the test 501 cleanupName string // Name of the cleanup function. 502 cleanupPc []uintptr // The stack trace at the point where Cleanup was called. 503 finished bool // Test function has completed. 504 inFuzzFn bool // Whether the fuzz target, if this is one, is running. 505 506 chatty *chattyPrinter // A copy of chattyPrinter, if the chatty flag is set. 507 bench bool // Whether the current test is a benchmark. 508 hasSub int32 // Written atomically. 509 raceErrors int // Number of races detected during test. 510 runner string // Function name of tRunner running the test. 511 512 parent *common 513 level int // Nesting depth of test or benchmark. 514 creator []uintptr // If level > 0, the stack trace at the point where the parent called t.Run. 515 name string // Name of test or benchmark. 516 start time.Time // Time test or benchmark started 517 duration time.Duration 518 barrier chan bool // To signal parallel subtests they may start. Nil when T.Parallel is not present (B) or not usable (when fuzzing). 519 signal chan bool // To signal a test is done. 520 sub []*T // Queue of subtests to be run in parallel. 521 522 tempDirMu sync.Mutex 523 tempDir string 524 tempDirErr error 525 tempDirSeq int32 526} 527 528// Short reports whether the -test.short flag is set. 529func Short() bool { 530 if short == nil { 531 panic("testing: Short called before Init") 532 } 533 // Catch code that calls this from TestMain without first calling flag.Parse. 534 if !flag.Parsed() { 535 panic("testing: Short called before Parse") 536 } 537 538 return *short 539} 540 541// CoverMode reports what the test coverage mode is set to. The 542// values are "set", "count", or "atomic". The return value will be 543// empty if test coverage is not enabled. 544func CoverMode() string { 545 return cover.Mode 546} 547 548// Verbose reports whether the -test.v flag is set. 549func Verbose() bool { 550 // Same as in Short. 551 if chatty == nil { 552 panic("testing: Verbose called before Init") 553 } 554 if !flag.Parsed() { 555 panic("testing: Verbose called before Parse") 556 } 557 return *chatty 558} 559 560func (c *common) checkFuzzFn(name string) { 561 if c.inFuzzFn { 562 panic(fmt.Sprintf("testing: f.%s was called inside the fuzz target, use t.%s instead", name, name)) 563 } 564} 565 566// frameSkip searches, starting after skip frames, for the first caller frame 567// in a function not marked as a helper and returns that frame. 568// The search stops if it finds a tRunner function that 569// was the entry point into the test and the test is not a subtest. 570// This function must be called with c.mu held. 571func (c *common) frameSkip(skip int) runtime.Frame { 572 // If the search continues into the parent test, we'll have to hold 573 // its mu temporarily. If we then return, we need to unlock it. 574 shouldUnlock := false 575 defer func() { 576 if shouldUnlock { 577 c.mu.Unlock() 578 } 579 }() 580 var pc [maxStackLen]uintptr 581 // Skip two extra frames to account for this function 582 // and runtime.Callers itself. 583 n := runtime.Callers(skip+2, pc[:]) 584 if n == 0 { 585 panic("testing: zero callers found") 586 } 587 frames := runtime.CallersFrames(pc[:n]) 588 var firstFrame, prevFrame, frame runtime.Frame 589 for more := true; more; prevFrame = frame { 590 frame, more = frames.Next() 591 if frame.Function == "runtime.gopanic" { 592 continue 593 } 594 if frame.Function == c.cleanupName { 595 frames = runtime.CallersFrames(c.cleanupPc) 596 continue 597 } 598 if firstFrame.PC == 0 { 599 firstFrame = frame 600 } 601 if frame.Function == c.runner { 602 // We've gone up all the way to the tRunner calling 603 // the test function (so the user must have 604 // called tb.Helper from inside that test function). 605 // If this is a top-level test, only skip up to the test function itself. 606 // If we're in a subtest, continue searching in the parent test, 607 // starting from the point of the call to Run which created this subtest. 608 if c.level > 1 { 609 frames = runtime.CallersFrames(c.creator) 610 parent := c.parent 611 // We're no longer looking at the current c after this point, 612 // so we should unlock its mu, unless it's the original receiver, 613 // in which case our caller doesn't expect us to do that. 614 if shouldUnlock { 615 c.mu.Unlock() 616 } 617 c = parent 618 // Remember to unlock c.mu when we no longer need it, either 619 // because we went up another nesting level, or because we 620 // returned. 621 shouldUnlock = true 622 c.mu.Lock() 623 continue 624 } 625 return prevFrame 626 } 627 // If more helper PCs have been added since we last did the conversion 628 if c.helperNames == nil { 629 c.helperNames = make(map[string]struct{}) 630 for pc := range c.helperPCs { 631 c.helperNames[pcToName(pc)] = struct{}{} 632 } 633 } 634 if _, ok := c.helperNames[frame.Function]; !ok { 635 // Found a frame that wasn't inside a helper function. 636 return frame 637 } 638 } 639 return firstFrame 640} 641 642// decorate prefixes the string with the file and line of the call site 643// and inserts the final newline if needed and indentation spaces for formatting. 644// This function must be called with c.mu held. 645func (c *common) decorate(s string, skip int) string { 646 frame := c.frameSkip(skip) 647 file := frame.File 648 line := frame.Line 649 if file != "" { 650 // Truncate file name at last file name separator. 651 if index := strings.LastIndex(file, "/"); index >= 0 { 652 file = file[index+1:] 653 } else if index = strings.LastIndex(file, "\\"); index >= 0 { 654 file = file[index+1:] 655 } 656 } else { 657 file = "???" 658 } 659 if line == 0 { 660 line = 1 661 } 662 buf := new(strings.Builder) 663 // Every line is indented at least 4 spaces. 664 buf.WriteString(" ") 665 fmt.Fprintf(buf, "%s:%d: ", file, line) 666 lines := strings.Split(s, "\n") 667 if l := len(lines); l > 1 && lines[l-1] == "" { 668 lines = lines[:l-1] 669 } 670 for i, line := range lines { 671 if i > 0 { 672 // Second and subsequent lines are indented an additional 4 spaces. 673 buf.WriteString("\n ") 674 } 675 buf.WriteString(line) 676 } 677 buf.WriteByte('\n') 678 return buf.String() 679} 680 681// flushToParent writes c.output to the parent after first writing the header 682// with the given format and arguments. 683func (c *common) flushToParent(testName, format string, args ...any) { 684 p := c.parent 685 p.mu.Lock() 686 defer p.mu.Unlock() 687 688 c.mu.Lock() 689 defer c.mu.Unlock() 690 691 if len(c.output) > 0 { 692 format += "%s" 693 args = append(args[:len(args):len(args)], c.output) 694 c.output = c.output[:0] // but why? 695 } 696 697 if c.chatty != nil && p.w == c.chatty.w { 698 // We're flushing to the actual output, so track that this output is 699 // associated with a specific test (and, specifically, that the next output 700 // is *not* associated with that test). 701 // 702 // Moreover, if c.output is non-empty it is important that this write be 703 // atomic with respect to the output of other tests, so that we don't end up 704 // with confusing '=== CONT' lines in the middle of our '--- PASS' block. 705 // Neither humans nor cmd/test2json can parse those easily. 706 // (See https://golang.org/issue/40771.) 707 c.chatty.Updatef(testName, format, args...) 708 } else { 709 // We're flushing to the output buffer of the parent test, which will 710 // itself follow a test-name header when it is finally flushed to stdout. 711 fmt.Fprintf(p.w, format, args...) 712 } 713} 714 715type indenter struct { 716 c *common 717} 718 719func (w indenter) Write(b []byte) (n int, err error) { 720 n = len(b) 721 for len(b) > 0 { 722 end := bytes.IndexByte(b, '\n') 723 if end == -1 { 724 end = len(b) 725 } else { 726 end++ 727 } 728 // An indent of 4 spaces will neatly align the dashes with the status 729 // indicator of the parent. 730 const indent = " " 731 w.c.output = append(w.c.output, indent...) 732 w.c.output = append(w.c.output, b[:end]...) 733 b = b[end:] 734 } 735 return 736} 737 738// fmtDuration returns a string representing d in the form "87.00s". 739func fmtDuration(d time.Duration) string { 740 return fmt.Sprintf("%.2fs", d.Seconds()) 741} 742 743// TB is the interface common to T, B, and F. 744type TB interface { 745 Cleanup(func()) 746 Error(args ...any) 747 Errorf(format string, args ...any) 748 Fail() 749 FailNow() 750 Failed() bool 751 Fatal(args ...any) 752 Fatalf(format string, args ...any) 753 Helper() 754 Log(args ...any) 755 Logf(format string, args ...any) 756 Name() string 757 Setenv(key, value string) 758 Skip(args ...any) 759 SkipNow() 760 Skipf(format string, args ...any) 761 Skipped() bool 762 TempDir() string 763 764 // A private method to prevent users implementing the 765 // interface and so future additions to it will not 766 // violate Go 1 compatibility. 767 private() 768} 769 770var _ TB = (*T)(nil) 771var _ TB = (*B)(nil) 772 773// T is a type passed to Test functions to manage test state and support formatted test logs. 774// 775// A test ends when its Test function returns or calls any of the methods 776// FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as 777// the Parallel method, must be called only from the goroutine running the 778// Test function. 779// 780// The other reporting methods, such as the variations of Log and Error, 781// may be called simultaneously from multiple goroutines. 782type T struct { 783 common 784 isParallel bool 785 isEnvSet bool 786 context *testContext // For running tests and subtests. 787} 788 789func (c *common) private() {} 790 791// Name returns the name of the running (sub-) test or benchmark. 792// 793// The name will include the name of the test along with the names of 794// any nested sub-tests. If two sibling sub-tests have the same name, 795// Name will append a suffix to guarantee the returned name is unique. 796func (c *common) Name() string { 797 return c.name 798} 799 800func (c *common) setRan() { 801 if c.parent != nil { 802 c.parent.setRan() 803 } 804 c.mu.Lock() 805 defer c.mu.Unlock() 806 c.ran = true 807} 808 809// Fail marks the function as having failed but continues execution. 810func (c *common) Fail() { 811 if c.parent != nil { 812 c.parent.Fail() 813 } 814 c.mu.Lock() 815 defer c.mu.Unlock() 816 // c.done needs to be locked to synchronize checks to c.done in parent tests. 817 if c.done { 818 panic("Fail in goroutine after " + c.name + " has completed") 819 } 820 c.failed = true 821} 822 823// Failed reports whether the function has failed. 824func (c *common) Failed() bool { 825 c.mu.RLock() 826 failed := c.failed 827 c.mu.RUnlock() 828 return failed || c.raceErrors+race.Errors() > 0 829} 830 831// FailNow marks the function as having failed and stops its execution 832// by calling runtime.Goexit (which then runs all deferred calls in the 833// current goroutine). 834// Execution will continue at the next test or benchmark. 835// FailNow must be called from the goroutine running the 836// test or benchmark function, not from other goroutines 837// created during the test. Calling FailNow does not stop 838// those other goroutines. 839func (c *common) FailNow() { 840 c.checkFuzzFn("FailNow") 841 c.Fail() 842 843 // Calling runtime.Goexit will exit the goroutine, which 844 // will run the deferred functions in this goroutine, 845 // which will eventually run the deferred lines in tRunner, 846 // which will signal to the test loop that this test is done. 847 // 848 // A previous version of this code said: 849 // 850 // c.duration = ... 851 // c.signal <- c.self 852 // runtime.Goexit() 853 // 854 // This previous version duplicated code (those lines are in 855 // tRunner no matter what), but worse the goroutine teardown 856 // implicit in runtime.Goexit was not guaranteed to complete 857 // before the test exited. If a test deferred an important cleanup 858 // function (like removing temporary files), there was no guarantee 859 // it would run on a test failure. Because we send on c.signal during 860 // a top-of-stack deferred function now, we know that the send 861 // only happens after any other stacked defers have completed. 862 c.mu.Lock() 863 c.finished = true 864 c.mu.Unlock() 865 runtime.Goexit() 866} 867 868// log generates the output. It's always at the same stack depth. 869func (c *common) log(s string) { 870 c.logDepth(s, 3) // logDepth + log + public function 871} 872 873// logDepth generates the output at an arbitrary stack depth. 874func (c *common) logDepth(s string, depth int) { 875 c.mu.Lock() 876 defer c.mu.Unlock() 877 if c.done { 878 // This test has already finished. Try and log this message 879 // with our parent. If we don't have a parent, panic. 880 for parent := c.parent; parent != nil; parent = parent.parent { 881 parent.mu.Lock() 882 defer parent.mu.Unlock() 883 if !parent.done { 884 parent.output = append(parent.output, parent.decorate(s, depth+1)...) 885 return 886 } 887 } 888 panic("Log in goroutine after " + c.name + " has completed: " + s) 889 } else { 890 if c.chatty != nil { 891 if c.bench { 892 // Benchmarks don't print === CONT, so we should skip the test 893 // printer and just print straight to stdout. 894 fmt.Print(c.decorate(s, depth+1)) 895 } else { 896 c.chatty.Printf(c.name, "%s", c.decorate(s, depth+1)) 897 } 898 899 return 900 } 901 c.output = append(c.output, c.decorate(s, depth+1)...) 902 } 903} 904 905// Log formats its arguments using default formatting, analogous to Println, 906// and records the text in the error log. For tests, the text will be printed only if 907// the test fails or the -test.v flag is set. For benchmarks, the text is always 908// printed to avoid having performance depend on the value of the -test.v flag. 909func (c *common) Log(args ...any) { 910 c.checkFuzzFn("Log") 911 c.log(fmt.Sprintln(args...)) 912} 913 914// Logf formats its arguments according to the format, analogous to Printf, and 915// records the text in the error log. A final newline is added if not provided. For 916// tests, the text will be printed only if the test fails or the -test.v flag is 917// set. For benchmarks, the text is always printed to avoid having performance 918// depend on the value of the -test.v flag. 919func (c *common) Logf(format string, args ...any) { 920 c.checkFuzzFn("Logf") 921 c.log(fmt.Sprintf(format, args...)) 922} 923 924// Error is equivalent to Log followed by Fail. 925func (c *common) Error(args ...any) { 926 c.checkFuzzFn("Error") 927 c.log(fmt.Sprintln(args...)) 928 c.Fail() 929} 930 931// Errorf is equivalent to Logf followed by Fail. 932func (c *common) Errorf(format string, args ...any) { 933 c.checkFuzzFn("Errorf") 934 c.log(fmt.Sprintf(format, args...)) 935 c.Fail() 936} 937 938// Fatal is equivalent to Log followed by FailNow. 939func (c *common) Fatal(args ...any) { 940 c.checkFuzzFn("Fatal") 941 c.log(fmt.Sprintln(args...)) 942 c.FailNow() 943} 944 945// Fatalf is equivalent to Logf followed by FailNow. 946func (c *common) Fatalf(format string, args ...any) { 947 c.checkFuzzFn("Fatalf") 948 c.log(fmt.Sprintf(format, args...)) 949 c.FailNow() 950} 951 952// Skip is equivalent to Log followed by SkipNow. 953func (c *common) Skip(args ...any) { 954 c.checkFuzzFn("Skip") 955 c.log(fmt.Sprintln(args...)) 956 c.SkipNow() 957} 958 959// Skipf is equivalent to Logf followed by SkipNow. 960func (c *common) Skipf(format string, args ...any) { 961 c.checkFuzzFn("Skipf") 962 c.log(fmt.Sprintf(format, args...)) 963 c.SkipNow() 964} 965 966// SkipNow marks the test as having been skipped and stops its execution 967// by calling runtime.Goexit. 968// If a test fails (see Error, Errorf, Fail) and is then skipped, 969// it is still considered to have failed. 970// Execution will continue at the next test or benchmark. See also FailNow. 971// SkipNow must be called from the goroutine running the test, not from 972// other goroutines created during the test. Calling SkipNow does not stop 973// those other goroutines. 974func (c *common) SkipNow() { 975 c.checkFuzzFn("SkipNow") 976 c.mu.Lock() 977 c.skipped = true 978 c.finished = true 979 c.mu.Unlock() 980 runtime.Goexit() 981} 982 983// Skipped reports whether the test was skipped. 984func (c *common) Skipped() bool { 985 c.mu.RLock() 986 defer c.mu.RUnlock() 987 return c.skipped 988} 989 990// Helper marks the calling function as a test helper function. 991// When printing file and line information, that function will be skipped. 992// Helper may be called simultaneously from multiple goroutines. 993func (c *common) Helper() { 994 c.mu.Lock() 995 defer c.mu.Unlock() 996 if c.helperPCs == nil { 997 c.helperPCs = make(map[uintptr]struct{}) 998 } 999 // repeating code from callerName here to save walking a stack frame 1000 var pc [1]uintptr 1001 n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper 1002 if n == 0 { 1003 panic("testing: zero callers found") 1004 } 1005 if _, found := c.helperPCs[pc[0]]; !found { 1006 c.helperPCs[pc[0]] = struct{}{} 1007 c.helperNames = nil // map will be recreated next time it is needed 1008 } 1009} 1010 1011// Cleanup registers a function to be called when the test (or subtest) and all its 1012// subtests complete. Cleanup functions will be called in last added, 1013// first called order. 1014func (c *common) Cleanup(f func()) { 1015 c.checkFuzzFn("Cleanup") 1016 var pc [maxStackLen]uintptr 1017 // Skip two extra frames to account for this function and runtime.Callers itself. 1018 n := runtime.Callers(2, pc[:]) 1019 cleanupPc := pc[:n] 1020 1021 fn := func() { 1022 defer func() { 1023 c.mu.Lock() 1024 defer c.mu.Unlock() 1025 c.cleanupName = "" 1026 c.cleanupPc = nil 1027 }() 1028 1029 name := callerName(0) 1030 c.mu.Lock() 1031 c.cleanupName = name 1032 c.cleanupPc = cleanupPc 1033 c.mu.Unlock() 1034 1035 f() 1036 } 1037 1038 c.mu.Lock() 1039 defer c.mu.Unlock() 1040 c.cleanups = append(c.cleanups, fn) 1041} 1042 1043// TempDir returns a temporary directory for the test to use. 1044// The directory is automatically removed by Cleanup when the test and 1045// all its subtests complete. 1046// Each subsequent call to t.TempDir returns a unique directory; 1047// if the directory creation fails, TempDir terminates the test by calling Fatal. 1048func (c *common) TempDir() string { 1049 c.checkFuzzFn("TempDir") 1050 // Use a single parent directory for all the temporary directories 1051 // created by a test, each numbered sequentially. 1052 c.tempDirMu.Lock() 1053 var nonExistent bool 1054 if c.tempDir == "" { // Usually the case with js/wasm 1055 nonExistent = true 1056 } else { 1057 _, err := os.Stat(c.tempDir) 1058 nonExistent = os.IsNotExist(err) 1059 if err != nil && !nonExistent { 1060 c.Fatalf("TempDir: %v", err) 1061 } 1062 } 1063 1064 if nonExistent { 1065 c.Helper() 1066 1067 // Drop unusual characters (such as path separators or 1068 // characters interacting with globs) from the directory name to 1069 // avoid surprising os.MkdirTemp behavior. 1070 mapper := func(r rune) rune { 1071 if r < utf8.RuneSelf { 1072 const allowed = "!#$%&()+,-.=@^_{}~ " 1073 if '0' <= r && r <= '9' || 1074 'a' <= r && r <= 'z' || 1075 'A' <= r && r <= 'Z' { 1076 return r 1077 } 1078 if strings.ContainsRune(allowed, r) { 1079 return r 1080 } 1081 } else if unicode.IsLetter(r) || unicode.IsNumber(r) { 1082 return r 1083 } 1084 return -1 1085 } 1086 pattern := strings.Map(mapper, c.Name()) 1087 c.tempDir, c.tempDirErr = os.MkdirTemp("", pattern) 1088 if c.tempDirErr == nil { 1089 c.Cleanup(func() { 1090 if err := os.RemoveAll(c.tempDir); err != nil { 1091 c.Errorf("TempDir RemoveAll cleanup: %v", err) 1092 } 1093 }) 1094 } 1095 } 1096 c.tempDirMu.Unlock() 1097 1098 if c.tempDirErr != nil { 1099 c.Fatalf("TempDir: %v", c.tempDirErr) 1100 } 1101 seq := atomic.AddInt32(&c.tempDirSeq, 1) 1102 dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq) 1103 if err := os.Mkdir(dir, 0777); err != nil { 1104 c.Fatalf("TempDir: %v", err) 1105 } 1106 return dir 1107} 1108 1109// Setenv calls os.Setenv(key, value) and uses Cleanup to 1110// restore the environment variable to its original value 1111// after the test. 1112// 1113// This cannot be used in parallel tests. 1114func (c *common) Setenv(key, value string) { 1115 c.checkFuzzFn("Setenv") 1116 prevValue, ok := os.LookupEnv(key) 1117 1118 if err := os.Setenv(key, value); err != nil { 1119 c.Fatalf("cannot set environment variable: %v", err) 1120 } 1121 1122 if ok { 1123 c.Cleanup(func() { 1124 os.Setenv(key, prevValue) 1125 }) 1126 } else { 1127 c.Cleanup(func() { 1128 os.Unsetenv(key) 1129 }) 1130 } 1131} 1132 1133// panicHanding is an argument to runCleanup. 1134type panicHandling int 1135 1136const ( 1137 normalPanic panicHandling = iota 1138 recoverAndReturnPanic 1139) 1140 1141// runCleanup is called at the end of the test. 1142// If catchPanic is true, this will catch panics, and return the recovered 1143// value if any. 1144func (c *common) runCleanup(ph panicHandling) (panicVal any) { 1145 if ph == recoverAndReturnPanic { 1146 defer func() { 1147 panicVal = recover() 1148 }() 1149 } 1150 1151 // Make sure that if a cleanup function panics, 1152 // we still run the remaining cleanup functions. 1153 defer func() { 1154 c.mu.Lock() 1155 recur := len(c.cleanups) > 0 1156 c.mu.Unlock() 1157 if recur { 1158 c.runCleanup(normalPanic) 1159 } 1160 }() 1161 1162 for { 1163 var cleanup func() 1164 c.mu.Lock() 1165 if len(c.cleanups) > 0 { 1166 last := len(c.cleanups) - 1 1167 cleanup = c.cleanups[last] 1168 c.cleanups = c.cleanups[:last] 1169 } 1170 c.mu.Unlock() 1171 if cleanup == nil { 1172 return nil 1173 } 1174 cleanup() 1175 } 1176} 1177 1178// callerName gives the function name (qualified with a package path) 1179// for the caller after skip frames (where 0 means the current function). 1180func callerName(skip int) string { 1181 var pc [1]uintptr 1182 n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName 1183 if n == 0 { 1184 panic("testing: zero callers found") 1185 } 1186 return pcToName(pc[0]) 1187} 1188 1189func pcToName(pc uintptr) string { 1190 pcs := []uintptr{pc} 1191 frames := runtime.CallersFrames(pcs) 1192 frame, _ := frames.Next() 1193 return frame.Function 1194} 1195 1196// Parallel signals that this test is to be run in parallel with (and only with) 1197// other parallel tests. When a test is run multiple times due to use of 1198// -test.count or -test.cpu, multiple instances of a single test never run in 1199// parallel with each other. 1200func (t *T) Parallel() { 1201 if t.isParallel { 1202 panic("testing: t.Parallel called multiple times") 1203 } 1204 if t.isEnvSet { 1205 panic("testing: t.Parallel called after t.Setenv; cannot set environment variables in parallel tests") 1206 } 1207 t.isParallel = true 1208 if t.parent.barrier == nil { 1209 // T.Parallel has no effect when fuzzing. 1210 // Multiple processes may run in parallel, but only one input can run at a 1211 // time per process so we can attribute crashes to specific inputs. 1212 return 1213 } 1214 1215 // We don't want to include the time we spend waiting for serial tests 1216 // in the test duration. Record the elapsed time thus far and reset the 1217 // timer afterwards. 1218 t.duration += time.Since(t.start) 1219 1220 // Add to the list of tests to be released by the parent. 1221 t.parent.sub = append(t.parent.sub, t) 1222 t.raceErrors += race.Errors() 1223 1224 if t.chatty != nil { 1225 // Unfortunately, even though PAUSE indicates that the named test is *no 1226 // longer* running, cmd/test2json interprets it as changing the active test 1227 // for the purpose of log parsing. We could fix cmd/test2json, but that 1228 // won't fix existing deployments of third-party tools that already shell 1229 // out to older builds of cmd/test2json — so merely fixing cmd/test2json 1230 // isn't enough for now. 1231 t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name) 1232 } 1233 1234 t.signal <- true // Release calling test. 1235 <-t.parent.barrier // Wait for the parent test to complete. 1236 t.context.waitParallel() 1237 1238 if t.chatty != nil { 1239 t.chatty.Updatef(t.name, "=== CONT %s\n", t.name) 1240 } 1241 1242 t.start = time.Now() 1243 t.raceErrors += -race.Errors() 1244} 1245 1246// Setenv calls os.Setenv(key, value) and uses Cleanup to 1247// restore the environment variable to its original value 1248// after the test. 1249// 1250// This cannot be used in parallel tests. 1251func (t *T) Setenv(key, value string) { 1252 if t.isParallel { 1253 panic("testing: t.Setenv called after t.Parallel; cannot set environment variables in parallel tests") 1254 } 1255 1256 t.isEnvSet = true 1257 1258 t.common.Setenv(key, value) 1259} 1260 1261// InternalTest is an internal type but exported because it is cross-package; 1262// it is part of the implementation of the "go test" command. 1263type InternalTest struct { 1264 Name string 1265 F func(*T) 1266} 1267 1268var errNilPanicOrGoexit = errors.New("test executed panic(nil) or runtime.Goexit") 1269 1270func tRunner(t *T, fn func(t *T)) { 1271 t.runner = callerName(0) 1272 1273 // When this goroutine is done, either because fn(t) 1274 // returned normally or because a test failure triggered 1275 // a call to runtime.Goexit, record the duration and send 1276 // a signal saying that the test is done. 1277 defer func() { 1278 if t.Failed() { 1279 atomic.AddUint32(&numFailed, 1) 1280 } 1281 1282 if t.raceErrors+race.Errors() > 0 { 1283 t.Errorf("race detected during execution of test") 1284 } 1285 1286 // Check if the test panicked or Goexited inappropriately. 1287 // 1288 // If this happens in a normal test, print output but continue panicking. 1289 // tRunner is called in its own goroutine, so this terminates the process. 1290 // 1291 // If this happens while fuzzing, recover from the panic and treat it like a 1292 // normal failure. It's important that the process keeps running in order to 1293 // find short inputs that cause panics. 1294 err := recover() 1295 signal := true 1296 1297 t.mu.RLock() 1298 finished := t.finished 1299 t.mu.RUnlock() 1300 if !finished && err == nil { 1301 err = errNilPanicOrGoexit 1302 for p := t.parent; p != nil; p = p.parent { 1303 p.mu.RLock() 1304 finished = p.finished 1305 p.mu.RUnlock() 1306 if finished { 1307 t.Errorf("%v: subtest may have called FailNow on a parent test", err) 1308 err = nil 1309 signal = false 1310 break 1311 } 1312 } 1313 } 1314 1315 if err != nil && t.context.isFuzzing { 1316 prefix := "panic: " 1317 if err == errNilPanicOrGoexit { 1318 prefix = "" 1319 } 1320 t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack())) 1321 t.mu.Lock() 1322 t.finished = true 1323 t.mu.Unlock() 1324 err = nil 1325 } 1326 1327 // Use a deferred call to ensure that we report that the test is 1328 // complete even if a cleanup function calls t.FailNow. See issue 41355. 1329 didPanic := false 1330 defer func() { 1331 if didPanic { 1332 return 1333 } 1334 if err != nil { 1335 panic(err) 1336 } 1337 // Only report that the test is complete if it doesn't panic, 1338 // as otherwise the test binary can exit before the panic is 1339 // reported to the user. See issue 41479. 1340 t.signal <- signal 1341 }() 1342 1343 doPanic := func(err any) { 1344 t.Fail() 1345 if r := t.runCleanup(recoverAndReturnPanic); r != nil { 1346 t.Logf("cleanup panicked with %v", r) 1347 } 1348 // Flush the output log up to the root before dying. 1349 for root := &t.common; root.parent != nil; root = root.parent { 1350 root.mu.Lock() 1351 root.duration += time.Since(root.start) 1352 d := root.duration 1353 root.mu.Unlock() 1354 root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d)) 1355 if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil { 1356 fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r) 1357 } 1358 } 1359 didPanic = true 1360 panic(err) 1361 } 1362 if err != nil { 1363 doPanic(err) 1364 } 1365 1366 t.duration += time.Since(t.start) 1367 1368 if len(t.sub) > 0 { 1369 // Run parallel subtests. 1370 // Decrease the running count for this test. 1371 t.context.release() 1372 // Release the parallel subtests. 1373 close(t.barrier) 1374 // Wait for subtests to complete. 1375 for _, sub := range t.sub { 1376 <-sub.signal 1377 } 1378 cleanupStart := time.Now() 1379 err := t.runCleanup(recoverAndReturnPanic) 1380 t.duration += time.Since(cleanupStart) 1381 if err != nil { 1382 doPanic(err) 1383 } 1384 if !t.isParallel { 1385 // Reacquire the count for sequential tests. See comment in Run. 1386 t.context.waitParallel() 1387 } 1388 } else if t.isParallel { 1389 // Only release the count for this test if it was run as a parallel 1390 // test. See comment in Run method. 1391 t.context.release() 1392 } 1393 t.report() // Report after all subtests have finished. 1394 1395 // Do not lock t.done to allow race detector to detect race in case 1396 // the user does not appropriately synchronize a goroutine. 1397 t.done = true 1398 if t.parent != nil && atomic.LoadInt32(&t.hasSub) == 0 { 1399 t.setRan() 1400 } 1401 }() 1402 defer func() { 1403 if len(t.sub) == 0 { 1404 t.runCleanup(normalPanic) 1405 } 1406 }() 1407 1408 t.start = time.Now() 1409 t.raceErrors = -race.Errors() 1410 fn(t) 1411 1412 // code beyond here will not be executed when FailNow is invoked 1413 t.mu.Lock() 1414 t.finished = true 1415 t.mu.Unlock() 1416} 1417 1418// Run runs f as a subtest of t called name. It runs f in a separate goroutine 1419// and blocks until f returns or calls t.Parallel to become a parallel test. 1420// Run reports whether f succeeded (or at least did not fail before calling t.Parallel). 1421// 1422// Run may be called simultaneously from multiple goroutines, but all such calls 1423// must return before the outer test function for t returns. 1424func (t *T) Run(name string, f func(t *T)) bool { 1425 atomic.StoreInt32(&t.hasSub, 1) 1426 testName, ok, _ := t.context.match.fullName(&t.common, name) 1427 if !ok || shouldFailFast() { 1428 return true 1429 } 1430 // Record the stack trace at the point of this call so that if the subtest 1431 // function - which runs in a separate stack - is marked as a helper, we can 1432 // continue walking the stack into the parent test. 1433 var pc [maxStackLen]uintptr 1434 n := runtime.Callers(2, pc[:]) 1435 t = &T{ 1436 common: common{ 1437 barrier: make(chan bool), 1438 signal: make(chan bool, 1), 1439 name: testName, 1440 parent: &t.common, 1441 level: t.level + 1, 1442 creator: pc[:n], 1443 chatty: t.chatty, 1444 }, 1445 context: t.context, 1446 } 1447 t.w = indenter{&t.common} 1448 1449 if t.chatty != nil { 1450 t.chatty.Updatef(t.name, "=== RUN %s\n", t.name) 1451 } 1452 // Instead of reducing the running count of this test before calling the 1453 // tRunner and increasing it afterwards, we rely on tRunner keeping the 1454 // count correct. This ensures that a sequence of sequential tests runs 1455 // without being preempted, even when their parent is a parallel test. This 1456 // may especially reduce surprises if *parallel == 1. 1457 go tRunner(t, f) 1458 if !<-t.signal { 1459 // At this point, it is likely that FailNow was called on one of the 1460 // parent tests by one of the subtests. Continue aborting up the chain. 1461 runtime.Goexit() 1462 } 1463 return !t.failed 1464} 1465 1466// Deadline reports the time at which the test binary will have 1467// exceeded the timeout specified by the -timeout flag. 1468// 1469// The ok result is false if the -timeout flag indicates “no timeout” (0). 1470func (t *T) Deadline() (deadline time.Time, ok bool) { 1471 deadline = t.context.deadline 1472 return deadline, !deadline.IsZero() 1473} 1474 1475// testContext holds all fields that are common to all tests. This includes 1476// synchronization primitives to run at most *parallel tests. 1477type testContext struct { 1478 match *matcher 1479 deadline time.Time 1480 1481 // isFuzzing is true in the context used when generating random inputs 1482 // for fuzz targets. isFuzzing is false when running normal tests and 1483 // when running fuzz tests as unit tests (without -fuzz or when -fuzz 1484 // does not match). 1485 isFuzzing bool 1486 1487 mu sync.Mutex 1488 1489 // Channel used to signal tests that are ready to be run in parallel. 1490 startParallel chan bool 1491 1492 // running is the number of tests currently running in parallel. 1493 // This does not include tests that are waiting for subtests to complete. 1494 running int 1495 1496 // numWaiting is the number tests waiting to be run in parallel. 1497 numWaiting int 1498 1499 // maxParallel is a copy of the parallel flag. 1500 maxParallel int 1501} 1502 1503func newTestContext(maxParallel int, m *matcher) *testContext { 1504 return &testContext{ 1505 match: m, 1506 startParallel: make(chan bool), 1507 maxParallel: maxParallel, 1508 running: 1, // Set the count to 1 for the main (sequential) test. 1509 } 1510} 1511 1512func (c *testContext) waitParallel() { 1513 c.mu.Lock() 1514 if c.running < c.maxParallel { 1515 c.running++ 1516 c.mu.Unlock() 1517 return 1518 } 1519 c.numWaiting++ 1520 c.mu.Unlock() 1521 <-c.startParallel 1522} 1523 1524func (c *testContext) release() { 1525 c.mu.Lock() 1526 if c.numWaiting == 0 { 1527 c.running-- 1528 c.mu.Unlock() 1529 return 1530 } 1531 c.numWaiting-- 1532 c.mu.Unlock() 1533 c.startParallel <- true // Pick a waiting test to be run. 1534} 1535 1536// No one should be using func Main anymore. 1537// See the doc comment on func Main and use MainStart instead. 1538var errMain = errors.New("testing: unexpected use of func Main") 1539 1540type matchStringOnly func(pat, str string) (bool, error) 1541 1542func (f matchStringOnly) MatchString(pat, str string) (bool, error) { return f(pat, str) } 1543func (f matchStringOnly) StartCPUProfile(w io.Writer) error { return errMain } 1544func (f matchStringOnly) StopCPUProfile() {} 1545func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain } 1546func (f matchStringOnly) ImportPath() string { return "" } 1547func (f matchStringOnly) StartTestLog(io.Writer) {} 1548func (f matchStringOnly) StopTestLog() error { return errMain } 1549func (f matchStringOnly) SetPanicOnExit0(bool) {} 1550func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error { 1551 return errMain 1552} 1553func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain } 1554func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) { 1555 return nil, errMain 1556} 1557func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil } 1558func (f matchStringOnly) ResetCoverage() {} 1559func (f matchStringOnly) SnapshotCoverage() {} 1560 1561// Main is an internal function, part of the implementation of the "go test" command. 1562// It was exported because it is cross-package and predates "internal" packages. 1563// It is no longer used by "go test" but preserved, as much as possible, for other 1564// systems that simulate "go test" using Main, but Main sometimes cannot be updated as 1565// new functionality is added to the testing package. 1566// Systems simulating "go test" should be updated to use MainStart. 1567func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) { 1568 os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run()) 1569} 1570 1571// M is a type passed to a TestMain function to run the actual tests. 1572type M struct { 1573 deps testDeps 1574 tests []InternalTest 1575 benchmarks []InternalBenchmark 1576 fuzzTargets []InternalFuzzTarget 1577 examples []InternalExample 1578 1579 timer *time.Timer 1580 afterOnce sync.Once 1581 1582 numRun int 1583 1584 // value to pass to os.Exit, the outer test func main 1585 // harness calls os.Exit with this code. See #34129. 1586 exitCode int 1587} 1588 1589// testDeps is an internal interface of functionality that is 1590// passed into this package by a test's generated main package. 1591// The canonical implementation of this interface is 1592// testing/internal/testdeps's TestDeps. 1593type testDeps interface { 1594 ImportPath() string 1595 MatchString(pat, str string) (bool, error) 1596 SetPanicOnExit0(bool) 1597 StartCPUProfile(io.Writer) error 1598 StopCPUProfile() 1599 StartTestLog(io.Writer) 1600 StopTestLog() error 1601 WriteProfileTo(string, io.Writer, int) error 1602 CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error 1603 RunFuzzWorker(func(corpusEntry) error) error 1604 ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) 1605 CheckCorpus([]any, []reflect.Type) error 1606 ResetCoverage() 1607 SnapshotCoverage() 1608} 1609 1610// MainStart is meant for use by tests generated by 'go test'. 1611// It is not meant to be called directly and is not subject to the Go 1 compatibility document. 1612// It may change signature from release to release. 1613func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M { 1614 Init() 1615 return &M{ 1616 deps: deps, 1617 tests: tests, 1618 benchmarks: benchmarks, 1619 fuzzTargets: fuzzTargets, 1620 examples: examples, 1621 } 1622} 1623 1624// Run runs the tests. It returns an exit code to pass to os.Exit. 1625func (m *M) Run() (code int) { 1626 defer func() { 1627 code = m.exitCode 1628 }() 1629 1630 // Count the number of calls to m.Run. 1631 // We only ever expected 1, but we didn't enforce that, 1632 // and now there are tests in the wild that call m.Run multiple times. 1633 // Sigh. golang.org/issue/23129. 1634 m.numRun++ 1635 1636 // TestMain may have already called flag.Parse. 1637 if !flag.Parsed() { 1638 flag.Parse() 1639 } 1640 1641 if *parallel < 1 { 1642 fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer") 1643 flag.Usage() 1644 m.exitCode = 2 1645 return 1646 } 1647 if *matchFuzz != "" && *fuzzCacheDir == "" { 1648 fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set") 1649 flag.Usage() 1650 m.exitCode = 2 1651 return 1652 } 1653 1654 if len(*matchList) != 0 { 1655 listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples) 1656 m.exitCode = 0 1657 return 1658 } 1659 1660 if *shuffle != "off" { 1661 var n int64 1662 var err error 1663 if *shuffle == "on" { 1664 n = time.Now().UnixNano() 1665 } else { 1666 n, err = strconv.ParseInt(*shuffle, 10, 64) 1667 if err != nil { 1668 fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err) 1669 m.exitCode = 2 1670 return 1671 } 1672 } 1673 fmt.Println("-test.shuffle", n) 1674 rng := rand.New(rand.NewSource(n)) 1675 rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] }) 1676 rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] }) 1677 } 1678 1679 parseCpuList() 1680 1681 m.before() 1682 defer m.after() 1683 1684 // Run tests, examples, and benchmarks unless this is a fuzz worker process. 1685 // Workers start after this is done by their parent process, and they should 1686 // not repeat this work. 1687 if !*isFuzzWorker { 1688 deadline := m.startAlarm() 1689 haveExamples = len(m.examples) > 0 1690 testRan, testOk := runTests(m.deps.MatchString, m.tests, deadline) 1691 fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline) 1692 exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples) 1693 m.stopAlarm() 1694 if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" { 1695 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run") 1696 } 1697 if !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks) || race.Errors() > 0 { 1698 fmt.Println("FAIL") 1699 m.exitCode = 1 1700 return 1701 } 1702 } 1703 1704 fuzzingOk := runFuzzing(m.deps, m.fuzzTargets) 1705 if !fuzzingOk { 1706 fmt.Println("FAIL") 1707 if *isFuzzWorker { 1708 m.exitCode = fuzzWorkerExitCode 1709 } else { 1710 m.exitCode = 1 1711 } 1712 return 1713 } 1714 1715 m.exitCode = 0 1716 if !*isFuzzWorker { 1717 fmt.Println("PASS") 1718 } 1719 return 1720} 1721 1722func (t *T) report() { 1723 if t.parent == nil { 1724 return 1725 } 1726 dstr := fmtDuration(t.duration) 1727 format := "--- %s: %s (%s)\n" 1728 if t.Failed() { 1729 t.flushToParent(t.name, format, "FAIL", t.name, dstr) 1730 } else if t.chatty != nil { 1731 if t.Skipped() { 1732 t.flushToParent(t.name, format, "SKIP", t.name, dstr) 1733 } else { 1734 t.flushToParent(t.name, format, "PASS", t.name, dstr) 1735 } 1736 } 1737} 1738 1739func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) { 1740 if _, err := matchString(*matchList, "non-empty"); err != nil { 1741 fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err) 1742 os.Exit(1) 1743 } 1744 1745 for _, test := range tests { 1746 if ok, _ := matchString(*matchList, test.Name); ok { 1747 fmt.Println(test.Name) 1748 } 1749 } 1750 for _, bench := range benchmarks { 1751 if ok, _ := matchString(*matchList, bench.Name); ok { 1752 fmt.Println(bench.Name) 1753 } 1754 } 1755 for _, fuzzTarget := range fuzzTargets { 1756 if ok, _ := matchString(*matchList, fuzzTarget.Name); ok { 1757 fmt.Println(fuzzTarget.Name) 1758 } 1759 } 1760 for _, example := range examples { 1761 if ok, _ := matchString(*matchList, example.Name); ok { 1762 fmt.Println(example.Name) 1763 } 1764 } 1765} 1766 1767// RunTests is an internal function but exported because it is cross-package; 1768// it is part of the implementation of the "go test" command. 1769func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) { 1770 var deadline time.Time 1771 if *timeout > 0 { 1772 deadline = time.Now().Add(*timeout) 1773 } 1774 ran, ok := runTests(matchString, tests, deadline) 1775 if !ran && !haveExamples { 1776 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run") 1777 } 1778 return ok 1779} 1780 1781func runTests(matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) { 1782 ok = true 1783 for _, procs := range cpuList { 1784 runtime.GOMAXPROCS(procs) 1785 for i := uint(0); i < *count; i++ { 1786 if shouldFailFast() { 1787 break 1788 } 1789 if i > 0 && !ran { 1790 // There were no tests to run on the first 1791 // iteration. This won't change, so no reason 1792 // to keep trying. 1793 break 1794 } 1795 ctx := newTestContext(*parallel, newMatcher(matchString, *match, "-test.run")) 1796 ctx.deadline = deadline 1797 t := &T{ 1798 common: common{ 1799 signal: make(chan bool, 1), 1800 barrier: make(chan bool), 1801 w: os.Stdout, 1802 }, 1803 context: ctx, 1804 } 1805 if Verbose() { 1806 t.chatty = newChattyPrinter(t.w) 1807 } 1808 tRunner(t, func(t *T) { 1809 for _, test := range tests { 1810 t.Run(test.Name, test.F) 1811 } 1812 }) 1813 select { 1814 case <-t.signal: 1815 default: 1816 panic("internal error: tRunner exited without sending on t.signal") 1817 } 1818 ok = ok && !t.Failed() 1819 ran = ran || t.ran 1820 } 1821 } 1822 return ran, ok 1823} 1824 1825// before runs before all testing. 1826func (m *M) before() { 1827 if *memProfileRate > 0 { 1828 runtime.MemProfileRate = *memProfileRate 1829 } 1830 if *cpuProfile != "" { 1831 f, err := os.Create(toOutputDir(*cpuProfile)) 1832 if err != nil { 1833 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 1834 return 1835 } 1836 if err := m.deps.StartCPUProfile(f); err != nil { 1837 fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err) 1838 f.Close() 1839 return 1840 } 1841 // Could save f so after can call f.Close; not worth the effort. 1842 } 1843 if *traceFile != "" { 1844 f, err := os.Create(toOutputDir(*traceFile)) 1845 if err != nil { 1846 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 1847 return 1848 } 1849 if err := trace.Start(f); err != nil { 1850 fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err) 1851 f.Close() 1852 return 1853 } 1854 // Could save f so after can call f.Close; not worth the effort. 1855 } 1856 if *blockProfile != "" && *blockProfileRate >= 0 { 1857 runtime.SetBlockProfileRate(*blockProfileRate) 1858 } 1859 if *mutexProfile != "" && *mutexProfileFraction >= 0 { 1860 runtime.SetMutexProfileFraction(*mutexProfileFraction) 1861 } 1862 if *coverProfile != "" && cover.Mode == "" { 1863 fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n") 1864 os.Exit(2) 1865 } 1866 if *testlog != "" { 1867 // Note: Not using toOutputDir. 1868 // This file is for use by cmd/go, not users. 1869 var f *os.File 1870 var err error 1871 if m.numRun == 1 { 1872 f, err = os.Create(*testlog) 1873 } else { 1874 f, err = os.OpenFile(*testlog, os.O_WRONLY, 0) 1875 if err == nil { 1876 f.Seek(0, io.SeekEnd) 1877 } 1878 } 1879 if err != nil { 1880 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 1881 os.Exit(2) 1882 } 1883 m.deps.StartTestLog(f) 1884 testlogFile = f 1885 } 1886 if *panicOnExit0 { 1887 m.deps.SetPanicOnExit0(true) 1888 } 1889} 1890 1891// after runs after all testing. 1892func (m *M) after() { 1893 m.afterOnce.Do(func() { 1894 m.writeProfiles() 1895 }) 1896 1897 // Restore PanicOnExit0 after every run, because we set it to true before 1898 // every run. Otherwise, if m.Run is called multiple times the behavior of 1899 // os.Exit(0) will not be restored after the second run. 1900 if *panicOnExit0 { 1901 m.deps.SetPanicOnExit0(false) 1902 } 1903} 1904 1905func (m *M) writeProfiles() { 1906 if *testlog != "" { 1907 if err := m.deps.StopTestLog(); err != nil { 1908 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err) 1909 os.Exit(2) 1910 } 1911 if err := testlogFile.Close(); err != nil { 1912 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err) 1913 os.Exit(2) 1914 } 1915 } 1916 if *cpuProfile != "" { 1917 m.deps.StopCPUProfile() // flushes profile to disk 1918 } 1919 if *traceFile != "" { 1920 trace.Stop() // flushes trace to disk 1921 } 1922 if *memProfile != "" { 1923 f, err := os.Create(toOutputDir(*memProfile)) 1924 if err != nil { 1925 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 1926 os.Exit(2) 1927 } 1928 runtime.GC() // materialize all statistics 1929 if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil { 1930 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err) 1931 os.Exit(2) 1932 } 1933 f.Close() 1934 } 1935 if *blockProfile != "" && *blockProfileRate >= 0 { 1936 f, err := os.Create(toOutputDir(*blockProfile)) 1937 if err != nil { 1938 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 1939 os.Exit(2) 1940 } 1941 if err = m.deps.WriteProfileTo("block", f, 0); err != nil { 1942 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err) 1943 os.Exit(2) 1944 } 1945 f.Close() 1946 } 1947 if *mutexProfile != "" && *mutexProfileFraction >= 0 { 1948 f, err := os.Create(toOutputDir(*mutexProfile)) 1949 if err != nil { 1950 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 1951 os.Exit(2) 1952 } 1953 if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil { 1954 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err) 1955 os.Exit(2) 1956 } 1957 f.Close() 1958 } 1959 if cover.Mode != "" { 1960 coverReport() 1961 } 1962} 1963 1964// toOutputDir returns the file name relocated, if required, to outputDir. 1965// Simple implementation to avoid pulling in path/filepath. 1966func toOutputDir(path string) string { 1967 if *outputDir == "" || path == "" { 1968 return path 1969 } 1970 // On Windows, it's clumsy, but we can be almost always correct 1971 // by just looking for a drive letter and a colon. 1972 // Absolute paths always have a drive letter (ignoring UNC). 1973 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear 1974 // what to do, but even then path/filepath doesn't help. 1975 // TODO: Worth doing better? Probably not, because we're here only 1976 // under the management of go test. 1977 if runtime.GOOS == "windows" && len(path) >= 2 { 1978 letter, colon := path[0], path[1] 1979 if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' { 1980 // If path starts with a drive letter we're stuck with it regardless. 1981 return path 1982 } 1983 } 1984 if os.IsPathSeparator(path[0]) { 1985 return path 1986 } 1987 return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path) 1988} 1989 1990// startAlarm starts an alarm if requested. 1991func (m *M) startAlarm() time.Time { 1992 if *timeout <= 0 { 1993 return time.Time{} 1994 } 1995 1996 deadline := time.Now().Add(*timeout) 1997 m.timer = time.AfterFunc(*timeout, func() { 1998 m.after() 1999 debug.SetTraceback("all") 2000 panic(fmt.Sprintf("test timed out after %v", *timeout)) 2001 }) 2002 return deadline 2003} 2004 2005// stopAlarm turns off the alarm. 2006func (m *M) stopAlarm() { 2007 if *timeout > 0 { 2008 m.timer.Stop() 2009 } 2010} 2011 2012func parseCpuList() { 2013 for _, val := range strings.Split(*cpuListStr, ",") { 2014 val = strings.TrimSpace(val) 2015 if val == "" { 2016 continue 2017 } 2018 cpu, err := strconv.Atoi(val) 2019 if err != nil || cpu <= 0 { 2020 fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val) 2021 os.Exit(1) 2022 } 2023 cpuList = append(cpuList, cpu) 2024 } 2025 if cpuList == nil { 2026 cpuList = append(cpuList, runtime.GOMAXPROCS(-1)) 2027 } 2028} 2029 2030func shouldFailFast() bool { 2031 return *failFast && atomic.LoadUint32(&numFailed) > 0 2032} 2033