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