Source file src/testing/testing.go

Documentation: testing

     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  //
     9  //	func TestXxx(*testing.T)
    10  //
    11  // where Xxx does not start with a lowercase letter. The function name
    12  // serves to identify the test routine.
    13  //
    14  // Within these functions, use the Error, Fail or related methods to signal failure.
    15  //
    16  // To write a new test suite, create a file whose name ends _test.go that
    17  // contains the TestXxx functions as described here. Put the file in the same
    18  // package as the one being tested. The file will be excluded from regular
    19  // package builds but will be included when the "go test" command is run.
    20  // For more detail, run "go help test" and "go help testflag".
    21  //
    22  // A simple test function looks like this:
    23  //
    24  //	func TestAbs(t *testing.T) {
    25  //	    got := Abs(-1)
    26  //	    if got != 1 {
    27  //	        t.Errorf("Abs(-1) = %d; want 1", got)
    28  //	    }
    29  //	}
    30  //
    31  // # Benchmarks
    32  //
    33  // Functions of the form
    34  //
    35  //	func BenchmarkXxx(*testing.B)
    36  //
    37  // are considered benchmarks, and are executed by the "go test" command when
    38  // its -bench flag is provided. Benchmarks are run sequentially.
    39  //
    40  // For a description of the testing flags, see
    41  // https://golang.org/cmd/go/#hdr-Testing_flags.
    42  //
    43  // A sample benchmark function looks like this:
    44  //
    45  //	func BenchmarkRandInt(b *testing.B) {
    46  //	    for i := 0; i < b.N; i++ {
    47  //	        rand.Int()
    48  //	    }
    49  //	}
    50  //
    51  // The benchmark function must run the target code b.N times.
    52  // During benchmark execution, b.N is adjusted until the benchmark function lasts
    53  // long enough to be timed reliably. The output
    54  //
    55  //	BenchmarkRandInt-8   	68453040	        17.8 ns/op
    56  //
    57  // means that the loop ran 68453040 times at a speed of 17.8 ns per loop.
    58  //
    59  // If a benchmark needs some expensive setup before running, the timer
    60  // may be reset:
    61  //
    62  //	func BenchmarkBigLen(b *testing.B) {
    63  //	    big := NewBig()
    64  //	    b.ResetTimer()
    65  //	    for i := 0; i < b.N; i++ {
    66  //	        big.Len()
    67  //	    }
    68  //	}
    69  //
    70  // If a benchmark needs to test performance in a parallel setting, it may use
    71  // the RunParallel helper function; such benchmarks are intended to be used with
    72  // the go test -cpu flag:
    73  //
    74  //	func BenchmarkTemplateParallel(b *testing.B) {
    75  //	    templ := template.Must(template.New("test").Parse("Hello, {{.}}!"))
    76  //	    b.RunParallel(func(pb *testing.PB) {
    77  //	        var buf bytes.Buffer
    78  //	        for pb.Next() {
    79  //	            buf.Reset()
    80  //	            templ.Execute(&buf, "World")
    81  //	        }
    82  //	    })
    83  //	}
    84  //
    85  // A detailed specification of the benchmark results format is given
    86  // in https://golang.org/design/14313-benchmark-format.
    87  //
    88  // There are standard tools for working with benchmark results at
    89  // https://golang.org/x/perf/cmd.
    90  // In particular, https://golang.org/x/perf/cmd/benchstat performs
    91  // statistically robust A/B comparisons.
    92  //
    93  // # Examples
    94  //
    95  // The package also runs and verifies example code. Example functions may
    96  // include a concluding line comment that begins with "Output:" and is compared with
    97  // the standard output of the function when the tests are run. (The comparison
    98  // ignores leading and trailing space.) These are examples of an example:
    99  //
   100  //	func ExampleHello() {
   101  //	    fmt.Println("hello")
   102  //	    // Output: hello
   103  //	}
   104  //
   105  //	func ExampleSalutations() {
   106  //	    fmt.Println("hello, and")
   107  //	    fmt.Println("goodbye")
   108  //	    // Output:
   109  //	    // hello, and
   110  //	    // goodbye
   111  //	}
   112  //
   113  // The comment prefix "Unordered output:" is like "Output:", but matches any
   114  // line order:
   115  //
   116  //	func ExamplePerm() {
   117  //	    for _, value := range Perm(5) {
   118  //	        fmt.Println(value)
   119  //	    }
   120  //	    // Unordered output: 4
   121  //	    // 2
   122  //	    // 1
   123  //	    // 3
   124  //	    // 0
   125  //	}
   126  //
   127  // Example functions without output comments are compiled but not executed.
   128  //
   129  // The naming convention to declare examples for the package, a function F, a type T and
   130  // method M on type T are:
   131  //
   132  //	func Example() { ... }
   133  //	func ExampleF() { ... }
   134  //	func ExampleT() { ... }
   135  //	func ExampleT_M() { ... }
   136  //
   137  // Multiple example functions for a package/type/function/method may be provided by
   138  // appending a distinct suffix to the name. The suffix must start with a
   139  // lower-case letter.
   140  //
   141  //	func Example_suffix() { ... }
   142  //	func ExampleF_suffix() { ... }
   143  //	func ExampleT_suffix() { ... }
   144  //	func ExampleT_M_suffix() { ... }
   145  //
   146  // The entire test file is presented as the example when it contains a single
   147  // example function, at least one other function, type, variable, or constant
   148  // declaration, and no test or benchmark functions.
   149  //
   150  // # Fuzzing
   151  //
   152  // 'go test' and the testing package support fuzzing, a testing technique where
   153  // a function is called with randomly generated inputs to find bugs not
   154  // anticipated by unit tests.
   155  //
   156  // Functions of the form
   157  //
   158  //	func FuzzXxx(*testing.F)
   159  //
   160  // are considered fuzz tests.
   161  //
   162  // For example:
   163  //
   164  //	func FuzzHex(f *testing.F) {
   165  //	  for _, seed := range [][]byte{{}, {0}, {9}, {0xa}, {0xf}, {1, 2, 3, 4}} {
   166  //	    f.Add(seed)
   167  //	  }
   168  //	  f.Fuzz(func(t *testing.T, in []byte) {
   169  //	    enc := hex.EncodeToString(in)
   170  //	    out, err := hex.DecodeString(enc)
   171  //	    if err != nil {
   172  //	      t.Fatalf("%v: decode: %v", in, err)
   173  //	    }
   174  //	    if !bytes.Equal(in, out) {
   175  //	      t.Fatalf("%v: not equal after round trip: %v", in, out)
   176  //	    }
   177  //	  })
   178  //	}
   179  //
   180  // A fuzz test maintains a seed corpus, or a set of inputs which are run by
   181  // default, and can seed input generation. Seed inputs may be registered by
   182  // calling (*F).Add or by storing files in the directory testdata/fuzz/<Name>
   183  // (where <Name> is the name of the fuzz test) within the package containing
   184  // the fuzz test. Seed inputs are optional, but the fuzzing engine may find
   185  // bugs more efficiently when provided with a set of small seed inputs with good
   186  // code coverage. These seed inputs can also serve as regression tests for bugs
   187  // identified through fuzzing.
   188  //
   189  // The function passed to (*F).Fuzz within the fuzz test is considered the fuzz
   190  // target. A fuzz target must accept a *T parameter, followed by one or more
   191  // parameters for random inputs. The types of arguments passed to (*F).Add must
   192  // be identical to the types of these parameters. The fuzz target may signal
   193  // that it's found a problem the same way tests do: by calling T.Fail (or any
   194  // method that calls it like T.Error or T.Fatal) or by panicking.
   195  //
   196  // When fuzzing is enabled (by setting the -fuzz flag to a regular expression
   197  // that matches a specific fuzz test), the fuzz target is called with arguments
   198  // generated by repeatedly making random changes to the seed inputs. On
   199  // supported platforms, 'go test' compiles the test executable with fuzzing
   200  // coverage instrumentation. The fuzzing engine uses that instrumentation to
   201  // find and cache inputs that expand coverage, increasing the likelihood of
   202  // finding bugs. If the fuzz target fails for a given input, the fuzzing engine
   203  // writes the inputs that caused the failure to a file in the directory
   204  // testdata/fuzz/<Name> within the package directory. This file later serves as
   205  // a seed input. If the file can't be written at that location (for example,
   206  // because the directory is read-only), the fuzzing engine writes the file to
   207  // the fuzz cache directory within the build cache instead.
   208  //
   209  // When fuzzing is disabled, the fuzz target is called with the seed inputs
   210  // registered with F.Add and seed inputs from testdata/fuzz/<Name>. In this
   211  // mode, the fuzz test acts much like a regular test, with subtests started
   212  // with F.Fuzz instead of T.Run.
   213  //
   214  // See https://go.dev/doc/fuzz for documentation about fuzzing.
   215  //
   216  // # Skipping
   217  //
   218  // Tests or benchmarks may be skipped at run time with a call to
   219  // the Skip method of *T or *B:
   220  //
   221  //	func TestTimeConsuming(t *testing.T) {
   222  //	    if testing.Short() {
   223  //	        t.Skip("skipping test in short mode.")
   224  //	    }
   225  //	    ...
   226  //	}
   227  //
   228  // The Skip method of *T can be used in a fuzz target if the input is invalid,
   229  // but should not be considered a failing input. For example:
   230  //
   231  //	func FuzzJSONMarshaling(f *testing.F) {
   232  //	    f.Fuzz(func(t *testing.T, b []byte) {
   233  //	        var v interface{}
   234  //	        if err := json.Unmarshal(b, &v); err != nil {
   235  //	            t.Skip()
   236  //	        }
   237  //	        if _, err := json.Marshal(v); err != nil {
   238  //	            t.Error("Marshal: %v", err)
   239  //	        }
   240  //	    })
   241  //	}
   242  //
   243  // # Subtests and Sub-benchmarks
   244  //
   245  // The Run methods of T and B allow defining subtests and sub-benchmarks,
   246  // without having to define separate functions for each. This enables uses
   247  // like table-driven benchmarks and creating hierarchical tests.
   248  // It also provides a way to share common setup and tear-down code:
   249  //
   250  //	func TestFoo(t *testing.T) {
   251  //	    // <setup code>
   252  //	    t.Run("A=1", func(t *testing.T) { ... })
   253  //	    t.Run("A=2", func(t *testing.T) { ... })
   254  //	    t.Run("B=1", func(t *testing.T) { ... })
   255  //	    // <tear-down code>
   256  //	}
   257  //
   258  // Each subtest and sub-benchmark has a unique name: the combination of the name
   259  // of the top-level test and the sequence of names passed to Run, separated by
   260  // slashes, with an optional trailing sequence number for disambiguation.
   261  //
   262  // The argument to the -run, -bench, and -fuzz command-line flags is an unanchored regular
   263  // expression that matches the test's name. For tests with multiple slash-separated
   264  // elements, such as subtests, the argument is itself slash-separated, with
   265  // expressions matching each name element in turn. Because it is unanchored, an
   266  // empty expression matches any string.
   267  // For example, using "matching" to mean "whose name contains":
   268  //
   269  //	go test -run ''        # Run all tests.
   270  //	go test -run Foo       # Run top-level tests matching "Foo", such as "TestFooBar".
   271  //	go test -run Foo/A=    # For top-level tests matching "Foo", run subtests matching "A=".
   272  //	go test -run /A=1      # For all top-level tests, run subtests matching "A=1".
   273  //	go test -fuzz FuzzFoo  # Fuzz the target matching "FuzzFoo"
   274  //
   275  // The -run argument can also be used to run a specific value in the seed
   276  // corpus, for debugging. For example:
   277  //
   278  //	go test -run=FuzzFoo/9ddb952d9814
   279  //
   280  // The -fuzz and -run flags can both be set, in order to fuzz a target but
   281  // skip the execution of all other tests.
   282  //
   283  // Subtests can also be used to control parallelism. A parent test will only
   284  // complete once all of its subtests complete. In this example, all tests are
   285  // run in parallel with each other, and only with each other, regardless of
   286  // other top-level tests that may be defined:
   287  //
   288  //	func TestGroupedParallel(t *testing.T) {
   289  //	    for _, tc := range tests {
   290  //	        tc := tc // capture range variable
   291  //	        t.Run(tc.Name, func(t *testing.T) {
   292  //	            t.Parallel()
   293  //	            ...
   294  //	        })
   295  //	    }
   296  //	}
   297  //
   298  // Run does not return until parallel subtests have completed, providing a way
   299  // to clean up after a group of parallel tests:
   300  //
   301  //	func TestTeardownParallel(t *testing.T) {
   302  //	    // This Run will not return until the parallel tests finish.
   303  //	    t.Run("group", func(t *testing.T) {
   304  //	        t.Run("Test1", parallelTest1)
   305  //	        t.Run("Test2", parallelTest2)
   306  //	        t.Run("Test3", parallelTest3)
   307  //	    })
   308  //	    // <tear-down code>
   309  //	}
   310  //
   311  // # Main
   312  //
   313  // It is sometimes necessary for a test or benchmark program to do extra setup or teardown
   314  // before or after it executes. It is also sometimes necessary to control
   315  // which code runs on the main thread. To support these and other cases,
   316  // if a test file contains a function:
   317  //
   318  //	func TestMain(m *testing.M)
   319  //
   320  // then the generated test will call TestMain(m) instead of running the tests or benchmarks
   321  // directly. TestMain runs in the main goroutine and can do whatever setup
   322  // and teardown is necessary around a call to m.Run. m.Run will return an exit
   323  // code that may be passed to os.Exit. If TestMain returns, the test wrapper
   324  // will pass the result of m.Run to os.Exit itself.
   325  //
   326  // When TestMain is called, flag.Parse has not been run. If TestMain depends on
   327  // command-line flags, including those of the testing package, it should call
   328  // flag.Parse explicitly. Command line flags are always parsed by the time test
   329  // or benchmark functions run.
   330  //
   331  // A simple implementation of TestMain is:
   332  //
   333  //	func TestMain(m *testing.M) {
   334  //		// call flag.Parse() here if TestMain uses flags
   335  //		os.Exit(m.Run())
   336  //	}
   337  //
   338  // TestMain is a low-level primitive and should not be necessary for casual
   339  // testing needs, where ordinary test functions suffice.
   340  package testing
   341  
   342  import (
   343  	"bytes"
   344  	"errors"
   345  	"flag"
   346  	"fmt"
   347  	"internal/race"
   348  	"io"
   349  	"math/rand"
   350  	"os"
   351  	"reflect"
   352  	"runtime"
   353  	"runtime/debug"
   354  	"runtime/trace"
   355  	"strconv"
   356  	"strings"
   357  	"sync"
   358  	"sync/atomic"
   359  	"time"
   360  	"unicode"
   361  	"unicode/utf8"
   362  )
   363  
   364  var initRan bool
   365  
   366  // Init registers testing flags. These flags are automatically registered by
   367  // the "go test" command before running test functions, so Init is only needed
   368  // when calling functions such as Benchmark without using "go test".
   369  //
   370  // Init has no effect if it was already called.
   371  func Init() {
   372  	if initRan {
   373  		return
   374  	}
   375  	initRan = true
   376  	// The short flag requests that tests run more quickly, but its functionality
   377  	// is provided by test writers themselves. The testing package is just its
   378  	// home. The all.bash installation script sets it to make installation more
   379  	// efficient, but by default the flag is off so a plain "go test" will do a
   380  	// full test of the package.
   381  	short = flag.Bool("test.short", false, "run smaller test suite to save time")
   382  
   383  	// The failfast flag requests that test execution stop after the first test failure.
   384  	failFast = flag.Bool("test.failfast", false, "do not start new tests after the first test failure")
   385  
   386  	// The directory in which to create profile files and the like. When run from
   387  	// "go test", the binary always runs in the source directory for the package;
   388  	// this flag lets "go test" tell the binary to write the files in the directory where
   389  	// the "go test" command is run.
   390  	outputDir = flag.String("test.outputdir", "", "write profiles to `dir`")
   391  	// Report as tests are run; default is silent for success.
   392  	chatty = flag.Bool("test.v", false, "verbose: print additional output")
   393  	count = flag.Uint("test.count", 1, "run tests and benchmarks `n` times")
   394  	coverProfile = flag.String("test.coverprofile", "", "write a coverage profile to `file`")
   395  	matchList = flag.String("test.list", "", "list tests, examples, and benchmarks matching `regexp` then exit")
   396  	match = flag.String("test.run", "", "run only tests and examples matching `regexp`")
   397  	memProfile = flag.String("test.memprofile", "", "write an allocation profile to `file`")
   398  	memProfileRate = flag.Int("test.memprofilerate", 0, "set memory allocation profiling `rate` (see runtime.MemProfileRate)")
   399  	cpuProfile = flag.String("test.cpuprofile", "", "write a cpu profile to `file`")
   400  	blockProfile = flag.String("test.blockprofile", "", "write a goroutine blocking profile to `file`")
   401  	blockProfileRate = flag.Int("test.blockprofilerate", 1, "set blocking profile `rate` (see runtime.SetBlockProfileRate)")
   402  	mutexProfile = flag.String("test.mutexprofile", "", "write a mutex contention profile to the named file after execution")
   403  	mutexProfileFraction = flag.Int("test.mutexprofilefraction", 1, "if >= 0, calls runtime.SetMutexProfileFraction()")
   404  	panicOnExit0 = flag.Bool("test.paniconexit0", false, "panic on call to os.Exit(0)")
   405  	traceFile = flag.String("test.trace", "", "write an execution trace to `file`")
   406  	timeout = flag.Duration("test.timeout", 0, "panic test binary after duration `d` (default 0, timeout disabled)")
   407  	cpuListStr = flag.String("test.cpu", "", "comma-separated `list` of cpu counts to run each test with")
   408  	parallel = flag.Int("test.parallel", runtime.GOMAXPROCS(0), "run at most `n` tests in parallel")
   409  	testlog = flag.String("test.testlogfile", "", "write test action log to `file` (for use only by cmd/go)")
   410  	shuffle = flag.String("test.shuffle", "off", "randomize the execution order of tests and benchmarks")
   411  
   412  	initBenchmarkFlags()
   413  	initFuzzFlags()
   414  }
   415  
   416  var (
   417  	// Flags, registered during Init.
   418  	short                *bool
   419  	failFast             *bool
   420  	outputDir            *string
   421  	chatty               *bool
   422  	count                *uint
   423  	coverProfile         *string
   424  	matchList            *string
   425  	match                *string
   426  	memProfile           *string
   427  	memProfileRate       *int
   428  	cpuProfile           *string
   429  	blockProfile         *string
   430  	blockProfileRate     *int
   431  	mutexProfile         *string
   432  	mutexProfileFraction *int
   433  	panicOnExit0         *bool
   434  	traceFile            *string
   435  	timeout              *time.Duration
   436  	cpuListStr           *string
   437  	parallel             *int
   438  	shuffle              *string
   439  	testlog              *string
   440  
   441  	haveExamples bool // are there examples?
   442  
   443  	cpuList     []int
   444  	testlogFile *os.File
   445  
   446  	numFailed uint32 // number of test failures
   447  )
   448  
   449  type chattyPrinter struct {
   450  	w          io.Writer
   451  	lastNameMu sync.Mutex // guards lastName
   452  	lastName   string     // last printed test name in chatty mode
   453  }
   454  
   455  func newChattyPrinter(w io.Writer) *chattyPrinter {
   456  	return &chattyPrinter{w: w}
   457  }
   458  
   459  // Updatef prints a message about the status of the named test to w.
   460  //
   461  // The formatted message must include the test name itself.
   462  func (p *chattyPrinter) Updatef(testName, format string, args ...any) {
   463  	p.lastNameMu.Lock()
   464  	defer p.lastNameMu.Unlock()
   465  
   466  	// Since the message already implies an association with a specific new test,
   467  	// we don't need to check what the old test name was or log an extra CONT line
   468  	// for it. (We're updating it anyway, and the current message already includes
   469  	// the test name.)
   470  	p.lastName = testName
   471  	fmt.Fprintf(p.w, format, args...)
   472  }
   473  
   474  // Printf prints a message, generated by the named test, that does not
   475  // necessarily mention that tests's name itself.
   476  func (p *chattyPrinter) Printf(testName, format string, args ...any) {
   477  	p.lastNameMu.Lock()
   478  	defer p.lastNameMu.Unlock()
   479  
   480  	if p.lastName == "" {
   481  		p.lastName = testName
   482  	} else if p.lastName != testName {
   483  		fmt.Fprintf(p.w, "=== CONT  %s\n", testName)
   484  		p.lastName = testName
   485  	}
   486  
   487  	fmt.Fprintf(p.w, format, args...)
   488  }
   489  
   490  // The maximum number of stack frames to go through when skipping helper functions for
   491  // the purpose of decorating log messages.
   492  const maxStackLen = 50
   493  
   494  // common holds the elements common between T and B and
   495  // captures common methods such as Errorf.
   496  type common struct {
   497  	mu          sync.RWMutex         // guards this group of fields
   498  	output      []byte               // Output generated by test or benchmark.
   499  	w           io.Writer            // For flushToParent.
   500  	ran         bool                 // Test or benchmark (or one of its subtests) was executed.
   501  	failed      bool                 // Test or benchmark has failed.
   502  	skipped     bool                 // Test or benchmark has been skipped.
   503  	done        bool                 // Test is finished and all subtests have completed.
   504  	helperPCs   map[uintptr]struct{} // functions to be skipped when writing file/line info
   505  	helperNames map[string]struct{}  // helperPCs converted to function names
   506  	cleanups    []func()             // optional functions to be called at the end of the test
   507  	cleanupName string               // Name of the cleanup function.
   508  	cleanupPc   []uintptr            // The stack trace at the point where Cleanup was called.
   509  	finished    bool                 // Test function has completed.
   510  	inFuzzFn    bool                 // Whether the fuzz target, if this is one, is running.
   511  
   512  	chatty     *chattyPrinter // A copy of chattyPrinter, if the chatty flag is set.
   513  	bench      bool           // Whether the current test is a benchmark.
   514  	hasSub     int32          // Written atomically.
   515  	raceErrors int            // Number of races detected during test.
   516  	runner     string         // Function name of tRunner running the test.
   517  
   518  	parent   *common
   519  	level    int       // Nesting depth of test or benchmark.
   520  	creator  []uintptr // If level > 0, the stack trace at the point where the parent called t.Run.
   521  	name     string    // Name of test or benchmark.
   522  	start    time.Time // Time test or benchmark started
   523  	duration time.Duration
   524  	barrier  chan bool // To signal parallel subtests they may start. Nil when T.Parallel is not present (B) or not usable (when fuzzing).
   525  	signal   chan bool // To signal a test is done.
   526  	sub      []*T      // Queue of subtests to be run in parallel.
   527  
   528  	tempDirMu  sync.Mutex
   529  	tempDir    string
   530  	tempDirErr error
   531  	tempDirSeq int32
   532  }
   533  
   534  // Short reports whether the -test.short flag is set.
   535  func Short() bool {
   536  	if short == nil {
   537  		panic("testing: Short called before Init")
   538  	}
   539  	// Catch code that calls this from TestMain without first calling flag.Parse.
   540  	if !flag.Parsed() {
   541  		panic("testing: Short called before Parse")
   542  	}
   543  
   544  	return *short
   545  }
   546  
   547  // CoverMode reports what the test coverage mode is set to. The
   548  // values are "set", "count", or "atomic". The return value will be
   549  // empty if test coverage is not enabled.
   550  func CoverMode() string {
   551  	return cover.Mode
   552  }
   553  
   554  // Verbose reports whether the -test.v flag is set.
   555  func Verbose() bool {
   556  	// Same as in Short.
   557  	if chatty == nil {
   558  		panic("testing: Verbose called before Init")
   559  	}
   560  	if !flag.Parsed() {
   561  		panic("testing: Verbose called before Parse")
   562  	}
   563  	return *chatty
   564  }
   565  
   566  func (c *common) checkFuzzFn(name string) {
   567  	if c.inFuzzFn {
   568  		panic(fmt.Sprintf("testing: f.%s was called inside the fuzz target, use t.%s instead", name, name))
   569  	}
   570  }
   571  
   572  // frameSkip searches, starting after skip frames, for the first caller frame
   573  // in a function not marked as a helper and returns that frame.
   574  // The search stops if it finds a tRunner function that
   575  // was the entry point into the test and the test is not a subtest.
   576  // This function must be called with c.mu held.
   577  func (c *common) frameSkip(skip int) runtime.Frame {
   578  	// If the search continues into the parent test, we'll have to hold
   579  	// its mu temporarily. If we then return, we need to unlock it.
   580  	shouldUnlock := false
   581  	defer func() {
   582  		if shouldUnlock {
   583  			c.mu.Unlock()
   584  		}
   585  	}()
   586  	var pc [maxStackLen]uintptr
   587  	// Skip two extra frames to account for this function
   588  	// and runtime.Callers itself.
   589  	n := runtime.Callers(skip+2, pc[:])
   590  	if n == 0 {
   591  		panic("testing: zero callers found")
   592  	}
   593  	frames := runtime.CallersFrames(pc[:n])
   594  	var firstFrame, prevFrame, frame runtime.Frame
   595  	for more := true; more; prevFrame = frame {
   596  		frame, more = frames.Next()
   597  		if frame.Function == "runtime.gopanic" {
   598  			continue
   599  		}
   600  		if frame.Function == c.cleanupName {
   601  			frames = runtime.CallersFrames(c.cleanupPc)
   602  			continue
   603  		}
   604  		if firstFrame.PC == 0 {
   605  			firstFrame = frame
   606  		}
   607  		if frame.Function == c.runner {
   608  			// We've gone up all the way to the tRunner calling
   609  			// the test function (so the user must have
   610  			// called tb.Helper from inside that test function).
   611  			// If this is a top-level test, only skip up to the test function itself.
   612  			// If we're in a subtest, continue searching in the parent test,
   613  			// starting from the point of the call to Run which created this subtest.
   614  			if c.level > 1 {
   615  				frames = runtime.CallersFrames(c.creator)
   616  				parent := c.parent
   617  				// We're no longer looking at the current c after this point,
   618  				// so we should unlock its mu, unless it's the original receiver,
   619  				// in which case our caller doesn't expect us to do that.
   620  				if shouldUnlock {
   621  					c.mu.Unlock()
   622  				}
   623  				c = parent
   624  				// Remember to unlock c.mu when we no longer need it, either
   625  				// because we went up another nesting level, or because we
   626  				// returned.
   627  				shouldUnlock = true
   628  				c.mu.Lock()
   629  				continue
   630  			}
   631  			return prevFrame
   632  		}
   633  		// If more helper PCs have been added since we last did the conversion
   634  		if c.helperNames == nil {
   635  			c.helperNames = make(map[string]struct{})
   636  			for pc := range c.helperPCs {
   637  				c.helperNames[pcToName(pc)] = struct{}{}
   638  			}
   639  		}
   640  		if _, ok := c.helperNames[frame.Function]; !ok {
   641  			// Found a frame that wasn't inside a helper function.
   642  			return frame
   643  		}
   644  	}
   645  	return firstFrame
   646  }
   647  
   648  // decorate prefixes the string with the file and line of the call site
   649  // and inserts the final newline if needed and indentation spaces for formatting.
   650  // This function must be called with c.mu held.
   651  func (c *common) decorate(s string, skip int) string {
   652  	frame := c.frameSkip(skip)
   653  	file := frame.File
   654  	line := frame.Line
   655  	if file != "" {
   656  		// Truncate file name at last file name separator.
   657  		if index := strings.LastIndex(file, "/"); index >= 0 {
   658  			file = file[index+1:]
   659  		} else if index = strings.LastIndex(file, "\\"); index >= 0 {
   660  			file = file[index+1:]
   661  		}
   662  	} else {
   663  		file = "???"
   664  	}
   665  	if line == 0 {
   666  		line = 1
   667  	}
   668  	buf := new(strings.Builder)
   669  	// Every line is indented at least 4 spaces.
   670  	buf.WriteString("    ")
   671  	fmt.Fprintf(buf, "%s:%d: ", file, line)
   672  	lines := strings.Split(s, "\n")
   673  	if l := len(lines); l > 1 && lines[l-1] == "" {
   674  		lines = lines[:l-1]
   675  	}
   676  	for i, line := range lines {
   677  		if i > 0 {
   678  			// Second and subsequent lines are indented an additional 4 spaces.
   679  			buf.WriteString("\n        ")
   680  		}
   681  		buf.WriteString(line)
   682  	}
   683  	buf.WriteByte('\n')
   684  	return buf.String()
   685  }
   686  
   687  // flushToParent writes c.output to the parent after first writing the header
   688  // with the given format and arguments.
   689  func (c *common) flushToParent(testName, format string, args ...any) {
   690  	p := c.parent
   691  	p.mu.Lock()
   692  	defer p.mu.Unlock()
   693  
   694  	c.mu.Lock()
   695  	defer c.mu.Unlock()
   696  
   697  	if len(c.output) > 0 {
   698  		format += "%s"
   699  		args = append(args[:len(args):len(args)], c.output)
   700  		c.output = c.output[:0] // but why?
   701  	}
   702  
   703  	if c.chatty != nil && p.w == c.chatty.w {
   704  		// We're flushing to the actual output, so track that this output is
   705  		// associated with a specific test (and, specifically, that the next output
   706  		// is *not* associated with that test).
   707  		//
   708  		// Moreover, if c.output is non-empty it is important that this write be
   709  		// atomic with respect to the output of other tests, so that we don't end up
   710  		// with confusing '=== CONT' lines in the middle of our '--- PASS' block.
   711  		// Neither humans nor cmd/test2json can parse those easily.
   712  		// (See https://golang.org/issue/40771.)
   713  		c.chatty.Updatef(testName, format, args...)
   714  	} else {
   715  		// We're flushing to the output buffer of the parent test, which will
   716  		// itself follow a test-name header when it is finally flushed to stdout.
   717  		fmt.Fprintf(p.w, format, args...)
   718  	}
   719  }
   720  
   721  type indenter struct {
   722  	c *common
   723  }
   724  
   725  func (w indenter) Write(b []byte) (n int, err error) {
   726  	n = len(b)
   727  	for len(b) > 0 {
   728  		end := bytes.IndexByte(b, '\n')
   729  		if end == -1 {
   730  			end = len(b)
   731  		} else {
   732  			end++
   733  		}
   734  		// An indent of 4 spaces will neatly align the dashes with the status
   735  		// indicator of the parent.
   736  		const indent = "    "
   737  		w.c.output = append(w.c.output, indent...)
   738  		w.c.output = append(w.c.output, b[:end]...)
   739  		b = b[end:]
   740  	}
   741  	return
   742  }
   743  
   744  // fmtDuration returns a string representing d in the form "87.00s".
   745  func fmtDuration(d time.Duration) string {
   746  	return fmt.Sprintf("%.2fs", d.Seconds())
   747  }
   748  
   749  // TB is the interface common to T, B, and F.
   750  type TB interface {
   751  	Cleanup(func())
   752  	Error(args ...any)
   753  	Errorf(format string, args ...any)
   754  	Fail()
   755  	FailNow()
   756  	Failed() bool
   757  	Fatal(args ...any)
   758  	Fatalf(format string, args ...any)
   759  	Helper()
   760  	Log(args ...any)
   761  	Logf(format string, args ...any)
   762  	Name() string
   763  	Setenv(key, value string)
   764  	Skip(args ...any)
   765  	SkipNow()
   766  	Skipf(format string, args ...any)
   767  	Skipped() bool
   768  	TempDir() string
   769  
   770  	// A private method to prevent users implementing the
   771  	// interface and so future additions to it will not
   772  	// violate Go 1 compatibility.
   773  	private()
   774  }
   775  
   776  var _ TB = (*T)(nil)
   777  var _ TB = (*B)(nil)
   778  
   779  // T is a type passed to Test functions to manage test state and support formatted test logs.
   780  //
   781  // A test ends when its Test function returns or calls any of the methods
   782  // FailNow, Fatal, Fatalf, SkipNow, Skip, or Skipf. Those methods, as well as
   783  // the Parallel method, must be called only from the goroutine running the
   784  // Test function.
   785  //
   786  // The other reporting methods, such as the variations of Log and Error,
   787  // may be called simultaneously from multiple goroutines.
   788  type T struct {
   789  	common
   790  	isParallel bool
   791  	isEnvSet   bool
   792  	context    *testContext // For running tests and subtests.
   793  }
   794  
   795  func (c *common) private() {}
   796  
   797  // Name returns the name of the running (sub-) test or benchmark.
   798  //
   799  // The name will include the name of the test along with the names of
   800  // any nested sub-tests. If two sibling sub-tests have the same name,
   801  // Name will append a suffix to guarantee the returned name is unique.
   802  func (c *common) Name() string {
   803  	return c.name
   804  }
   805  
   806  func (c *common) setRan() {
   807  	if c.parent != nil {
   808  		c.parent.setRan()
   809  	}
   810  	c.mu.Lock()
   811  	defer c.mu.Unlock()
   812  	c.ran = true
   813  }
   814  
   815  // Fail marks the function as having failed but continues execution.
   816  func (c *common) Fail() {
   817  	if c.parent != nil {
   818  		c.parent.Fail()
   819  	}
   820  	c.mu.Lock()
   821  	defer c.mu.Unlock()
   822  	// c.done needs to be locked to synchronize checks to c.done in parent tests.
   823  	if c.done {
   824  		panic("Fail in goroutine after " + c.name + " has completed")
   825  	}
   826  	c.failed = true
   827  }
   828  
   829  // Failed reports whether the function has failed.
   830  func (c *common) Failed() bool {
   831  	c.mu.RLock()
   832  	failed := c.failed
   833  	c.mu.RUnlock()
   834  	return failed || c.raceErrors+race.Errors() > 0
   835  }
   836  
   837  // FailNow marks the function as having failed and stops its execution
   838  // by calling runtime.Goexit (which then runs all deferred calls in the
   839  // current goroutine).
   840  // Execution will continue at the next test or benchmark.
   841  // FailNow must be called from the goroutine running the
   842  // test or benchmark function, not from other goroutines
   843  // created during the test. Calling FailNow does not stop
   844  // those other goroutines.
   845  func (c *common) FailNow() {
   846  	c.checkFuzzFn("FailNow")
   847  	c.Fail()
   848  
   849  	// Calling runtime.Goexit will exit the goroutine, which
   850  	// will run the deferred functions in this goroutine,
   851  	// which will eventually run the deferred lines in tRunner,
   852  	// which will signal to the test loop that this test is done.
   853  	//
   854  	// A previous version of this code said:
   855  	//
   856  	//	c.duration = ...
   857  	//	c.signal <- c.self
   858  	//	runtime.Goexit()
   859  	//
   860  	// This previous version duplicated code (those lines are in
   861  	// tRunner no matter what), but worse the goroutine teardown
   862  	// implicit in runtime.Goexit was not guaranteed to complete
   863  	// before the test exited. If a test deferred an important cleanup
   864  	// function (like removing temporary files), there was no guarantee
   865  	// it would run on a test failure. Because we send on c.signal during
   866  	// a top-of-stack deferred function now, we know that the send
   867  	// only happens after any other stacked defers have completed.
   868  	c.mu.Lock()
   869  	c.finished = true
   870  	c.mu.Unlock()
   871  	runtime.Goexit()
   872  }
   873  
   874  // log generates the output. It's always at the same stack depth.
   875  func (c *common) log(s string) {
   876  	c.logDepth(s, 3) // logDepth + log + public function
   877  }
   878  
   879  // logDepth generates the output at an arbitrary stack depth.
   880  func (c *common) logDepth(s string, depth int) {
   881  	c.mu.Lock()
   882  	defer c.mu.Unlock()
   883  	if c.done {
   884  		// This test has already finished. Try and log this message
   885  		// with our parent. If we don't have a parent, panic.
   886  		for parent := c.parent; parent != nil; parent = parent.parent {
   887  			parent.mu.Lock()
   888  			defer parent.mu.Unlock()
   889  			if !parent.done {
   890  				parent.output = append(parent.output, parent.decorate(s, depth+1)...)
   891  				return
   892  			}
   893  		}
   894  		panic("Log in goroutine after " + c.name + " has completed: " + s)
   895  	} else {
   896  		if c.chatty != nil {
   897  			if c.bench {
   898  				// Benchmarks don't print === CONT, so we should skip the test
   899  				// printer and just print straight to stdout.
   900  				fmt.Print(c.decorate(s, depth+1))
   901  			} else {
   902  				c.chatty.Printf(c.name, "%s", c.decorate(s, depth+1))
   903  			}
   904  
   905  			return
   906  		}
   907  		c.output = append(c.output, c.decorate(s, depth+1)...)
   908  	}
   909  }
   910  
   911  // Log formats its arguments using default formatting, analogous to Println,
   912  // and records the text in the error log. For tests, the text will be printed only if
   913  // the test fails or the -test.v flag is set. For benchmarks, the text is always
   914  // printed to avoid having performance depend on the value of the -test.v flag.
   915  func (c *common) Log(args ...any) {
   916  	c.checkFuzzFn("Log")
   917  	c.log(fmt.Sprintln(args...))
   918  }
   919  
   920  // Logf formats its arguments according to the format, analogous to Printf, and
   921  // records the text in the error log. A final newline is added if not provided. For
   922  // tests, the text will be printed only if the test fails or the -test.v flag is
   923  // set. For benchmarks, the text is always printed to avoid having performance
   924  // depend on the value of the -test.v flag.
   925  func (c *common) Logf(format string, args ...any) {
   926  	c.checkFuzzFn("Logf")
   927  	c.log(fmt.Sprintf(format, args...))
   928  }
   929  
   930  // Error is equivalent to Log followed by Fail.
   931  func (c *common) Error(args ...any) {
   932  	c.checkFuzzFn("Error")
   933  	c.log(fmt.Sprintln(args...))
   934  	c.Fail()
   935  }
   936  
   937  // Errorf is equivalent to Logf followed by Fail.
   938  func (c *common) Errorf(format string, args ...any) {
   939  	c.checkFuzzFn("Errorf")
   940  	c.log(fmt.Sprintf(format, args...))
   941  	c.Fail()
   942  }
   943  
   944  // Fatal is equivalent to Log followed by FailNow.
   945  func (c *common) Fatal(args ...any) {
   946  	c.checkFuzzFn("Fatal")
   947  	c.log(fmt.Sprintln(args...))
   948  	c.FailNow()
   949  }
   950  
   951  // Fatalf is equivalent to Logf followed by FailNow.
   952  func (c *common) Fatalf(format string, args ...any) {
   953  	c.checkFuzzFn("Fatalf")
   954  	c.log(fmt.Sprintf(format, args...))
   955  	c.FailNow()
   956  }
   957  
   958  // Skip is equivalent to Log followed by SkipNow.
   959  func (c *common) Skip(args ...any) {
   960  	c.checkFuzzFn("Skip")
   961  	c.log(fmt.Sprintln(args...))
   962  	c.SkipNow()
   963  }
   964  
   965  // Skipf is equivalent to Logf followed by SkipNow.
   966  func (c *common) Skipf(format string, args ...any) {
   967  	c.checkFuzzFn("Skipf")
   968  	c.log(fmt.Sprintf(format, args...))
   969  	c.SkipNow()
   970  }
   971  
   972  // SkipNow marks the test as having been skipped and stops its execution
   973  // by calling runtime.Goexit.
   974  // If a test fails (see Error, Errorf, Fail) and is then skipped,
   975  // it is still considered to have failed.
   976  // Execution will continue at the next test or benchmark. See also FailNow.
   977  // SkipNow must be called from the goroutine running the test, not from
   978  // other goroutines created during the test. Calling SkipNow does not stop
   979  // those other goroutines.
   980  func (c *common) SkipNow() {
   981  	c.checkFuzzFn("SkipNow")
   982  	c.mu.Lock()
   983  	c.skipped = true
   984  	c.finished = true
   985  	c.mu.Unlock()
   986  	runtime.Goexit()
   987  }
   988  
   989  // Skipped reports whether the test was skipped.
   990  func (c *common) Skipped() bool {
   991  	c.mu.RLock()
   992  	defer c.mu.RUnlock()
   993  	return c.skipped
   994  }
   995  
   996  // Helper marks the calling function as a test helper function.
   997  // When printing file and line information, that function will be skipped.
   998  // Helper may be called simultaneously from multiple goroutines.
   999  func (c *common) Helper() {
  1000  	c.mu.Lock()
  1001  	defer c.mu.Unlock()
  1002  	if c.helperPCs == nil {
  1003  		c.helperPCs = make(map[uintptr]struct{})
  1004  	}
  1005  	// repeating code from callerName here to save walking a stack frame
  1006  	var pc [1]uintptr
  1007  	n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper
  1008  	if n == 0 {
  1009  		panic("testing: zero callers found")
  1010  	}
  1011  	if _, found := c.helperPCs[pc[0]]; !found {
  1012  		c.helperPCs[pc[0]] = struct{}{}
  1013  		c.helperNames = nil // map will be recreated next time it is needed
  1014  	}
  1015  }
  1016  
  1017  // Cleanup registers a function to be called when the test (or subtest) and all its
  1018  // subtests complete. Cleanup functions will be called in last added,
  1019  // first called order.
  1020  func (c *common) Cleanup(f func()) {
  1021  	c.checkFuzzFn("Cleanup")
  1022  	var pc [maxStackLen]uintptr
  1023  	// Skip two extra frames to account for this function and runtime.Callers itself.
  1024  	n := runtime.Callers(2, pc[:])
  1025  	cleanupPc := pc[:n]
  1026  
  1027  	fn := func() {
  1028  		defer func() {
  1029  			c.mu.Lock()
  1030  			defer c.mu.Unlock()
  1031  			c.cleanupName = ""
  1032  			c.cleanupPc = nil
  1033  		}()
  1034  
  1035  		name := callerName(0)
  1036  		c.mu.Lock()
  1037  		c.cleanupName = name
  1038  		c.cleanupPc = cleanupPc
  1039  		c.mu.Unlock()
  1040  
  1041  		f()
  1042  	}
  1043  
  1044  	c.mu.Lock()
  1045  	defer c.mu.Unlock()
  1046  	c.cleanups = append(c.cleanups, fn)
  1047  }
  1048  
  1049  // TempDir returns a temporary directory for the test to use.
  1050  // The directory is automatically removed by Cleanup when the test and
  1051  // all its subtests complete.
  1052  // Each subsequent call to t.TempDir returns a unique directory;
  1053  // if the directory creation fails, TempDir terminates the test by calling Fatal.
  1054  func (c *common) TempDir() string {
  1055  	c.checkFuzzFn("TempDir")
  1056  	// Use a single parent directory for all the temporary directories
  1057  	// created by a test, each numbered sequentially.
  1058  	c.tempDirMu.Lock()
  1059  	var nonExistent bool
  1060  	if c.tempDir == "" { // Usually the case with js/wasm
  1061  		nonExistent = true
  1062  	} else {
  1063  		_, err := os.Stat(c.tempDir)
  1064  		nonExistent = os.IsNotExist(err)
  1065  		if err != nil && !nonExistent {
  1066  			c.Fatalf("TempDir: %v", err)
  1067  		}
  1068  	}
  1069  
  1070  	if nonExistent {
  1071  		c.Helper()
  1072  
  1073  		// Drop unusual characters (such as path separators or
  1074  		// characters interacting with globs) from the directory name to
  1075  		// avoid surprising os.MkdirTemp behavior.
  1076  		mapper := func(r rune) rune {
  1077  			if r < utf8.RuneSelf {
  1078  				const allowed = "!#$%&()+,-.=@^_{}~ "
  1079  				if '0' <= r && r <= '9' ||
  1080  					'a' <= r && r <= 'z' ||
  1081  					'A' <= r && r <= 'Z' {
  1082  					return r
  1083  				}
  1084  				if strings.ContainsRune(allowed, r) {
  1085  					return r
  1086  				}
  1087  			} else if unicode.IsLetter(r) || unicode.IsNumber(r) {
  1088  				return r
  1089  			}
  1090  			return -1
  1091  		}
  1092  		pattern := strings.Map(mapper, c.Name())
  1093  		c.tempDir, c.tempDirErr = os.MkdirTemp("", pattern)
  1094  		if c.tempDirErr == nil {
  1095  			c.Cleanup(func() {
  1096  				if err := removeAll(c.tempDir); err != nil {
  1097  					c.Errorf("TempDir RemoveAll cleanup: %v", err)
  1098  				}
  1099  			})
  1100  		}
  1101  	}
  1102  	c.tempDirMu.Unlock()
  1103  
  1104  	if c.tempDirErr != nil {
  1105  		c.Fatalf("TempDir: %v", c.tempDirErr)
  1106  	}
  1107  	seq := atomic.AddInt32(&c.tempDirSeq, 1)
  1108  	dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)
  1109  	if err := os.Mkdir(dir, 0777); err != nil {
  1110  		c.Fatalf("TempDir: %v", err)
  1111  	}
  1112  	return dir
  1113  }
  1114  
  1115  // removeAll is like os.RemoveAll, but retries Windows "Access is denied."
  1116  // errors up to an arbitrary timeout.
  1117  //
  1118  // Those errors have been known to occur spuriously on at least the
  1119  // windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur
  1120  // legitimately if the test leaves behind a temp file that either is still open
  1121  // or the test otherwise lacks permission to delete. In the case of legitimate
  1122  // failures, a failing test may take a bit longer to fail, but once the test is
  1123  // fixed the extra latency will go away.
  1124  func removeAll(path string) error {
  1125  	const arbitraryTimeout = 2 * time.Second
  1126  	var (
  1127  		start     time.Time
  1128  		nextSleep = 1 * time.Millisecond
  1129  	)
  1130  	for {
  1131  		err := os.RemoveAll(path)
  1132  		if !isWindowsRetryable(err) {
  1133  			return err
  1134  		}
  1135  		if start.IsZero() {
  1136  			start = time.Now()
  1137  		} else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {
  1138  			return err
  1139  		}
  1140  		time.Sleep(nextSleep)
  1141  		nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))
  1142  	}
  1143  }
  1144  
  1145  // Setenv calls os.Setenv(key, value) and uses Cleanup to
  1146  // restore the environment variable to its original value
  1147  // after the test.
  1148  //
  1149  // This cannot be used in parallel tests.
  1150  func (c *common) Setenv(key, value string) {
  1151  	c.checkFuzzFn("Setenv")
  1152  	prevValue, ok := os.LookupEnv(key)
  1153  
  1154  	if err := os.Setenv(key, value); err != nil {
  1155  		c.Fatalf("cannot set environment variable: %v", err)
  1156  	}
  1157  
  1158  	if ok {
  1159  		c.Cleanup(func() {
  1160  			os.Setenv(key, prevValue)
  1161  		})
  1162  	} else {
  1163  		c.Cleanup(func() {
  1164  			os.Unsetenv(key)
  1165  		})
  1166  	}
  1167  }
  1168  
  1169  // panicHanding is an argument to runCleanup.
  1170  type panicHandling int
  1171  
  1172  const (
  1173  	normalPanic panicHandling = iota
  1174  	recoverAndReturnPanic
  1175  )
  1176  
  1177  // runCleanup is called at the end of the test.
  1178  // If catchPanic is true, this will catch panics, and return the recovered
  1179  // value if any.
  1180  func (c *common) runCleanup(ph panicHandling) (panicVal any) {
  1181  	if ph == recoverAndReturnPanic {
  1182  		defer func() {
  1183  			panicVal = recover()
  1184  		}()
  1185  	}
  1186  
  1187  	// Make sure that if a cleanup function panics,
  1188  	// we still run the remaining cleanup functions.
  1189  	defer func() {
  1190  		c.mu.Lock()
  1191  		recur := len(c.cleanups) > 0
  1192  		c.mu.Unlock()
  1193  		if recur {
  1194  			c.runCleanup(normalPanic)
  1195  		}
  1196  	}()
  1197  
  1198  	for {
  1199  		var cleanup func()
  1200  		c.mu.Lock()
  1201  		if len(c.cleanups) > 0 {
  1202  			last := len(c.cleanups) - 1
  1203  			cleanup = c.cleanups[last]
  1204  			c.cleanups = c.cleanups[:last]
  1205  		}
  1206  		c.mu.Unlock()
  1207  		if cleanup == nil {
  1208  			return nil
  1209  		}
  1210  		cleanup()
  1211  	}
  1212  }
  1213  
  1214  // callerName gives the function name (qualified with a package path)
  1215  // for the caller after skip frames (where 0 means the current function).
  1216  func callerName(skip int) string {
  1217  	var pc [1]uintptr
  1218  	n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName
  1219  	if n == 0 {
  1220  		panic("testing: zero callers found")
  1221  	}
  1222  	return pcToName(pc[0])
  1223  }
  1224  
  1225  func pcToName(pc uintptr) string {
  1226  	pcs := []uintptr{pc}
  1227  	frames := runtime.CallersFrames(pcs)
  1228  	frame, _ := frames.Next()
  1229  	return frame.Function
  1230  }
  1231  
  1232  // Parallel signals that this test is to be run in parallel with (and only with)
  1233  // other parallel tests. When a test is run multiple times due to use of
  1234  // -test.count or -test.cpu, multiple instances of a single test never run in
  1235  // parallel with each other.
  1236  func (t *T) Parallel() {
  1237  	if t.isParallel {
  1238  		panic("testing: t.Parallel called multiple times")
  1239  	}
  1240  	if t.isEnvSet {
  1241  		panic("testing: t.Parallel called after t.Setenv; cannot set environment variables in parallel tests")
  1242  	}
  1243  	t.isParallel = true
  1244  	if t.parent.barrier == nil {
  1245  		// T.Parallel has no effect when fuzzing.
  1246  		// Multiple processes may run in parallel, but only one input can run at a
  1247  		// time per process so we can attribute crashes to specific inputs.
  1248  		return
  1249  	}
  1250  
  1251  	// We don't want to include the time we spend waiting for serial tests
  1252  	// in the test duration. Record the elapsed time thus far and reset the
  1253  	// timer afterwards.
  1254  	t.duration += time.Since(t.start)
  1255  
  1256  	// Add to the list of tests to be released by the parent.
  1257  	t.parent.sub = append(t.parent.sub, t)
  1258  	t.raceErrors += race.Errors()
  1259  
  1260  	if t.chatty != nil {
  1261  		// Unfortunately, even though PAUSE indicates that the named test is *no
  1262  		// longer* running, cmd/test2json interprets it as changing the active test
  1263  		// for the purpose of log parsing. We could fix cmd/test2json, but that
  1264  		// won't fix existing deployments of third-party tools that already shell
  1265  		// out to older builds of cmd/test2json — so merely fixing cmd/test2json
  1266  		// isn't enough for now.
  1267  		t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)
  1268  	}
  1269  
  1270  	t.signal <- true   // Release calling test.
  1271  	<-t.parent.barrier // Wait for the parent test to complete.
  1272  	t.context.waitParallel()
  1273  
  1274  	if t.chatty != nil {
  1275  		t.chatty.Updatef(t.name, "=== CONT  %s\n", t.name)
  1276  	}
  1277  
  1278  	t.start = time.Now()
  1279  	t.raceErrors += -race.Errors()
  1280  }
  1281  
  1282  // Setenv calls os.Setenv(key, value) and uses Cleanup to
  1283  // restore the environment variable to its original value
  1284  // after the test.
  1285  //
  1286  // This cannot be used in parallel tests.
  1287  func (t *T) Setenv(key, value string) {
  1288  	if t.isParallel {
  1289  		panic("testing: t.Setenv called after t.Parallel; cannot set environment variables in parallel tests")
  1290  	}
  1291  
  1292  	t.isEnvSet = true
  1293  
  1294  	t.common.Setenv(key, value)
  1295  }
  1296  
  1297  // InternalTest is an internal type but exported because it is cross-package;
  1298  // it is part of the implementation of the "go test" command.
  1299  type InternalTest struct {
  1300  	Name string
  1301  	F    func(*T)
  1302  }
  1303  
  1304  var errNilPanicOrGoexit = errors.New("test executed panic(nil) or runtime.Goexit")
  1305  
  1306  func tRunner(t *T, fn func(t *T)) {
  1307  	t.runner = callerName(0)
  1308  
  1309  	// When this goroutine is done, either because fn(t)
  1310  	// returned normally or because a test failure triggered
  1311  	// a call to runtime.Goexit, record the duration and send
  1312  	// a signal saying that the test is done.
  1313  	defer func() {
  1314  		if t.Failed() {
  1315  			atomic.AddUint32(&numFailed, 1)
  1316  		}
  1317  
  1318  		if t.raceErrors+race.Errors() > 0 {
  1319  			t.Errorf("race detected during execution of test")
  1320  		}
  1321  
  1322  		// Check if the test panicked or Goexited inappropriately.
  1323  		//
  1324  		// If this happens in a normal test, print output but continue panicking.
  1325  		// tRunner is called in its own goroutine, so this terminates the process.
  1326  		//
  1327  		// If this happens while fuzzing, recover from the panic and treat it like a
  1328  		// normal failure. It's important that the process keeps running in order to
  1329  		// find short inputs that cause panics.
  1330  		err := recover()
  1331  		signal := true
  1332  
  1333  		t.mu.RLock()
  1334  		finished := t.finished
  1335  		t.mu.RUnlock()
  1336  		if !finished && err == nil {
  1337  			err = errNilPanicOrGoexit
  1338  			for p := t.parent; p != nil; p = p.parent {
  1339  				p.mu.RLock()
  1340  				finished = p.finished
  1341  				p.mu.RUnlock()
  1342  				if finished {
  1343  					t.Errorf("%v: subtest may have called FailNow on a parent test", err)
  1344  					err = nil
  1345  					signal = false
  1346  					break
  1347  				}
  1348  			}
  1349  		}
  1350  
  1351  		if err != nil && t.context.isFuzzing {
  1352  			prefix := "panic: "
  1353  			if err == errNilPanicOrGoexit {
  1354  				prefix = ""
  1355  			}
  1356  			t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack()))
  1357  			t.mu.Lock()
  1358  			t.finished = true
  1359  			t.mu.Unlock()
  1360  			err = nil
  1361  		}
  1362  
  1363  		// Use a deferred call to ensure that we report that the test is
  1364  		// complete even if a cleanup function calls t.FailNow. See issue 41355.
  1365  		didPanic := false
  1366  		defer func() {
  1367  			if didPanic {
  1368  				return
  1369  			}
  1370  			if err != nil {
  1371  				panic(err)
  1372  			}
  1373  			// Only report that the test is complete if it doesn't panic,
  1374  			// as otherwise the test binary can exit before the panic is
  1375  			// reported to the user. See issue 41479.
  1376  			t.signal <- signal
  1377  		}()
  1378  
  1379  		doPanic := func(err any) {
  1380  			t.Fail()
  1381  			if r := t.runCleanup(recoverAndReturnPanic); r != nil {
  1382  				t.Logf("cleanup panicked with %v", r)
  1383  			}
  1384  			// Flush the output log up to the root before dying.
  1385  			for root := &t.common; root.parent != nil; root = root.parent {
  1386  				root.mu.Lock()
  1387  				root.duration += time.Since(root.start)
  1388  				d := root.duration
  1389  				root.mu.Unlock()
  1390  				root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d))
  1391  				if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil {
  1392  					fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r)
  1393  				}
  1394  			}
  1395  			didPanic = true
  1396  			panic(err)
  1397  		}
  1398  		if err != nil {
  1399  			doPanic(err)
  1400  		}
  1401  
  1402  		t.duration += time.Since(t.start)
  1403  
  1404  		if len(t.sub) > 0 {
  1405  			// Run parallel subtests.
  1406  			// Decrease the running count for this test.
  1407  			t.context.release()
  1408  			// Release the parallel subtests.
  1409  			close(t.barrier)
  1410  			// Wait for subtests to complete.
  1411  			for _, sub := range t.sub {
  1412  				<-sub.signal
  1413  			}
  1414  			cleanupStart := time.Now()
  1415  			err := t.runCleanup(recoverAndReturnPanic)
  1416  			t.duration += time.Since(cleanupStart)
  1417  			if err != nil {
  1418  				doPanic(err)
  1419  			}
  1420  			if !t.isParallel {
  1421  				// Reacquire the count for sequential tests. See comment in Run.
  1422  				t.context.waitParallel()
  1423  			}
  1424  		} else if t.isParallel {
  1425  			// Only release the count for this test if it was run as a parallel
  1426  			// test. See comment in Run method.
  1427  			t.context.release()
  1428  		}
  1429  		t.report() // Report after all subtests have finished.
  1430  
  1431  		// Do not lock t.done to allow race detector to detect race in case
  1432  		// the user does not appropriately synchronize a goroutine.
  1433  		t.done = true
  1434  		if t.parent != nil && atomic.LoadInt32(&t.hasSub) == 0 {
  1435  			t.setRan()
  1436  		}
  1437  	}()
  1438  	defer func() {
  1439  		if len(t.sub) == 0 {
  1440  			t.runCleanup(normalPanic)
  1441  		}
  1442  	}()
  1443  
  1444  	t.start = time.Now()
  1445  	t.raceErrors = -race.Errors()
  1446  	fn(t)
  1447  
  1448  	// code beyond here will not be executed when FailNow is invoked
  1449  	t.mu.Lock()
  1450  	t.finished = true
  1451  	t.mu.Unlock()
  1452  }
  1453  
  1454  // Run runs f as a subtest of t called name. It runs f in a separate goroutine
  1455  // and blocks until f returns or calls t.Parallel to become a parallel test.
  1456  // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
  1457  //
  1458  // Run may be called simultaneously from multiple goroutines, but all such calls
  1459  // must return before the outer test function for t returns.
  1460  func (t *T) Run(name string, f func(t *T)) bool {
  1461  	atomic.StoreInt32(&t.hasSub, 1)
  1462  	testName, ok, _ := t.context.match.fullName(&t.common, name)
  1463  	if !ok || shouldFailFast() {
  1464  		return true
  1465  	}
  1466  	// Record the stack trace at the point of this call so that if the subtest
  1467  	// function - which runs in a separate stack - is marked as a helper, we can
  1468  	// continue walking the stack into the parent test.
  1469  	var pc [maxStackLen]uintptr
  1470  	n := runtime.Callers(2, pc[:])
  1471  	t = &T{
  1472  		common: common{
  1473  			barrier: make(chan bool),
  1474  			signal:  make(chan bool, 1),
  1475  			name:    testName,
  1476  			parent:  &t.common,
  1477  			level:   t.level + 1,
  1478  			creator: pc[:n],
  1479  			chatty:  t.chatty,
  1480  		},
  1481  		context: t.context,
  1482  	}
  1483  	t.w = indenter{&t.common}
  1484  
  1485  	if t.chatty != nil {
  1486  		t.chatty.Updatef(t.name, "=== RUN   %s\n", t.name)
  1487  	}
  1488  	// Instead of reducing the running count of this test before calling the
  1489  	// tRunner and increasing it afterwards, we rely on tRunner keeping the
  1490  	// count correct. This ensures that a sequence of sequential tests runs
  1491  	// without being preempted, even when their parent is a parallel test. This
  1492  	// may especially reduce surprises if *parallel == 1.
  1493  	go tRunner(t, f)
  1494  	if !<-t.signal {
  1495  		// At this point, it is likely that FailNow was called on one of the
  1496  		// parent tests by one of the subtests. Continue aborting up the chain.
  1497  		runtime.Goexit()
  1498  	}
  1499  	return !t.failed
  1500  }
  1501  
  1502  // Deadline reports the time at which the test binary will have
  1503  // exceeded the timeout specified by the -timeout flag.
  1504  //
  1505  // The ok result is false if the -timeout flag indicates “no timeout” (0).
  1506  func (t *T) Deadline() (deadline time.Time, ok bool) {
  1507  	deadline = t.context.deadline
  1508  	return deadline, !deadline.IsZero()
  1509  }
  1510  
  1511  // testContext holds all fields that are common to all tests. This includes
  1512  // synchronization primitives to run at most *parallel tests.
  1513  type testContext struct {
  1514  	match    *matcher
  1515  	deadline time.Time
  1516  
  1517  	// isFuzzing is true in the context used when generating random inputs
  1518  	// for fuzz targets. isFuzzing is false when running normal tests and
  1519  	// when running fuzz tests as unit tests (without -fuzz or when -fuzz
  1520  	// does not match).
  1521  	isFuzzing bool
  1522  
  1523  	mu sync.Mutex
  1524  
  1525  	// Channel used to signal tests that are ready to be run in parallel.
  1526  	startParallel chan bool
  1527  
  1528  	// running is the number of tests currently running in parallel.
  1529  	// This does not include tests that are waiting for subtests to complete.
  1530  	running int
  1531  
  1532  	// numWaiting is the number tests waiting to be run in parallel.
  1533  	numWaiting int
  1534  
  1535  	// maxParallel is a copy of the parallel flag.
  1536  	maxParallel int
  1537  }
  1538  
  1539  func newTestContext(maxParallel int, m *matcher) *testContext {
  1540  	return &testContext{
  1541  		match:         m,
  1542  		startParallel: make(chan bool),
  1543  		maxParallel:   maxParallel,
  1544  		running:       1, // Set the count to 1 for the main (sequential) test.
  1545  	}
  1546  }
  1547  
  1548  func (c *testContext) waitParallel() {
  1549  	c.mu.Lock()
  1550  	if c.running < c.maxParallel {
  1551  		c.running++
  1552  		c.mu.Unlock()
  1553  		return
  1554  	}
  1555  	c.numWaiting++
  1556  	c.mu.Unlock()
  1557  	<-c.startParallel
  1558  }
  1559  
  1560  func (c *testContext) release() {
  1561  	c.mu.Lock()
  1562  	if c.numWaiting == 0 {
  1563  		c.running--
  1564  		c.mu.Unlock()
  1565  		return
  1566  	}
  1567  	c.numWaiting--
  1568  	c.mu.Unlock()
  1569  	c.startParallel <- true // Pick a waiting test to be run.
  1570  }
  1571  
  1572  // No one should be using func Main anymore.
  1573  // See the doc comment on func Main and use MainStart instead.
  1574  var errMain = errors.New("testing: unexpected use of func Main")
  1575  
  1576  type matchStringOnly func(pat, str string) (bool, error)
  1577  
  1578  func (f matchStringOnly) MatchString(pat, str string) (bool, error)   { return f(pat, str) }
  1579  func (f matchStringOnly) StartCPUProfile(w io.Writer) error           { return errMain }
  1580  func (f matchStringOnly) StopCPUProfile()                             {}
  1581  func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain }
  1582  func (f matchStringOnly) ImportPath() string                          { return "" }
  1583  func (f matchStringOnly) StartTestLog(io.Writer)                      {}
  1584  func (f matchStringOnly) StopTestLog() error                          { return errMain }
  1585  func (f matchStringOnly) SetPanicOnExit0(bool)                        {}
  1586  func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error {
  1587  	return errMain
  1588  }
  1589  func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain }
  1590  func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) {
  1591  	return nil, errMain
  1592  }
  1593  func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil }
  1594  func (f matchStringOnly) ResetCoverage()                          {}
  1595  func (f matchStringOnly) SnapshotCoverage()                       {}
  1596  
  1597  // Main is an internal function, part of the implementation of the "go test" command.
  1598  // It was exported because it is cross-package and predates "internal" packages.
  1599  // It is no longer used by "go test" but preserved, as much as possible, for other
  1600  // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
  1601  // new functionality is added to the testing package.
  1602  // Systems simulating "go test" should be updated to use MainStart.
  1603  func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {
  1604  	os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run())
  1605  }
  1606  
  1607  // M is a type passed to a TestMain function to run the actual tests.
  1608  type M struct {
  1609  	deps        testDeps
  1610  	tests       []InternalTest
  1611  	benchmarks  []InternalBenchmark
  1612  	fuzzTargets []InternalFuzzTarget
  1613  	examples    []InternalExample
  1614  
  1615  	timer     *time.Timer
  1616  	afterOnce sync.Once
  1617  
  1618  	numRun int
  1619  
  1620  	// value to pass to os.Exit, the outer test func main
  1621  	// harness calls os.Exit with this code. See #34129.
  1622  	exitCode int
  1623  }
  1624  
  1625  // testDeps is an internal interface of functionality that is
  1626  // passed into this package by a test's generated main package.
  1627  // The canonical implementation of this interface is
  1628  // testing/internal/testdeps's TestDeps.
  1629  type testDeps interface {
  1630  	ImportPath() string
  1631  	MatchString(pat, str string) (bool, error)
  1632  	SetPanicOnExit0(bool)
  1633  	StartCPUProfile(io.Writer) error
  1634  	StopCPUProfile()
  1635  	StartTestLog(io.Writer)
  1636  	StopTestLog() error
  1637  	WriteProfileTo(string, io.Writer, int) error
  1638  	CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error
  1639  	RunFuzzWorker(func(corpusEntry) error) error
  1640  	ReadCorpus(string, []reflect.Type) ([]corpusEntry, error)
  1641  	CheckCorpus([]any, []reflect.Type) error
  1642  	ResetCoverage()
  1643  	SnapshotCoverage()
  1644  }
  1645  
  1646  // MainStart is meant for use by tests generated by 'go test'.
  1647  // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
  1648  // It may change signature from release to release.
  1649  func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M {
  1650  	Init()
  1651  	return &M{
  1652  		deps:        deps,
  1653  		tests:       tests,
  1654  		benchmarks:  benchmarks,
  1655  		fuzzTargets: fuzzTargets,
  1656  		examples:    examples,
  1657  	}
  1658  }
  1659  
  1660  // Run runs the tests. It returns an exit code to pass to os.Exit.
  1661  func (m *M) Run() (code int) {
  1662  	defer func() {
  1663  		code = m.exitCode
  1664  	}()
  1665  
  1666  	// Count the number of calls to m.Run.
  1667  	// We only ever expected 1, but we didn't enforce that,
  1668  	// and now there are tests in the wild that call m.Run multiple times.
  1669  	// Sigh. golang.org/issue/23129.
  1670  	m.numRun++
  1671  
  1672  	// TestMain may have already called flag.Parse.
  1673  	if !flag.Parsed() {
  1674  		flag.Parse()
  1675  	}
  1676  
  1677  	if *parallel < 1 {
  1678  		fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer")
  1679  		flag.Usage()
  1680  		m.exitCode = 2
  1681  		return
  1682  	}
  1683  	if *matchFuzz != "" && *fuzzCacheDir == "" {
  1684  		fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set")
  1685  		flag.Usage()
  1686  		m.exitCode = 2
  1687  		return
  1688  	}
  1689  
  1690  	if len(*matchList) != 0 {
  1691  		listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples)
  1692  		m.exitCode = 0
  1693  		return
  1694  	}
  1695  
  1696  	if *shuffle != "off" {
  1697  		var n int64
  1698  		var err error
  1699  		if *shuffle == "on" {
  1700  			n = time.Now().UnixNano()
  1701  		} else {
  1702  			n, err = strconv.ParseInt(*shuffle, 10, 64)
  1703  			if err != nil {
  1704  				fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err)
  1705  				m.exitCode = 2
  1706  				return
  1707  			}
  1708  		}
  1709  		fmt.Println("-test.shuffle", n)
  1710  		rng := rand.New(rand.NewSource(n))
  1711  		rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] })
  1712  		rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] })
  1713  	}
  1714  
  1715  	parseCpuList()
  1716  
  1717  	m.before()
  1718  	defer m.after()
  1719  
  1720  	// Run tests, examples, and benchmarks unless this is a fuzz worker process.
  1721  	// Workers start after this is done by their parent process, and they should
  1722  	// not repeat this work.
  1723  	if !*isFuzzWorker {
  1724  		deadline := m.startAlarm()
  1725  		haveExamples = len(m.examples) > 0
  1726  		testRan, testOk := runTests(m.deps.MatchString, m.tests, deadline)
  1727  		fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline)
  1728  		exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples)
  1729  		m.stopAlarm()
  1730  		if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" {
  1731  			fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  1732  		}
  1733  		if !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks) || race.Errors() > 0 {
  1734  			fmt.Println("FAIL")
  1735  			m.exitCode = 1
  1736  			return
  1737  		}
  1738  	}
  1739  
  1740  	fuzzingOk := runFuzzing(m.deps, m.fuzzTargets)
  1741  	if !fuzzingOk {
  1742  		fmt.Println("FAIL")
  1743  		if *isFuzzWorker {
  1744  			m.exitCode = fuzzWorkerExitCode
  1745  		} else {
  1746  			m.exitCode = 1
  1747  		}
  1748  		return
  1749  	}
  1750  
  1751  	m.exitCode = 0
  1752  	if !*isFuzzWorker {
  1753  		fmt.Println("PASS")
  1754  	}
  1755  	return
  1756  }
  1757  
  1758  func (t *T) report() {
  1759  	if t.parent == nil {
  1760  		return
  1761  	}
  1762  	dstr := fmtDuration(t.duration)
  1763  	format := "--- %s: %s (%s)\n"
  1764  	if t.Failed() {
  1765  		t.flushToParent(t.name, format, "FAIL", t.name, dstr)
  1766  	} else if t.chatty != nil {
  1767  		if t.Skipped() {
  1768  			t.flushToParent(t.name, format, "SKIP", t.name, dstr)
  1769  		} else {
  1770  			t.flushToParent(t.name, format, "PASS", t.name, dstr)
  1771  		}
  1772  	}
  1773  }
  1774  
  1775  func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) {
  1776  	if _, err := matchString(*matchList, "non-empty"); err != nil {
  1777  		fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err)
  1778  		os.Exit(1)
  1779  	}
  1780  
  1781  	for _, test := range tests {
  1782  		if ok, _ := matchString(*matchList, test.Name); ok {
  1783  			fmt.Println(test.Name)
  1784  		}
  1785  	}
  1786  	for _, bench := range benchmarks {
  1787  		if ok, _ := matchString(*matchList, bench.Name); ok {
  1788  			fmt.Println(bench.Name)
  1789  		}
  1790  	}
  1791  	for _, fuzzTarget := range fuzzTargets {
  1792  		if ok, _ := matchString(*matchList, fuzzTarget.Name); ok {
  1793  			fmt.Println(fuzzTarget.Name)
  1794  		}
  1795  	}
  1796  	for _, example := range examples {
  1797  		if ok, _ := matchString(*matchList, example.Name); ok {
  1798  			fmt.Println(example.Name)
  1799  		}
  1800  	}
  1801  }
  1802  
  1803  // RunTests is an internal function but exported because it is cross-package;
  1804  // it is part of the implementation of the "go test" command.
  1805  func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {
  1806  	var deadline time.Time
  1807  	if *timeout > 0 {
  1808  		deadline = time.Now().Add(*timeout)
  1809  	}
  1810  	ran, ok := runTests(matchString, tests, deadline)
  1811  	if !ran && !haveExamples {
  1812  		fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  1813  	}
  1814  	return ok
  1815  }
  1816  
  1817  func runTests(matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
  1818  	ok = true
  1819  	for _, procs := range cpuList {
  1820  		runtime.GOMAXPROCS(procs)
  1821  		for i := uint(0); i < *count; i++ {
  1822  			if shouldFailFast() {
  1823  				break
  1824  			}
  1825  			if i > 0 && !ran {
  1826  				// There were no tests to run on the first
  1827  				// iteration. This won't change, so no reason
  1828  				// to keep trying.
  1829  				break
  1830  			}
  1831  			ctx := newTestContext(*parallel, newMatcher(matchString, *match, "-test.run"))
  1832  			ctx.deadline = deadline
  1833  			t := &T{
  1834  				common: common{
  1835  					signal:  make(chan bool, 1),
  1836  					barrier: make(chan bool),
  1837  					w:       os.Stdout,
  1838  				},
  1839  				context: ctx,
  1840  			}
  1841  			if Verbose() {
  1842  				t.chatty = newChattyPrinter(t.w)
  1843  			}
  1844  			tRunner(t, func(t *T) {
  1845  				for _, test := range tests {
  1846  					t.Run(test.Name, test.F)
  1847  				}
  1848  			})
  1849  			select {
  1850  			case <-t.signal:
  1851  			default:
  1852  				panic("internal error: tRunner exited without sending on t.signal")
  1853  			}
  1854  			ok = ok && !t.Failed()
  1855  			ran = ran || t.ran
  1856  		}
  1857  	}
  1858  	return ran, ok
  1859  }
  1860  
  1861  // before runs before all testing.
  1862  func (m *M) before() {
  1863  	if *memProfileRate > 0 {
  1864  		runtime.MemProfileRate = *memProfileRate
  1865  	}
  1866  	if *cpuProfile != "" {
  1867  		f, err := os.Create(toOutputDir(*cpuProfile))
  1868  		if err != nil {
  1869  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  1870  			return
  1871  		}
  1872  		if err := m.deps.StartCPUProfile(f); err != nil {
  1873  			fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err)
  1874  			f.Close()
  1875  			return
  1876  		}
  1877  		// Could save f so after can call f.Close; not worth the effort.
  1878  	}
  1879  	if *traceFile != "" {
  1880  		f, err := os.Create(toOutputDir(*traceFile))
  1881  		if err != nil {
  1882  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  1883  			return
  1884  		}
  1885  		if err := trace.Start(f); err != nil {
  1886  			fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err)
  1887  			f.Close()
  1888  			return
  1889  		}
  1890  		// Could save f so after can call f.Close; not worth the effort.
  1891  	}
  1892  	if *blockProfile != "" && *blockProfileRate >= 0 {
  1893  		runtime.SetBlockProfileRate(*blockProfileRate)
  1894  	}
  1895  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  1896  		runtime.SetMutexProfileFraction(*mutexProfileFraction)
  1897  	}
  1898  	if *coverProfile != "" && cover.Mode == "" {
  1899  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
  1900  		os.Exit(2)
  1901  	}
  1902  	if *testlog != "" {
  1903  		// Note: Not using toOutputDir.
  1904  		// This file is for use by cmd/go, not users.
  1905  		var f *os.File
  1906  		var err error
  1907  		if m.numRun == 1 {
  1908  			f, err = os.Create(*testlog)
  1909  		} else {
  1910  			f, err = os.OpenFile(*testlog, os.O_WRONLY, 0)
  1911  			if err == nil {
  1912  				f.Seek(0, io.SeekEnd)
  1913  			}
  1914  		}
  1915  		if err != nil {
  1916  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  1917  			os.Exit(2)
  1918  		}
  1919  		m.deps.StartTestLog(f)
  1920  		testlogFile = f
  1921  	}
  1922  	if *panicOnExit0 {
  1923  		m.deps.SetPanicOnExit0(true)
  1924  	}
  1925  }
  1926  
  1927  // after runs after all testing.
  1928  func (m *M) after() {
  1929  	m.afterOnce.Do(func() {
  1930  		m.writeProfiles()
  1931  	})
  1932  
  1933  	// Restore PanicOnExit0 after every run, because we set it to true before
  1934  	// every run. Otherwise, if m.Run is called multiple times the behavior of
  1935  	// os.Exit(0) will not be restored after the second run.
  1936  	if *panicOnExit0 {
  1937  		m.deps.SetPanicOnExit0(false)
  1938  	}
  1939  }
  1940  
  1941  func (m *M) writeProfiles() {
  1942  	if *testlog != "" {
  1943  		if err := m.deps.StopTestLog(); err != nil {
  1944  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  1945  			os.Exit(2)
  1946  		}
  1947  		if err := testlogFile.Close(); err != nil {
  1948  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  1949  			os.Exit(2)
  1950  		}
  1951  	}
  1952  	if *cpuProfile != "" {
  1953  		m.deps.StopCPUProfile() // flushes profile to disk
  1954  	}
  1955  	if *traceFile != "" {
  1956  		trace.Stop() // flushes trace to disk
  1957  	}
  1958  	if *memProfile != "" {
  1959  		f, err := os.Create(toOutputDir(*memProfile))
  1960  		if err != nil {
  1961  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  1962  			os.Exit(2)
  1963  		}
  1964  		runtime.GC() // materialize all statistics
  1965  		if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil {
  1966  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err)
  1967  			os.Exit(2)
  1968  		}
  1969  		f.Close()
  1970  	}
  1971  	if *blockProfile != "" && *blockProfileRate >= 0 {
  1972  		f, err := os.Create(toOutputDir(*blockProfile))
  1973  		if err != nil {
  1974  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  1975  			os.Exit(2)
  1976  		}
  1977  		if err = m.deps.WriteProfileTo("block", f, 0); err != nil {
  1978  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err)
  1979  			os.Exit(2)
  1980  		}
  1981  		f.Close()
  1982  	}
  1983  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  1984  		f, err := os.Create(toOutputDir(*mutexProfile))
  1985  		if err != nil {
  1986  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  1987  			os.Exit(2)
  1988  		}
  1989  		if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil {
  1990  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err)
  1991  			os.Exit(2)
  1992  		}
  1993  		f.Close()
  1994  	}
  1995  	if cover.Mode != "" {
  1996  		coverReport()
  1997  	}
  1998  }
  1999  
  2000  // toOutputDir returns the file name relocated, if required, to outputDir.
  2001  // Simple implementation to avoid pulling in path/filepath.
  2002  func toOutputDir(path string) string {
  2003  	if *outputDir == "" || path == "" {
  2004  		return path
  2005  	}
  2006  	// On Windows, it's clumsy, but we can be almost always correct
  2007  	// by just looking for a drive letter and a colon.
  2008  	// Absolute paths always have a drive letter (ignoring UNC).
  2009  	// Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
  2010  	// what to do, but even then path/filepath doesn't help.
  2011  	// TODO: Worth doing better? Probably not, because we're here only
  2012  	// under the management of go test.
  2013  	if runtime.GOOS == "windows" && len(path) >= 2 {
  2014  		letter, colon := path[0], path[1]
  2015  		if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' {
  2016  			// If path starts with a drive letter we're stuck with it regardless.
  2017  			return path
  2018  		}
  2019  	}
  2020  	if os.IsPathSeparator(path[0]) {
  2021  		return path
  2022  	}
  2023  	return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path)
  2024  }
  2025  
  2026  // startAlarm starts an alarm if requested.
  2027  func (m *M) startAlarm() time.Time {
  2028  	if *timeout <= 0 {
  2029  		return time.Time{}
  2030  	}
  2031  
  2032  	deadline := time.Now().Add(*timeout)
  2033  	m.timer = time.AfterFunc(*timeout, func() {
  2034  		m.after()
  2035  		debug.SetTraceback("all")
  2036  		panic(fmt.Sprintf("test timed out after %v", *timeout))
  2037  	})
  2038  	return deadline
  2039  }
  2040  
  2041  // stopAlarm turns off the alarm.
  2042  func (m *M) stopAlarm() {
  2043  	if *timeout > 0 {
  2044  		m.timer.Stop()
  2045  	}
  2046  }
  2047  
  2048  func parseCpuList() {
  2049  	for _, val := range strings.Split(*cpuListStr, ",") {
  2050  		val = strings.TrimSpace(val)
  2051  		if val == "" {
  2052  			continue
  2053  		}
  2054  		cpu, err := strconv.Atoi(val)
  2055  		if err != nil || cpu <= 0 {
  2056  			fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val)
  2057  			os.Exit(1)
  2058  		}
  2059  		cpuList = append(cpuList, cpu)
  2060  	}
  2061  	if cpuList == nil {
  2062  		cpuList = append(cpuList, runtime.GOMAXPROCS(-1))
  2063  	}
  2064  }
  2065  
  2066  func shouldFailFast() bool {
  2067  	return *failFast && atomic.LoadUint32(&numFailed) > 0
  2068  }
  2069  

View as plain text