...
Run Format

Source file src/testing/testing.go

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

View as plain text