Source file src/testing/testing.go

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

View as plain text