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 can be any alphanumeric string (but the first letter must not be in 10 // [a-z]) and 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 // Tests and benchmarks may be skipped if not applicable with a call to 21 // the Skip method of *T and *B: 22 // func TestTimeConsuming(t *testing.T) { 23 // if testing.Short() { 24 // t.Skip("skipping test in short mode.") 25 // } 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-Description_of_testing_flags. 38 // 39 // A sample benchmark function looks like this: 40 // func BenchmarkHello(b *testing.B) { 41 // for i := 0; i < b.N; i++ { 42 // fmt.Sprintf("hello") 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 // BenchmarkHello 10000000 282 ns/op 50 // means that the loop ran 10000000 times at a speed of 282 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 // Example functions without output comments are compiled but not executed. 99 // 100 // The naming convention to declare examples for the package, a function F, a type T and 101 // method M on type T are: 102 // 103 // func Example() { ... } 104 // func ExampleF() { ... } 105 // func ExampleT() { ... } 106 // func ExampleT_M() { ... } 107 // 108 // Multiple example functions for a package/type/function/method may be provided by 109 // appending a distinct suffix to the name. The suffix must start with a 110 // lower-case letter. 111 // 112 // func Example_suffix() { ... } 113 // func ExampleF_suffix() { ... } 114 // func ExampleT_suffix() { ... } 115 // func ExampleT_M_suffix() { ... } 116 // 117 // The entire test file is presented as the example when it contains a single 118 // example function, at least one other function, type, variable, or constant 119 // declaration, and no test or benchmark functions. 120 // 121 // Subtests and Sub-benchmarks 122 // 123 // The Run methods of T and B allow defining subtests and sub-benchmarks, 124 // without having to define separate functions for each. This enables uses 125 // like table-driven benchmarks and creating hierarchical tests. 126 // It also provides a way to share common setup and tear-down code: 127 // 128 // func TestFoo(t *testing.T) { 129 // // <setup code> 130 // t.Run("A=1", func(t *testing.T) { ... }) 131 // t.Run("A=2", func(t *testing.T) { ... }) 132 // t.Run("B=1", func(t *testing.T) { ... }) 133 // // <tear-down code> 134 // } 135 // 136 // Each subtest and sub-benchmark has a unique name: the combination of the name 137 // of the top-level test and the sequence of names passed to Run, separated by 138 // slashes, with an optional trailing sequence number for disambiguation. 139 // 140 // The argument to the -run and -bench command-line flags is an unanchored regular 141 // expression that matches the test's name. For tests with multiple slash-separated 142 // elements, such as subtests, the argument is itself slash-separated, with 143 // expressions matching each name element in turn. Because it is unanchored, an 144 // empty expression matches any string. 145 // For example, using "matching" to mean "whose name contains": 146 // 147 // go test -run '' # Run all tests. 148 // go test -run Foo # Run top-level tests matching "Foo", such as "TestFooBar". 149 // go test -run Foo/A= # For top-level tests matching "Foo", run subtests matching "A=". 150 // go test -run /A=1 # For all top-level tests, run subtests matching "A=1". 151 // 152 // Subtests can also be used to control parallelism. A parent test will only 153 // complete once all of its subtests complete. In this example, all tests are 154 // run in parallel with each other, and only with each other, regardless of 155 // other top-level tests that may be defined: 156 // 157 // func TestGroupedParallel(t *testing.T) { 158 // for _, tc := range tests { 159 // tc := tc // capture range variable 160 // t.Run(tc.Name, func(t *testing.T) { 161 // t.Parallel() 162 // ... 163 // }) 164 // } 165 // } 166 // 167 // Run does not return until parallel subtests have completed, providing a way 168 // to clean up after a group of parallel tests: 169 // 170 // func TestTeardownParallel(t *testing.T) { 171 // // This Run will not return until the parallel tests finish. 172 // t.Run("group", func(t *testing.T) { 173 // t.Run("Test1", parallelTest1) 174 // t.Run("Test2", parallelTest2) 175 // t.Run("Test3", parallelTest3) 176 // }) 177 // // <tear-down code> 178 // } 179 // 180 // Main 181 // 182 // It is sometimes necessary for a test program to do extra setup or teardown 183 // before or after testing. It is also sometimes necessary for a test to control 184 // which code runs on the main thread. To support these and other cases, 185 // if a test file contains a function: 186 // 187 // func TestMain(m *testing.M) 188 // 189 // then the generated test will call TestMain(m) instead of running the tests 190 // directly. TestMain runs in the main goroutine and can do whatever setup 191 // and teardown is necessary around a call to m.Run. It should then call 192 // os.Exit with the result of m.Run. When TestMain is called, flag.Parse has 193 // not been run. If TestMain depends on command-line flags, including those 194 // of the testing package, it should call flag.Parse explicitly. 195 // 196 // A simple implementation of TestMain is: 197 // 198 // func TestMain(m *testing.M) { 199 // // call flag.Parse() here if TestMain uses flags 200 // os.Exit(m.Run()) 201 // } 202 // 203 package testing 204 205 import ( 206 "bytes" 207 "errors" 208 "flag" 209 "fmt" 210 "internal/race" 211 "io" 212 "os" 213 "runtime" 214 "runtime/debug" 215 "runtime/trace" 216 "strconv" 217 "strings" 218 "sync" 219 "sync/atomic" 220 "time" 221 ) 222 223 var ( 224 // The short flag requests that tests run more quickly, but its functionality 225 // is provided by test writers themselves. The testing package is just its 226 // home. The all.bash installation script sets it to make installation more 227 // efficient, but by default the flag is off so a plain "go test" will do a 228 // full test of the package. 229 short = flag.Bool("test.short", false, "run smaller test suite to save time") 230 231 // The directory in which to create profile files and the like. When run from 232 // "go test", the binary always runs in the source directory for the package; 233 // this flag lets "go test" tell the binary to write the files in the directory where 234 // the "go test" command is run. 235 outputDir = flag.String("test.outputdir", "", "write profiles to `dir`") 236 237 // Report as tests are run; default is silent for success. 238 chatty = flag.Bool("test.v", false, "verbose: print additional output") 239 count = flag.Uint("test.count", 1, "run tests and benchmarks `n` times") 240 coverProfile = flag.String("test.coverprofile", "", "write a coverage profile to `file`") 241 match = flag.String("test.run", "", "run only tests and examples matching `regexp`") 242 memProfile = flag.String("test.memprofile", "", "write a memory profile to `file`") 243 memProfileRate = flag.Int("test.memprofilerate", 0, "set memory profiling `rate` (see runtime.MemProfileRate)") 244 cpuProfile = flag.String("test.cpuprofile", "", "write a cpu profile to `file`") 245 blockProfile = flag.String("test.blockprofile", "", "write a goroutine blocking profile to `file`") 246 blockProfileRate = flag.Int("test.blockprofilerate", 1, "set blocking profile `rate` (see runtime.SetBlockProfileRate)") 247 mutexProfile = flag.String("test.mutexprofile", "", "write a mutex contention profile to the named file after execution") 248 mutexProfileFraction = flag.Int("test.mutexprofilefraction", 1, "if >= 0, calls runtime.SetMutexProfileFraction()") 249 traceFile = flag.String("test.trace", "", "write an execution trace to `file`") 250 timeout = flag.Duration("test.timeout", 0, "fail test binary execution after duration `d` (0 means unlimited)") 251 cpuListStr = flag.String("test.cpu", "", "comma-separated `list` of cpu counts to run each test with") 252 parallel = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "run at most `n` tests in parallel") 253 254 haveExamples bool // are there examples? 255 256 cpuList []int 257 ) 258 259 // common holds the elements common between T and B and 260 // captures common methods such as Errorf. 261 type common struct { 262 mu sync.RWMutex // guards output, failed, and done. 263 output []byte // Output generated by test or benchmark. 264 w io.Writer // For flushToParent. 265 chatty bool // A copy of the chatty flag. 266 ran bool // Test or benchmark (or one of its subtests) was executed. 267 failed bool // Test or benchmark has failed. 268 skipped bool // Test of benchmark has been skipped. 269 finished bool // Test function has completed. 270 done bool // Test is finished and all subtests have completed. 271 hasSub int32 // written atomically 272 raceErrors int // number of races detected during test 273 274 parent *common 275 level int // Nesting depth of test or benchmark. 276 name string // Name of test or benchmark. 277 start time.Time // Time test or benchmark started 278 duration time.Duration 279 barrier chan bool // To signal parallel subtests they may start. 280 signal chan bool // To signal a test is done. 281 sub []*T // Queue of subtests to be run in parallel. 282 } 283 284 // Short reports whether the -test.short flag is set. 285 func Short() bool { 286 return *short 287 } 288 289 // CoverMode reports what the test coverage mode is set to. The 290 // values are "set", "count", or "atomic". The return value will be 291 // empty if test coverage is not enabled. 292 func CoverMode() string { 293 return cover.Mode 294 } 295 296 // Verbose reports whether the -test.v flag is set. 297 func Verbose() bool { 298 return *chatty 299 } 300 301 // decorate prefixes the string with the file and line of the call site 302 // and inserts the final newline if needed and indentation tabs for formatting. 303 func decorate(s string) string { 304 _, file, line, ok := runtime.Caller(3) // decorate + log + public function. 305 if ok { 306 // Truncate file name at last file name separator. 307 if index := strings.LastIndex(file, "/"); index >= 0 { 308 file = file[index+1:] 309 } else if index = strings.LastIndex(file, "\\"); index >= 0 { 310 file = file[index+1:] 311 } 312 } else { 313 file = "???" 314 line = 1 315 } 316 buf := new(bytes.Buffer) 317 // Every line is indented at least one tab. 318 buf.WriteByte('\t') 319 fmt.Fprintf(buf, "%s:%d: ", file, line) 320 lines := strings.Split(s, "\n") 321 if l := len(lines); l > 1 && lines[l-1] == "" { 322 lines = lines[:l-1] 323 } 324 for i, line := range lines { 325 if i > 0 { 326 // Second and subsequent lines are indented an extra tab. 327 buf.WriteString("\n\t\t") 328 } 329 buf.WriteString(line) 330 } 331 buf.WriteByte('\n') 332 return buf.String() 333 } 334 335 // flushToParent writes c.output to the parent after first writing the header 336 // with the given format and arguments. 337 func (c *common) flushToParent(format string, args ...interface{}) { 338 p := c.parent 339 p.mu.Lock() 340 defer p.mu.Unlock() 341 342 fmt.Fprintf(p.w, format, args...) 343 344 c.mu.Lock() 345 defer c.mu.Unlock() 346 io.Copy(p.w, bytes.NewReader(c.output)) 347 c.output = c.output[:0] 348 } 349 350 type indenter struct { 351 c *common 352 } 353 354 func (w indenter) Write(b []byte) (n int, err error) { 355 n = len(b) 356 for len(b) > 0 { 357 end := bytes.IndexByte(b, '\n') 358 if end == -1 { 359 end = len(b) 360 } else { 361 end++ 362 } 363 // An indent of 4 spaces will neatly align the dashes with the status 364 // indicator of the parent. 365 const indent = " " 366 w.c.output = append(w.c.output, indent...) 367 w.c.output = append(w.c.output, b[:end]...) 368 b = b[end:] 369 } 370 return 371 } 372 373 // fmtDuration returns a string representing d in the form "87.00s". 374 func fmtDuration(d time.Duration) string { 375 return fmt.Sprintf("%.2fs", d.Seconds()) 376 } 377 378 // TB is the interface common to T and B. 379 type TB interface { 380 Error(args ...interface{}) 381 Errorf(format string, args ...interface{}) 382 Fail() 383 FailNow() 384 Failed() bool 385 Fatal(args ...interface{}) 386 Fatalf(format string, args ...interface{}) 387 Log(args ...interface{}) 388 Logf(format string, args ...interface{}) 389 Name() string 390 Skip(args ...interface{}) 391 SkipNow() 392 Skipf(format string, args ...interface{}) 393 Skipped() bool 394 395 // A private method to prevent users implementing the 396 // interface and so future additions to it will not 397 // violate Go 1 compatibility. 398 private() 399 } 400 401 var _ TB = (*T)(nil) 402 var _ TB = (*B)(nil) 403 404 // T is a type passed to Test functions to manage test state and support formatted test logs. 405 // Logs are accumulated during execution and dumped to standard output when done. 406 // 407 // A test ends when its Test function returns or calls any of the methods 408 // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as 409 // the Parallel method, must be called only from the goroutine running the 410 // Test function. 411 // 412 // The other reporting methods, such as the variations of Log and Error, 413 // may be called simultaneously from multiple goroutines. 414 type T struct { 415 common 416 isParallel bool 417 context *testContext // For running tests and subtests. 418 } 419 420 func (c *common) private() {} 421 422 // Name returns the name of the running test or benchmark. 423 func (c *common) Name() string { 424 return c.name 425 } 426 427 func (c *common) setRan() { 428 if c.parent != nil { 429 c.parent.setRan() 430 } 431 c.mu.Lock() 432 defer c.mu.Unlock() 433 c.ran = true 434 } 435 436 // Fail marks the function as having failed but continues execution. 437 func (c *common) Fail() { 438 if c.parent != nil { 439 c.parent.Fail() 440 } 441 c.mu.Lock() 442 defer c.mu.Unlock() 443 // c.done needs to be locked to synchronize checks to c.done in parent tests. 444 if c.done { 445 panic("Fail in goroutine after " + c.name + " has completed") 446 } 447 c.failed = true 448 } 449 450 // Failed reports whether the function has failed. 451 func (c *common) Failed() bool { 452 c.mu.RLock() 453 defer c.mu.RUnlock() 454 return c.failed 455 } 456 457 // FailNow marks the function as having failed and stops its execution. 458 // Execution will continue at the next test or benchmark. 459 // FailNow must be called from the goroutine running the 460 // test or benchmark function, not from other goroutines 461 // created during the test. Calling FailNow does not stop 462 // those other goroutines. 463 func (c *common) FailNow() { 464 c.Fail() 465 466 // Calling runtime.Goexit will exit the goroutine, which 467 // will run the deferred functions in this goroutine, 468 // which will eventually run the deferred lines in tRunner, 469 // which will signal to the test loop that this test is done. 470 // 471 // A previous version of this code said: 472 // 473 // c.duration = ... 474 // c.signal <- c.self 475 // runtime.Goexit() 476 // 477 // This previous version duplicated code (those lines are in 478 // tRunner no matter what), but worse the goroutine teardown 479 // implicit in runtime.Goexit was not guaranteed to complete 480 // before the test exited. If a test deferred an important cleanup 481 // function (like removing temporary files), there was no guarantee 482 // it would run on a test failure. Because we send on c.signal during 483 // a top-of-stack deferred function now, we know that the send 484 // only happens after any other stacked defers have completed. 485 c.finished = true 486 runtime.Goexit() 487 } 488 489 // log generates the output. It's always at the same stack depth. 490 func (c *common) log(s string) { 491 c.mu.Lock() 492 defer c.mu.Unlock() 493 c.output = append(c.output, decorate(s)...) 494 } 495 496 // Log formats its arguments using default formatting, analogous to Println, 497 // and records the text in the error log. For tests, the text will be printed only if 498 // the test fails or the -test.v flag is set. For benchmarks, the text is always 499 // printed to avoid having performance depend on the value of the -test.v flag. 500 func (c *common) Log(args ...interface{}) { c.log(fmt.Sprintln(args...)) } 501 502 // Logf formats its arguments according to the format, analogous to Printf, and 503 // records the text in the error log. A final newline is added if not provided. For 504 // tests, the text will be printed only if the test fails or the -test.v flag is 505 // set. For benchmarks, the text is always printed to avoid having performance 506 // depend on the value of the -test.v flag. 507 func (c *common) Logf(format string, args ...interface{}) { c.log(fmt.Sprintf(format, args...)) } 508 509 // Error is equivalent to Log followed by Fail. 510 func (c *common) Error(args ...interface{}) { 511 c.log(fmt.Sprintln(args...)) 512 c.Fail() 513 } 514 515 // Errorf is equivalent to Logf followed by Fail. 516 func (c *common) Errorf(format string, args ...interface{}) { 517 c.log(fmt.Sprintf(format, args...)) 518 c.Fail() 519 } 520 521 // Fatal is equivalent to Log followed by FailNow. 522 func (c *common) Fatal(args ...interface{}) { 523 c.log(fmt.Sprintln(args...)) 524 c.FailNow() 525 } 526 527 // Fatalf is equivalent to Logf followed by FailNow. 528 func (c *common) Fatalf(format string, args ...interface{}) { 529 c.log(fmt.Sprintf(format, args...)) 530 c.FailNow() 531 } 532 533 // Skip is equivalent to Log followed by SkipNow. 534 func (c *common) Skip(args ...interface{}) { 535 c.log(fmt.Sprintln(args...)) 536 c.SkipNow() 537 } 538 539 // Skipf is equivalent to Logf followed by SkipNow. 540 func (c *common) Skipf(format string, args ...interface{}) { 541 c.log(fmt.Sprintf(format, args...)) 542 c.SkipNow() 543 } 544 545 // SkipNow marks the test as having been skipped and stops its execution. 546 // If a test fails (see Error, Errorf, Fail) and is then skipped, 547 // it is still considered to have failed. 548 // Execution will continue at the next test or benchmark. See also FailNow. 549 // SkipNow must be called from the goroutine running the test, not from 550 // other goroutines created during the test. Calling SkipNow does not stop 551 // those other goroutines. 552 func (c *common) SkipNow() { 553 c.skip() 554 c.finished = true 555 runtime.Goexit() 556 } 557 558 func (c *common) skip() { 559 c.mu.Lock() 560 defer c.mu.Unlock() 561 c.skipped = true 562 } 563 564 // Skipped reports whether the test was skipped. 565 func (c *common) Skipped() bool { 566 c.mu.RLock() 567 defer c.mu.RUnlock() 568 return c.skipped 569 } 570 571 // Parallel signals that this test is to be run in parallel with (and only with) 572 // other parallel tests. 573 func (t *T) Parallel() { 574 if t.isParallel { 575 panic("testing: t.Parallel called multiple times") 576 } 577 t.isParallel = true 578 579 // We don't want to include the time we spend waiting for serial tests 580 // in the test duration. Record the elapsed time thus far and reset the 581 // timer afterwards. 582 t.duration += time.Since(t.start) 583 584 // Add to the list of tests to be released by the parent. 585 t.parent.sub = append(t.parent.sub, t) 586 t.raceErrors += race.Errors() 587 588 t.signal <- true // Release calling test. 589 <-t.parent.barrier // Wait for the parent test to complete. 590 t.context.waitParallel() 591 t.start = time.Now() 592 t.raceErrors += -race.Errors() 593 } 594 595 // An internal type but exported because it is cross-package; part of the implementation 596 // of the "go test" command. 597 type InternalTest struct { 598 Name string 599 F func(*T) 600 } 601 602 func tRunner(t *T, fn func(t *T)) { 603 // When this goroutine is done, either because fn(t) 604 // returned normally or because a test failure triggered 605 // a call to runtime.Goexit, record the duration and send 606 // a signal saying that the test is done. 607 defer func() { 608 t.raceErrors += race.Errors() 609 if t.raceErrors > 0 { 610 t.Errorf("race detected during execution of test") 611 } 612 613 t.duration += time.Now().Sub(t.start) 614 // If the test panicked, print any test output before dying. 615 err := recover() 616 if !t.finished && err == nil { 617 err = fmt.Errorf("test executed panic(nil) or runtime.Goexit") 618 } 619 if err != nil { 620 t.Fail() 621 t.report() 622 panic(err) 623 } 624 625 if len(t.sub) > 0 { 626 // Run parallel subtests. 627 // Decrease the running count for this test. 628 t.context.release() 629 // Release the parallel subtests. 630 close(t.barrier) 631 // Wait for subtests to complete. 632 for _, sub := range t.sub { 633 <-sub.signal 634 } 635 if !t.isParallel { 636 // Reacquire the count for sequential tests. See comment in Run. 637 t.context.waitParallel() 638 } 639 } else if t.isParallel { 640 // Only release the count for this test if it was run as a parallel 641 // test. See comment in Run method. 642 t.context.release() 643 } 644 t.report() // Report after all subtests have finished. 645 646 // Do not lock t.done to allow race detector to detect race in case 647 // the user does not appropriately synchronizes a goroutine. 648 t.done = true 649 if t.parent != nil && atomic.LoadInt32(&t.hasSub) == 0 { 650 t.setRan() 651 } 652 t.signal <- true 653 }() 654 655 t.start = time.Now() 656 t.raceErrors = -race.Errors() 657 fn(t) 658 t.finished = true 659 } 660 661 // Run runs f as a subtest of t called name. It reports whether f succeeded. 662 // Run will block until all its parallel subtests have completed. 663 // 664 // Run may be called simultaneously from multiple goroutines, but all such 665 // calls must happen before the outer test function for t returns. 666 func (t *T) Run(name string, f func(t *T)) bool { 667 atomic.StoreInt32(&t.hasSub, 1) 668 testName, ok := t.context.match.fullName(&t.common, name) 669 if !ok { 670 return true 671 } 672 t = &T{ 673 common: common{ 674 barrier: make(chan bool), 675 signal: make(chan bool), 676 name: testName, 677 parent: &t.common, 678 level: t.level + 1, 679 chatty: t.chatty, 680 }, 681 context: t.context, 682 } 683 t.w = indenter{&t.common} 684 685 if t.chatty { 686 // Print directly to root's io.Writer so there is no delay. 687 root := t.parent 688 for ; root.parent != nil; root = root.parent { 689 } 690 fmt.Fprintf(root.w, "=== RUN %s\n", t.name) 691 } 692 // Instead of reducing the running count of this test before calling the 693 // tRunner and increasing it afterwards, we rely on tRunner keeping the 694 // count correct. This ensures that a sequence of sequential tests runs 695 // without being preempted, even when their parent is a parallel test. This 696 // may especially reduce surprises if *parallel == 1. 697 go tRunner(t, f) 698 <-t.signal 699 return !t.failed 700 } 701 702 // testContext holds all fields that are common to all tests. This includes 703 // synchronization primitives to run at most *parallel tests. 704 type testContext struct { 705 match *matcher 706 707 mu sync.Mutex 708 709 // Channel used to signal tests that are ready to be run in parallel. 710 startParallel chan bool 711 712 // running is the number of tests currently running in parallel. 713 // This does not include tests that are waiting for subtests to complete. 714 running int 715 716 // numWaiting is the number tests waiting to be run in parallel. 717 numWaiting int 718 719 // maxParallel is a copy of the parallel flag. 720 maxParallel int 721 } 722 723 func newTestContext(maxParallel int, m *matcher) *testContext { 724 return &testContext{ 725 match: m, 726 startParallel: make(chan bool), 727 maxParallel: maxParallel, 728 running: 1, // Set the count to 1 for the main (sequential) test. 729 } 730 } 731 732 func (c *testContext) waitParallel() { 733 c.mu.Lock() 734 if c.running < c.maxParallel { 735 c.running++ 736 c.mu.Unlock() 737 return 738 } 739 c.numWaiting++ 740 c.mu.Unlock() 741 <-c.startParallel 742 } 743 744 func (c *testContext) release() { 745 c.mu.Lock() 746 if c.numWaiting == 0 { 747 c.running-- 748 c.mu.Unlock() 749 return 750 } 751 c.numWaiting-- 752 c.mu.Unlock() 753 c.startParallel <- true // Pick a waiting test to be run. 754 } 755 756 // No one should be using func Main anymore. 757 // See the doc comment on func Main and use MainStart instead. 758 var errMain = errors.New("testing: unexpected use of func Main") 759 760 type matchStringOnly func(pat, str string) (bool, error) 761 762 func (f matchStringOnly) MatchString(pat, str string) (bool, error) { return f(pat, str) } 763 func (f matchStringOnly) StartCPUProfile(w io.Writer) error { return errMain } 764 func (f matchStringOnly) StopCPUProfile() {} 765 func (f matchStringOnly) WriteHeapProfile(w io.Writer) error { return errMain } 766 func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain } 767 768 // Main is an internal function, part of the implementation of the "go test" command. 769 // It was exported because it is cross-package and predates "internal" packages. 770 // It is no longer used by "go test" but preserved, as much as possible, for other 771 // systems that simulate "go test" using Main, but Main sometimes cannot be updated as 772 // new functionality is added to the testing package. 773 // Systems simulating "go test" should be updated to use MainStart. 774 func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) { 775 os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, examples).Run()) 776 } 777 778 // M is a type passed to a TestMain function to run the actual tests. 779 type M struct { 780 deps testDeps 781 tests []InternalTest 782 benchmarks []InternalBenchmark 783 examples []InternalExample 784 } 785 786 // testDeps is an internal interface of functionality that is 787 // passed into this package by a test's generated main package. 788 // The canonical implementation of this interface is 789 // testing/internal/testdeps's TestDeps. 790 type testDeps interface { 791 MatchString(pat, str string) (bool, error) 792 StartCPUProfile(io.Writer) error 793 StopCPUProfile() 794 WriteHeapProfile(io.Writer) error 795 WriteProfileTo(string, io.Writer, int) error 796 } 797 798 // MainStart is meant for use by tests generated by 'go test'. 799 // It is not meant to be called directly and is not subject to the Go 1 compatibility document. 800 // It may change signature from release to release. 801 func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) *M { 802 return &M{ 803 deps: deps, 804 tests: tests, 805 benchmarks: benchmarks, 806 examples: examples, 807 } 808 } 809 810 // Run runs the tests. It returns an exit code to pass to os.Exit. 811 func (m *M) Run() int { 812 // TestMain may have already called flag.Parse. 813 if !flag.Parsed() { 814 flag.Parse() 815 } 816 817 parseCpuList() 818 819 m.before() 820 startAlarm() 821 haveExamples = len(m.examples) > 0 822 testRan, testOk := runTests(m.deps.MatchString, m.tests) 823 exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples) 824 stopAlarm() 825 if !testRan && !exampleRan && *matchBenchmarks == "" { 826 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run") 827 } 828 if !testOk || !exampleOk || !runBenchmarks(m.deps.MatchString, m.benchmarks) || race.Errors() > 0 { 829 fmt.Println("FAIL") 830 m.after() 831 return 1 832 } 833 834 fmt.Println("PASS") 835 m.after() 836 return 0 837 } 838 839 func (t *T) report() { 840 if t.parent == nil { 841 return 842 } 843 dstr := fmtDuration(t.duration) 844 format := "--- %s: %s (%s)\n" 845 if t.Failed() { 846 t.flushToParent(format, "FAIL", t.name, dstr) 847 } else if t.chatty { 848 if t.Skipped() { 849 t.flushToParent(format, "SKIP", t.name, dstr) 850 } else { 851 t.flushToParent(format, "PASS", t.name, dstr) 852 } 853 } 854 } 855 856 // An internal function but exported because it is cross-package; part of the implementation 857 // of the "go test" command. 858 func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) { 859 ran, ok := runTests(matchString, tests) 860 if !ran && !haveExamples { 861 fmt.Fprintln(os.Stderr, "testing: warning: no tests to run") 862 } 863 return ok 864 } 865 866 func runTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ran, ok bool) { 867 ok = true 868 for _, procs := range cpuList { 869 runtime.GOMAXPROCS(procs) 870 ctx := newTestContext(*parallel, newMatcher(matchString, *match, "-test.run")) 871 t := &T{ 872 common: common{ 873 signal: make(chan bool), 874 barrier: make(chan bool), 875 w: os.Stdout, 876 chatty: *chatty, 877 }, 878 context: ctx, 879 } 880 tRunner(t, func(t *T) { 881 for _, test := range tests { 882 t.Run(test.Name, test.F) 883 } 884 // Run catching the signal rather than the tRunner as a separate 885 // goroutine to avoid adding a goroutine during the sequential 886 // phase as this pollutes the stacktrace output when aborting. 887 go func() { <-t.signal }() 888 }) 889 ok = ok && !t.Failed() 890 ran = ran || t.ran 891 } 892 return ran, ok 893 } 894 895 // before runs before all testing. 896 func (m *M) before() { 897 if *memProfileRate > 0 { 898 runtime.MemProfileRate = *memProfileRate 899 } 900 if *cpuProfile != "" { 901 f, err := os.Create(toOutputDir(*cpuProfile)) 902 if err != nil { 903 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 904 return 905 } 906 if err := m.deps.StartCPUProfile(f); err != nil { 907 fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err) 908 f.Close() 909 return 910 } 911 // Could save f so after can call f.Close; not worth the effort. 912 } 913 if *traceFile != "" { 914 f, err := os.Create(toOutputDir(*traceFile)) 915 if err != nil { 916 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 917 return 918 } 919 if err := trace.Start(f); err != nil { 920 fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err) 921 f.Close() 922 return 923 } 924 // Could save f so after can call f.Close; not worth the effort. 925 } 926 if *blockProfile != "" && *blockProfileRate >= 0 { 927 runtime.SetBlockProfileRate(*blockProfileRate) 928 } 929 if *mutexProfile != "" && *mutexProfileFraction >= 0 { 930 runtime.SetMutexProfileFraction(*mutexProfileFraction) 931 } 932 if *coverProfile != "" && cover.Mode == "" { 933 fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n") 934 os.Exit(2) 935 } 936 } 937 938 // after runs after all testing. 939 func (m *M) after() { 940 if *cpuProfile != "" { 941 m.deps.StopCPUProfile() // flushes profile to disk 942 } 943 if *traceFile != "" { 944 trace.Stop() // flushes trace to disk 945 } 946 if *memProfile != "" { 947 f, err := os.Create(toOutputDir(*memProfile)) 948 if err != nil { 949 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 950 os.Exit(2) 951 } 952 runtime.GC() // materialize all statistics 953 if err = m.deps.WriteHeapProfile(f); err != nil { 954 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err) 955 os.Exit(2) 956 } 957 f.Close() 958 } 959 if *blockProfile != "" && *blockProfileRate >= 0 { 960 f, err := os.Create(toOutputDir(*blockProfile)) 961 if err != nil { 962 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 963 os.Exit(2) 964 } 965 if err = m.deps.WriteProfileTo("block", f, 0); err != nil { 966 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err) 967 os.Exit(2) 968 } 969 f.Close() 970 } 971 if *mutexProfile != "" && *mutexProfileFraction >= 0 { 972 f, err := os.Create(toOutputDir(*mutexProfile)) 973 if err != nil { 974 fmt.Fprintf(os.Stderr, "testing: %s\n", err) 975 os.Exit(2) 976 } 977 if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil { 978 fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err) 979 os.Exit(2) 980 } 981 f.Close() 982 } 983 if cover.Mode != "" { 984 coverReport() 985 } 986 } 987 988 // toOutputDir returns the file name relocated, if required, to outputDir. 989 // Simple implementation to avoid pulling in path/filepath. 990 func toOutputDir(path string) string { 991 if *outputDir == "" || path == "" { 992 return path 993 } 994 if runtime.GOOS == "windows" { 995 // On Windows, it's clumsy, but we can be almost always correct 996 // by just looking for a drive letter and a colon. 997 // Absolute paths always have a drive letter (ignoring UNC). 998 // Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear 999 // what to do, but even then path/filepath doesn't help. 1000 // TODO: Worth doing better? Probably not, because we're here only 1001 // under the management of go test. 1002 if len(path) >= 2 { 1003 letter, colon := path[0], path[1] 1004 if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' { 1005 // If path starts with a drive letter we're stuck with it regardless. 1006 return path 1007 } 1008 } 1009 } 1010 if os.IsPathSeparator(path[0]) { 1011 return path 1012 } 1013 return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path) 1014 } 1015 1016 var timer *time.Timer 1017 1018 // startAlarm starts an alarm if requested. 1019 func startAlarm() { 1020 if *timeout > 0 { 1021 timer = time.AfterFunc(*timeout, func() { 1022 debug.SetTraceback("all") 1023 panic(fmt.Sprintf("test timed out after %v", *timeout)) 1024 }) 1025 } 1026 } 1027 1028 // stopAlarm turns off the alarm. 1029 func stopAlarm() { 1030 if *timeout > 0 { 1031 timer.Stop() 1032 } 1033 } 1034 1035 func parseCpuList() { 1036 for _, val := range strings.Split(*cpuListStr, ",") { 1037 val = strings.TrimSpace(val) 1038 if val == "" { 1039 continue 1040 } 1041 cpu, err := strconv.Atoi(val) 1042 if err != nil || cpu <= 0 { 1043 fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val) 1044 os.Exit(1) 1045 } 1046 for i := uint(0); i < *count; i++ { 1047 cpuList = append(cpuList, cpu) 1048 } 1049 } 1050 if cpuList == nil { 1051 for i := uint(0); i < *count; i++ { 1052 cpuList = append(cpuList, runtime.GOMAXPROCS(-1)) 1053 } 1054 } 1055 } 1056