...
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 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	

View as plain text