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

View as plain text