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