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

View as plain text