github.com/mtsmfm/go/src@v0.0.0-20221020090648-44bdcb9f8fde/testing/testing.go (about)

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