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