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  // If the environment variable GOTMPDIR is set, the temporary directory will
  1322  // be created somewhere beneath it.
  1323  func (c *common) TempDir() string {
  1324  	c.checkFuzzFn("TempDir")
  1325  	// Use a single parent directory for all the temporary directories
  1326  	// created by a test, each numbered sequentially.
  1327  	c.tempDirMu.Lock()
  1328  	var nonExistent bool
  1329  	if c.tempDir == "" { // Usually the case with js/wasm
  1330  		nonExistent = true
  1331  	} else {
  1332  		_, err := os.Stat(c.tempDir)
  1333  		nonExistent = os.IsNotExist(err)
  1334  		if err != nil && !nonExistent {
  1335  			c.Fatalf("TempDir: %v", err)
  1336  		}
  1337  	}
  1338  
  1339  	if nonExistent {
  1340  		c.Helper()
  1341  
  1342  		pattern := c.Name()
  1343  		// Limit length of file names on disk.
  1344  		// Invalid runes from slicing are dropped by strings.Map below.
  1345  		pattern = pattern[:min(len(pattern), 64)]
  1346  
  1347  		// Drop unusual characters (such as path separators or
  1348  		// characters interacting with globs) from the directory name to
  1349  		// avoid surprising os.MkdirTemp behavior.
  1350  		mapper := func(r rune) rune {
  1351  			if r < utf8.RuneSelf {
  1352  				const allowed = "!#$%&()+,-.=@^_{}~ "
  1353  				if '0' <= r && r <= '9' ||
  1354  					'a' <= r && r <= 'z' ||
  1355  					'A' <= r && r <= 'Z' {
  1356  					return r
  1357  				}
  1358  				if strings.ContainsRune(allowed, r) {
  1359  					return r
  1360  				}
  1361  			} else if unicode.IsLetter(r) || unicode.IsNumber(r) {
  1362  				return r
  1363  			}
  1364  			return -1
  1365  		}
  1366  		pattern = strings.Map(mapper, pattern)
  1367  		c.tempDir, c.tempDirErr = os.MkdirTemp(os.Getenv("GOTMPDIR"), pattern)
  1368  		if c.tempDirErr == nil {
  1369  			c.Cleanup(func() {
  1370  				if err := removeAll(c.tempDir); err != nil {
  1371  					c.Errorf("TempDir RemoveAll cleanup: %v", err)
  1372  				}
  1373  			})
  1374  		}
  1375  	}
  1376  
  1377  	if c.tempDirErr == nil {
  1378  		c.tempDirSeq++
  1379  	}
  1380  	seq := c.tempDirSeq
  1381  	c.tempDirMu.Unlock()
  1382  
  1383  	if c.tempDirErr != nil {
  1384  		c.Fatalf("TempDir: %v", c.tempDirErr)
  1385  	}
  1386  
  1387  	dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)
  1388  	if err := os.Mkdir(dir, 0o777); err != nil {
  1389  		c.Fatalf("TempDir: %v", err)
  1390  	}
  1391  	return dir
  1392  }
  1393  
  1394  // removeAll is like os.RemoveAll, but retries Windows "Access is denied."
  1395  // errors up to an arbitrary timeout.
  1396  //
  1397  // Those errors have been known to occur spuriously on at least the
  1398  // windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur
  1399  // legitimately if the test leaves behind a temp file that either is still open
  1400  // or the test otherwise lacks permission to delete. In the case of legitimate
  1401  // failures, a failing test may take a bit longer to fail, but once the test is
  1402  // fixed the extra latency will go away.
  1403  func removeAll(path string) error {
  1404  	const arbitraryTimeout = 2 * time.Second
  1405  	var (
  1406  		start     time.Time
  1407  		nextSleep = 1 * time.Millisecond
  1408  	)
  1409  	for {
  1410  		err := os.RemoveAll(path)
  1411  		if !isWindowsRetryable(err) {
  1412  			return err
  1413  		}
  1414  		if start.IsZero() {
  1415  			start = time.Now()
  1416  		} else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {
  1417  			return err
  1418  		}
  1419  		time.Sleep(nextSleep)
  1420  		nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))
  1421  	}
  1422  }
  1423  
  1424  // Setenv calls [os.Setenv] and uses Cleanup to
  1425  // restore the environment variable to its original value
  1426  // after the test.
  1427  //
  1428  // Because Setenv affects the whole process, it cannot be used
  1429  // in parallel tests or tests with parallel ancestors.
  1430  func (c *common) Setenv(key, value string) {
  1431  	c.checkFuzzFn("Setenv")
  1432  	prevValue, ok := os.LookupEnv(key)
  1433  
  1434  	if err := os.Setenv(key, value); err != nil {
  1435  		c.Fatalf("cannot set environment variable: %v", err)
  1436  	}
  1437  
  1438  	if ok {
  1439  		c.Cleanup(func() {
  1440  			os.Setenv(key, prevValue)
  1441  		})
  1442  	} else {
  1443  		c.Cleanup(func() {
  1444  			os.Unsetenv(key)
  1445  		})
  1446  	}
  1447  }
  1448  
  1449  // Chdir calls [os.Chdir] and uses Cleanup to restore the current
  1450  // working directory to its original value after the test. On Unix, it
  1451  // also sets PWD environment variable for the duration of the test.
  1452  //
  1453  // Because Chdir affects the whole process, it cannot be used
  1454  // in parallel tests or tests with parallel ancestors.
  1455  func (c *common) Chdir(dir string) {
  1456  	c.checkFuzzFn("Chdir")
  1457  	oldwd, err := os.Open(".")
  1458  	if err != nil {
  1459  		c.Fatal(err)
  1460  	}
  1461  	if err := os.Chdir(dir); err != nil {
  1462  		c.Fatal(err)
  1463  	}
  1464  	// On POSIX platforms, PWD represents “an absolute pathname of the
  1465  	// current working directory.” Since we are changing the working
  1466  	// directory, we should also set or update PWD to reflect that.
  1467  	switch runtime.GOOS {
  1468  	case "windows", "plan9":
  1469  		// Windows and Plan 9 do not use the PWD variable.
  1470  	default:
  1471  		if !filepath.IsAbs(dir) {
  1472  			dir, err = os.Getwd()
  1473  			if err != nil {
  1474  				c.Fatal(err)
  1475  			}
  1476  		}
  1477  		c.Setenv("PWD", dir)
  1478  	}
  1479  	c.Cleanup(func() {
  1480  		err := oldwd.Chdir()
  1481  		oldwd.Close()
  1482  		if err != nil {
  1483  			// It's not safe to continue with tests if we can't
  1484  			// get back to the original working directory. Since
  1485  			// we are holding a dirfd, this is highly unlikely.
  1486  			panic("testing.Chdir: " + err.Error())
  1487  		}
  1488  	})
  1489  }
  1490  
  1491  // Context returns a context that is canceled just before
  1492  // Cleanup-registered functions are called.
  1493  //
  1494  // Cleanup functions can wait for any resources
  1495  // that shut down on [context.Context.Done] before the test or benchmark completes.
  1496  func (c *common) Context() context.Context {
  1497  	c.checkFuzzFn("Context")
  1498  	return c.ctx
  1499  }
  1500  
  1501  // Attr emits a test attribute associated with this test.
  1502  //
  1503  // The key must not contain whitespace.
  1504  // The value must not contain newlines or carriage returns.
  1505  //
  1506  // The meaning of different attribute keys is left up to
  1507  // continuous integration systems and test frameworks.
  1508  //
  1509  // Test attributes are emitted immediately in the test log,
  1510  // but they are intended to be treated as unordered.
  1511  func (c *common) Attr(key, value string) {
  1512  	if strings.ContainsFunc(key, unicode.IsSpace) {
  1513  		c.Errorf("disallowed whitespace in attribute key %q", key)
  1514  		return
  1515  	}
  1516  	if strings.ContainsAny(value, "\r\n") {
  1517  		c.Errorf("disallowed newline in attribute value %q", value)
  1518  		return
  1519  	}
  1520  	if c.chatty == nil {
  1521  		return
  1522  	}
  1523  	c.chatty.Updatef(c.name, "=== ATTR  %s %v %v\n", c.name, key, value)
  1524  }
  1525  
  1526  // panicHandling controls the panic handling used by runCleanup.
  1527  type panicHandling int
  1528  
  1529  const (
  1530  	normalPanic panicHandling = iota
  1531  	recoverAndReturnPanic
  1532  )
  1533  
  1534  // runCleanup is called at the end of the test.
  1535  // If ph is recoverAndReturnPanic, it will catch panics, and return the
  1536  // recovered value if any.
  1537  func (c *common) runCleanup(ph panicHandling) (panicVal any) {
  1538  	c.cleanupStarted.Store(true)
  1539  	defer c.cleanupStarted.Store(false)
  1540  
  1541  	if ph == recoverAndReturnPanic {
  1542  		defer func() {
  1543  			panicVal = recover()
  1544  		}()
  1545  	}
  1546  
  1547  	// Make sure that if a cleanup function panics,
  1548  	// we still run the remaining cleanup functions.
  1549  	defer func() {
  1550  		c.mu.Lock()
  1551  		recur := len(c.cleanups) > 0
  1552  		c.mu.Unlock()
  1553  		if recur {
  1554  			c.runCleanup(normalPanic)
  1555  		}
  1556  	}()
  1557  
  1558  	if c.cancelCtx != nil {
  1559  		c.cancelCtx()
  1560  	}
  1561  
  1562  	for {
  1563  		var cleanup func()
  1564  		c.mu.Lock()
  1565  		if len(c.cleanups) > 0 {
  1566  			last := len(c.cleanups) - 1
  1567  			cleanup = c.cleanups[last]
  1568  			c.cleanups = c.cleanups[:last]
  1569  		}
  1570  		c.mu.Unlock()
  1571  		if cleanup == nil {
  1572  			return nil
  1573  		}
  1574  		cleanup()
  1575  	}
  1576  }
  1577  
  1578  // resetRaces updates c.parent's count of data race errors (or the global count,
  1579  // if c has no parent), and updates c.lastRaceErrors to match.
  1580  //
  1581  // Any races that occurred prior to this call to resetRaces will
  1582  // not be attributed to c.
  1583  func (c *common) resetRaces() {
  1584  	if c.parent == nil {
  1585  		c.lastRaceErrors.Store(int64(race.Errors()))
  1586  	} else {
  1587  		c.lastRaceErrors.Store(c.parent.checkRaces())
  1588  	}
  1589  }
  1590  
  1591  // checkRaces checks whether the global count of data race errors has increased
  1592  // since c's count was last reset.
  1593  //
  1594  // If so, it marks c as having failed due to those races (logging an error for
  1595  // the first such race), and updates the race counts for the parents of c so
  1596  // that if they are currently suspended (such as in a call to T.Run) they will
  1597  // not log separate errors for the race(s).
  1598  //
  1599  // Note that multiple tests may be marked as failed due to the same race if they
  1600  // are executing in parallel.
  1601  func (c *common) checkRaces() (raceErrors int64) {
  1602  	raceErrors = int64(race.Errors())
  1603  	for {
  1604  		last := c.lastRaceErrors.Load()
  1605  		if raceErrors <= last {
  1606  			// All races have already been reported.
  1607  			return raceErrors
  1608  		}
  1609  		if c.lastRaceErrors.CompareAndSwap(last, raceErrors) {
  1610  			break
  1611  		}
  1612  	}
  1613  
  1614  	if c.raceErrorLogged.CompareAndSwap(false, true) {
  1615  		// This is the first race we've encountered for this test.
  1616  		// Mark the test as failed, and log the reason why only once.
  1617  		// (Note that the race detector itself will still write a goroutine
  1618  		// dump for any further races it detects.)
  1619  		c.Errorf("race detected during execution of test")
  1620  	}
  1621  
  1622  	// Update the parent(s) of this test so that they don't re-report the race.
  1623  	parent := c.parent
  1624  	for parent != nil {
  1625  		for {
  1626  			last := parent.lastRaceErrors.Load()
  1627  			if raceErrors <= last {
  1628  				// This race was already reported by another (likely parallel) subtest.
  1629  				return raceErrors
  1630  			}
  1631  			if parent.lastRaceErrors.CompareAndSwap(last, raceErrors) {
  1632  				break
  1633  			}
  1634  		}
  1635  		parent = parent.parent
  1636  	}
  1637  
  1638  	return raceErrors
  1639  }
  1640  
  1641  // callerName gives the function name (qualified with a package path)
  1642  // for the caller after skip frames (where 0 means the current function).
  1643  func callerName(skip int) string {
  1644  	var pc [1]uintptr
  1645  	n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName
  1646  	if n == 0 {
  1647  		panic("testing: zero callers found")
  1648  	}
  1649  	return pcToName(pc[0])
  1650  }
  1651  
  1652  func pcToName(pc uintptr) string {
  1653  	pcs := []uintptr{pc}
  1654  	frames := runtime.CallersFrames(pcs)
  1655  	frame, _ := frames.Next()
  1656  	return frame.Function
  1657  }
  1658  
  1659  const parallelConflict = `testing: test using t.Setenv or t.Chdir can not use t.Parallel`
  1660  
  1661  // Parallel signals that this test is to be run in parallel with (and only with)
  1662  // other parallel tests. When a test is run multiple times due to use of
  1663  // -test.count or -test.cpu, multiple instances of a single test never run in
  1664  // parallel with each other.
  1665  func (t *T) Parallel() {
  1666  	if t.isParallel {
  1667  		panic("testing: t.Parallel called multiple times")
  1668  	}
  1669  	if t.isSynctest {
  1670  		panic("testing: t.Parallel called inside synctest bubble")
  1671  	}
  1672  	if t.denyParallel {
  1673  		panic(parallelConflict)
  1674  	}
  1675  	if t.parent.barrier == nil {
  1676  		// T.Parallel has no effect when fuzzing.
  1677  		// Multiple processes may run in parallel, but only one input can run at a
  1678  		// time per process so we can attribute crashes to specific inputs.
  1679  		return
  1680  	}
  1681  
  1682  	t.isParallel = true
  1683  
  1684  	// We don't want to include the time we spend waiting for serial tests
  1685  	// in the test duration. Record the elapsed time thus far and reset the
  1686  	// timer afterwards.
  1687  	t.duration += highPrecisionTimeSince(t.start)
  1688  
  1689  	// Add to the list of tests to be released by the parent.
  1690  	t.parent.sub = append(t.parent.sub, t)
  1691  
  1692  	// Report any races during execution of this test up to this point.
  1693  	//
  1694  	// We will assume that any races that occur between here and the point where
  1695  	// we unblock are not caused by this subtest. That assumption usually holds,
  1696  	// although it can be wrong if the test spawns a goroutine that races in the
  1697  	// background while the rest of the test is blocked on the call to Parallel.
  1698  	// If that happens, we will misattribute the background race to some other
  1699  	// test, or to no test at all — but that false-negative is so unlikely that it
  1700  	// is not worth adding race-report noise for the common case where the test is
  1701  	// completely suspended during the call to Parallel.
  1702  	t.checkRaces()
  1703  
  1704  	if t.chatty != nil {
  1705  		t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)
  1706  	}
  1707  	running.Delete(t.name)
  1708  
  1709  	t.signal <- true   // Release calling test.
  1710  	<-t.parent.barrier // Wait for the parent test to complete.
  1711  	t.tstate.waitParallel()
  1712  	parallelStart.Add(1)
  1713  
  1714  	if t.chatty != nil {
  1715  		t.chatty.Updatef(t.name, "=== CONT  %s\n", t.name)
  1716  	}
  1717  	running.Store(t.name, highPrecisionTimeNow())
  1718  	t.start = highPrecisionTimeNow()
  1719  
  1720  	// Reset the local race counter to ignore any races that happened while this
  1721  	// goroutine was blocked, such as in the parent test or in other parallel
  1722  	// subtests.
  1723  	//
  1724  	// (Note that we don't call parent.checkRaces here:
  1725  	// if other parallel subtests have already introduced races, we want to
  1726  	// let them report those races instead of attributing them to the parent.)
  1727  	t.lastRaceErrors.Store(int64(race.Errors()))
  1728  }
  1729  
  1730  func (t *T) checkParallel() {
  1731  	// Non-parallel subtests that have parallel ancestors may still
  1732  	// run in parallel with other tests: they are only non-parallel
  1733  	// with respect to the other subtests of the same parent.
  1734  	// Since calls like SetEnv or Chdir affects the whole process, we need
  1735  	// to deny those if the current test or any parent is parallel.
  1736  	for c := &t.common; c != nil; c = c.parent {
  1737  		if c.isParallel {
  1738  			panic(parallelConflict)
  1739  		}
  1740  	}
  1741  
  1742  	t.denyParallel = true
  1743  }
  1744  
  1745  // Setenv calls os.Setenv(key, value) and uses Cleanup to
  1746  // restore the environment variable to its original value
  1747  // after the test.
  1748  //
  1749  // Because Setenv affects the whole process, it cannot be used
  1750  // in parallel tests or tests with parallel ancestors.
  1751  func (t *T) Setenv(key, value string) {
  1752  	t.checkParallel()
  1753  	t.common.Setenv(key, value)
  1754  }
  1755  
  1756  // Chdir calls [os.Chdir] and uses Cleanup to restore the current
  1757  // working directory to its original value after the test. On Unix, it
  1758  // also sets PWD environment variable for the duration of the test.
  1759  //
  1760  // Because Chdir affects the whole process, it cannot be used
  1761  // in parallel tests or tests with parallel ancestors.
  1762  func (t *T) Chdir(dir string) {
  1763  	t.checkParallel()
  1764  	t.common.Chdir(dir)
  1765  }
  1766  
  1767  // InternalTest is an internal type but exported because it is cross-package;
  1768  // it is part of the implementation of the "go test" command.
  1769  type InternalTest struct {
  1770  	Name string
  1771  	F    func(*T)
  1772  }
  1773  
  1774  var errNilPanicOrGoexit = errors.New("test executed panic(nil) or runtime.Goexit")
  1775  
  1776  func tRunner(t *T, fn func(t *T)) {
  1777  	t.runner = callerName(0)
  1778  
  1779  	// When this goroutine is done, either because fn(t)
  1780  	// returned normally or because a test failure triggered
  1781  	// a call to runtime.Goexit, record the duration and send
  1782  	// a signal saying that the test is done.
  1783  	defer func() {
  1784  		t.checkRaces()
  1785  
  1786  		// TODO(#61034): This is the wrong place for this check.
  1787  		if t.Failed() {
  1788  			numFailed.Add(1)
  1789  		}
  1790  
  1791  		// Check if the test panicked or Goexited inappropriately.
  1792  		//
  1793  		// If this happens in a normal test, print output but continue panicking.
  1794  		// tRunner is called in its own goroutine, so this terminates the process.
  1795  		//
  1796  		// If this happens while fuzzing, recover from the panic and treat it like a
  1797  		// normal failure. It's important that the process keeps running in order to
  1798  		// find short inputs that cause panics.
  1799  		err := recover()
  1800  		signal := true
  1801  
  1802  		t.mu.RLock()
  1803  		finished := t.finished
  1804  		t.mu.RUnlock()
  1805  		if !finished && err == nil {
  1806  			err = errNilPanicOrGoexit
  1807  			for p := t.parent; p != nil; p = p.parent {
  1808  				p.mu.RLock()
  1809  				finished = p.finished
  1810  				p.mu.RUnlock()
  1811  				if finished {
  1812  					if !t.isParallel {
  1813  						t.Errorf("%v: subtest may have called FailNow on a parent test", err)
  1814  						err = nil
  1815  					}
  1816  					signal = false
  1817  					break
  1818  				}
  1819  			}
  1820  		}
  1821  
  1822  		if err != nil && t.tstate.isFuzzing {
  1823  			prefix := "panic: "
  1824  			if err == errNilPanicOrGoexit {
  1825  				prefix = ""
  1826  			}
  1827  			t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack()))
  1828  			t.mu.Lock()
  1829  			t.finished = true
  1830  			t.mu.Unlock()
  1831  			err = nil
  1832  		}
  1833  
  1834  		// Use a deferred call to ensure that we report that the test is
  1835  		// complete even if a cleanup function calls t.FailNow. See issue 41355.
  1836  		didPanic := false
  1837  		defer func() {
  1838  			// Only report that the test is complete if it doesn't panic,
  1839  			// as otherwise the test binary can exit before the panic is
  1840  			// reported to the user. See issue 41479.
  1841  			if didPanic {
  1842  				return
  1843  			}
  1844  			if err != nil {
  1845  				panic(err)
  1846  			}
  1847  			running.Delete(t.name)
  1848  			if t.isParallel {
  1849  				parallelStop.Add(1)
  1850  			}
  1851  			t.signal <- signal
  1852  		}()
  1853  
  1854  		doPanic := func(err any) {
  1855  			t.Fail()
  1856  			if r := t.runCleanup(recoverAndReturnPanic); r != nil {
  1857  				t.Logf("cleanup panicked with %v", r)
  1858  			}
  1859  			// Flush the output log up to the root before dying.
  1860  			// Skip this if this *T is a synctest bubble, because we're not a subtest.
  1861  			for root := &t.common; !root.isSynctest && root.parent != nil; root = root.parent {
  1862  				root.mu.Lock()
  1863  				root.duration += highPrecisionTimeSince(root.start)
  1864  				d := root.duration
  1865  				root.mu.Unlock()
  1866  				// Output buffered logs.
  1867  				root.flushPartial()
  1868  				root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d))
  1869  				if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil {
  1870  					fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r)
  1871  				}
  1872  			}
  1873  			didPanic = true
  1874  			panic(err)
  1875  		}
  1876  		if err != nil {
  1877  			doPanic(err)
  1878  		}
  1879  
  1880  		t.duration += highPrecisionTimeSince(t.start)
  1881  
  1882  		if len(t.sub) > 0 {
  1883  			// Run parallel subtests.
  1884  
  1885  			// Decrease the running count for this test and mark it as no longer running.
  1886  			t.tstate.release()
  1887  			running.Delete(t.name)
  1888  
  1889  			// Release the parallel subtests.
  1890  			close(t.barrier)
  1891  			// Wait for subtests to complete.
  1892  			for _, sub := range t.sub {
  1893  				<-sub.signal
  1894  			}
  1895  
  1896  			// Run any cleanup callbacks, marking the test as running
  1897  			// in case the cleanup hangs.
  1898  			cleanupStart := highPrecisionTimeNow()
  1899  			running.Store(t.name, cleanupStart)
  1900  			err := t.runCleanup(recoverAndReturnPanic)
  1901  			t.duration += highPrecisionTimeSince(cleanupStart)
  1902  			if err != nil {
  1903  				doPanic(err)
  1904  			}
  1905  			t.checkRaces()
  1906  			if !t.isParallel {
  1907  				// Reacquire the count for sequential tests. See comment in Run.
  1908  				t.tstate.waitParallel()
  1909  			}
  1910  		} else if t.isParallel {
  1911  			// Only release the count for this test if it was run as a parallel
  1912  			// test. See comment in Run method.
  1913  			t.tstate.release()
  1914  		}
  1915  		// Output buffered logs.
  1916  		for root := &t.common; root.parent != nil; root = root.parent {
  1917  			root.flushPartial()
  1918  		}
  1919  		t.report() // Report after all subtests have finished.
  1920  
  1921  		// Do not lock t.done to allow race detector to detect race in case
  1922  		// the user does not appropriately synchronize a goroutine.
  1923  		t.done = true
  1924  		if t.parent != nil && !t.hasSub.Load() {
  1925  			t.setRan()
  1926  		}
  1927  	}()
  1928  	defer func() {
  1929  		if len(t.sub) == 0 {
  1930  			t.runCleanup(normalPanic)
  1931  		}
  1932  	}()
  1933  
  1934  	t.start = highPrecisionTimeNow()
  1935  	t.resetRaces()
  1936  	fn(t)
  1937  
  1938  	// code beyond here will not be executed when FailNow is invoked
  1939  	t.mu.Lock()
  1940  	t.finished = true
  1941  	t.mu.Unlock()
  1942  }
  1943  
  1944  // Run runs f as a subtest of t called name. It runs f in a separate goroutine
  1945  // and blocks until f returns or calls t.Parallel to become a parallel test.
  1946  // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
  1947  //
  1948  // Run may be called simultaneously from multiple goroutines, but all such calls
  1949  // must return before the outer test function for t returns.
  1950  func (t *T) Run(name string, f func(t *T)) bool {
  1951  	if t.isSynctest {
  1952  		panic("testing: t.Run called inside synctest bubble")
  1953  	}
  1954  	if t.cleanupStarted.Load() {
  1955  		panic("testing: t.Run called during t.Cleanup")
  1956  	}
  1957  
  1958  	t.hasSub.Store(true)
  1959  	testName, ok, _ := t.tstate.match.fullName(&t.common, name)
  1960  	if !ok || shouldFailFast() {
  1961  		return true
  1962  	}
  1963  	// Record the stack trace at the point of this call so that if the subtest
  1964  	// function - which runs in a separate stack - is marked as a helper, we can
  1965  	// continue walking the stack into the parent test.
  1966  	var pc [maxStackLen]uintptr
  1967  	n := runtime.Callers(2, pc[:])
  1968  
  1969  	// There's no reason to inherit this context from parent. The user's code can't observe
  1970  	// the difference between the background context and the one from the parent test.
  1971  	ctx, cancelCtx := context.WithCancel(context.Background())
  1972  	t = &T{
  1973  		common: common{
  1974  			barrier:   make(chan bool),
  1975  			signal:    make(chan bool, 1),
  1976  			name:      testName,
  1977  			parent:    &t.common,
  1978  			level:     t.level + 1,
  1979  			creator:   pc[:n],
  1980  			chatty:    t.chatty,
  1981  			ctx:       ctx,
  1982  			cancelCtx: cancelCtx,
  1983  		},
  1984  		tstate: t.tstate,
  1985  	}
  1986  	t.w = indenter{&t.common}
  1987  	t.setOutputWriter()
  1988  
  1989  	if t.chatty != nil {
  1990  		t.chatty.Updatef(t.name, "=== RUN   %s\n", t.name)
  1991  	}
  1992  	running.Store(t.name, highPrecisionTimeNow())
  1993  
  1994  	// Instead of reducing the running count of this test before calling the
  1995  	// tRunner and increasing it afterwards, we rely on tRunner keeping the
  1996  	// count correct. This ensures that a sequence of sequential tests runs
  1997  	// without being preempted, even when their parent is a parallel test. This
  1998  	// may especially reduce surprises if *parallel == 1.
  1999  	go tRunner(t, f)
  2000  
  2001  	// The parent goroutine will block until the subtest either finishes or calls
  2002  	// Parallel, but in general we don't know whether the parent goroutine is the
  2003  	// top-level test function or some other goroutine it has spawned.
  2004  	// To avoid confusing false-negatives, we leave the parent in the running map
  2005  	// even though in the typical case it is blocked.
  2006  
  2007  	if !<-t.signal {
  2008  		// At this point, it is likely that FailNow was called on one of the
  2009  		// parent tests by one of the subtests. Continue aborting up the chain.
  2010  		runtime.Goexit()
  2011  	}
  2012  
  2013  	if t.chatty != nil && t.chatty.json {
  2014  		t.chatty.Updatef(t.parent.name, "=== NAME  %s\n", t.parent.name)
  2015  	}
  2016  	return !t.failed
  2017  }
  2018  
  2019  // testingSynctestTest runs f within a synctest bubble.
  2020  // It is called by synctest.Test, from within an already-created bubble.
  2021  //
  2022  //go:linkname testingSynctestTest testing/synctest.testingSynctestTest
  2023  func testingSynctestTest(t *T, f func(*T)) (ok bool) {
  2024  	if t.cleanupStarted.Load() {
  2025  		panic("testing: synctest.Run called during t.Cleanup")
  2026  	}
  2027  
  2028  	var pc [maxStackLen]uintptr
  2029  	n := runtime.Callers(2, pc[:])
  2030  
  2031  	ctx, cancelCtx := context.WithCancel(context.Background())
  2032  	t2 := &T{
  2033  		common: common{
  2034  			barrier:    make(chan bool),
  2035  			signal:     make(chan bool, 1),
  2036  			name:       t.name,
  2037  			parent:     &t.common,
  2038  			level:      t.level + 1,
  2039  			creator:    pc[:n],
  2040  			chatty:     t.chatty,
  2041  			ctx:        ctx,
  2042  			cancelCtx:  cancelCtx,
  2043  			isSynctest: true,
  2044  		},
  2045  		tstate: t.tstate,
  2046  	}
  2047  
  2048  	go tRunner(t2, f)
  2049  	if !<-t2.signal {
  2050  		// At this point, it is likely that FailNow was called on one of the
  2051  		// parent tests by one of the subtests. Continue aborting up the chain.
  2052  		runtime.Goexit()
  2053  	}
  2054  	return !t2.failed
  2055  }
  2056  
  2057  // Deadline reports the time at which the test binary will have
  2058  // exceeded the timeout specified by the -timeout flag.
  2059  //
  2060  // The ok result is false if the -timeout flag indicates “no timeout” (0).
  2061  func (t *T) Deadline() (deadline time.Time, ok bool) {
  2062  	if t.isSynctest {
  2063  		// There's no point in returning a real-clock deadline to
  2064  		// a test using a fake clock. We could return "no timeout",
  2065  		// but panicking makes it easier for users to catch the error.
  2066  		panic("testing: t.Deadline called inside synctest bubble")
  2067  	}
  2068  	deadline = t.tstate.deadline
  2069  	return deadline, !deadline.IsZero()
  2070  }
  2071  
  2072  // testState holds all fields that are common to all tests. This includes
  2073  // synchronization primitives to run at most *parallel tests.
  2074  type testState struct {
  2075  	match    *matcher
  2076  	deadline time.Time
  2077  
  2078  	// isFuzzing is true in the state used when generating random inputs
  2079  	// for fuzz targets. isFuzzing is false when running normal tests and
  2080  	// when running fuzz tests as unit tests (without -fuzz or when -fuzz
  2081  	// does not match).
  2082  	isFuzzing bool
  2083  
  2084  	mu sync.Mutex
  2085  
  2086  	// Channel used to signal tests that are ready to be run in parallel.
  2087  	startParallel chan bool
  2088  
  2089  	// running is the number of tests currently running in parallel.
  2090  	// This does not include tests that are waiting for subtests to complete.
  2091  	running int
  2092  
  2093  	// numWaiting is the number tests waiting to be run in parallel.
  2094  	numWaiting int
  2095  
  2096  	// maxParallel is a copy of the parallel flag.
  2097  	maxParallel int
  2098  }
  2099  
  2100  func newTestState(maxParallel int, m *matcher) *testState {
  2101  	return &testState{
  2102  		match:         m,
  2103  		startParallel: make(chan bool),
  2104  		maxParallel:   maxParallel,
  2105  		running:       1, // Set the count to 1 for the main (sequential) test.
  2106  	}
  2107  }
  2108  
  2109  func (s *testState) waitParallel() {
  2110  	s.mu.Lock()
  2111  	if s.running < s.maxParallel {
  2112  		s.running++
  2113  		s.mu.Unlock()
  2114  		return
  2115  	}
  2116  	s.numWaiting++
  2117  	s.mu.Unlock()
  2118  	<-s.startParallel
  2119  }
  2120  
  2121  func (s *testState) release() {
  2122  	s.mu.Lock()
  2123  	if s.numWaiting == 0 {
  2124  		s.running--
  2125  		s.mu.Unlock()
  2126  		return
  2127  	}
  2128  	s.numWaiting--
  2129  	s.mu.Unlock()
  2130  	s.startParallel <- true // Pick a waiting test to be run.
  2131  }
  2132  
  2133  // No one should be using func Main anymore.
  2134  // See the doc comment on func Main and use MainStart instead.
  2135  var errMain = errors.New("testing: unexpected use of func Main")
  2136  
  2137  type matchStringOnly func(pat, str string) (bool, error)
  2138  
  2139  func (f matchStringOnly) MatchString(pat, str string) (bool, error)   { return f(pat, str) }
  2140  func (f matchStringOnly) StartCPUProfile(w io.Writer) error           { return errMain }
  2141  func (f matchStringOnly) StopCPUProfile()                             {}
  2142  func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain }
  2143  func (f matchStringOnly) ImportPath() string                          { return "" }
  2144  func (f matchStringOnly) StartTestLog(io.Writer)                      {}
  2145  func (f matchStringOnly) StopTestLog() error                          { return errMain }
  2146  func (f matchStringOnly) SetPanicOnExit0(bool)                        {}
  2147  func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error {
  2148  	return errMain
  2149  }
  2150  func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain }
  2151  func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) {
  2152  	return nil, errMain
  2153  }
  2154  func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil }
  2155  func (f matchStringOnly) ResetCoverage()                          {}
  2156  func (f matchStringOnly) SnapshotCoverage()                       {}
  2157  
  2158  func (f matchStringOnly) InitRuntimeCoverage() (mode string, tearDown func(string, string) (string, error), snapcov func() float64) {
  2159  	return
  2160  }
  2161  
  2162  // Main is an internal function, part of the implementation of the "go test" command.
  2163  // It was exported because it is cross-package and predates "internal" packages.
  2164  // It is no longer used by "go test" but preserved, as much as possible, for other
  2165  // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
  2166  // new functionality is added to the testing package.
  2167  // Systems simulating "go test" should be updated to use [MainStart].
  2168  func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {
  2169  	os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run())
  2170  }
  2171  
  2172  // M is a type passed to a TestMain function to run the actual tests.
  2173  type M struct {
  2174  	deps        testDeps
  2175  	tests       []InternalTest
  2176  	benchmarks  []InternalBenchmark
  2177  	fuzzTargets []InternalFuzzTarget
  2178  	examples    []InternalExample
  2179  
  2180  	timer     *time.Timer
  2181  	afterOnce sync.Once
  2182  
  2183  	numRun int
  2184  
  2185  	// value to pass to os.Exit, the outer test func main
  2186  	// harness calls os.Exit with this code. See #34129.
  2187  	exitCode int
  2188  }
  2189  
  2190  // testDeps is an internal interface of functionality that is
  2191  // passed into this package by a test's generated main package.
  2192  // The canonical implementation of this interface is
  2193  // testing/internal/testdeps's TestDeps.
  2194  type testDeps interface {
  2195  	ImportPath() string
  2196  	MatchString(pat, str string) (bool, error)
  2197  	SetPanicOnExit0(bool)
  2198  	StartCPUProfile(io.Writer) error
  2199  	StopCPUProfile()
  2200  	StartTestLog(io.Writer)
  2201  	StopTestLog() error
  2202  	WriteProfileTo(string, io.Writer, int) error
  2203  	CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error
  2204  	RunFuzzWorker(func(corpusEntry) error) error
  2205  	ReadCorpus(string, []reflect.Type) ([]corpusEntry, error)
  2206  	CheckCorpus([]any, []reflect.Type) error
  2207  	ResetCoverage()
  2208  	SnapshotCoverage()
  2209  	InitRuntimeCoverage() (mode string, tearDown func(coverprofile string, gocoverdir string) (string, error), snapcov func() float64)
  2210  }
  2211  
  2212  // MainStart is meant for use by tests generated by 'go test'.
  2213  // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
  2214  // It may change signature from release to release.
  2215  func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M {
  2216  	registerCover(deps.InitRuntimeCoverage())
  2217  	Init()
  2218  	return &M{
  2219  		deps:        deps,
  2220  		tests:       tests,
  2221  		benchmarks:  benchmarks,
  2222  		fuzzTargets: fuzzTargets,
  2223  		examples:    examples,
  2224  	}
  2225  }
  2226  
  2227  var (
  2228  	testingTesting bool
  2229  	realStderr     *os.File
  2230  )
  2231  
  2232  // Run runs the tests. It returns an exit code to pass to os.Exit.
  2233  // The exit code is zero when all tests pass, and non-zero for any kind
  2234  // of failure. For machine readable test results, parse the output of
  2235  // 'go test -json'.
  2236  func (m *M) Run() (code int) {
  2237  	defer func() {
  2238  		code = m.exitCode
  2239  	}()
  2240  
  2241  	// Count the number of calls to m.Run.
  2242  	// We only ever expected 1, but we didn't enforce that,
  2243  	// and now there are tests in the wild that call m.Run multiple times.
  2244  	// Sigh. go.dev/issue/23129.
  2245  	m.numRun++
  2246  
  2247  	// TestMain may have already called flag.Parse.
  2248  	if !flag.Parsed() {
  2249  		flag.Parse()
  2250  	}
  2251  
  2252  	if chatty.json {
  2253  		// With -v=json, stdout and stderr are pointing to the same pipe,
  2254  		// which is leading into test2json. In general, operating systems
  2255  		// do a good job of ensuring that writes to the same pipe through
  2256  		// different file descriptors are delivered whole, so that writing
  2257  		// AAA to stdout and BBB to stderr simultaneously produces
  2258  		// AAABBB or BBBAAA on the pipe, not something like AABBBA.
  2259  		// However, the exception to this is when the pipe fills: in that
  2260  		// case, Go's use of non-blocking I/O means that writing AAA
  2261  		// or BBB might be split across multiple system calls, making it
  2262  		// entirely possible to get output like AABBBA. The same problem
  2263  		// happens inside the operating system kernel if we switch to
  2264  		// blocking I/O on the pipe. This interleaved output can do things
  2265  		// like print unrelated messages in the middle of a TestFoo line,
  2266  		// which confuses test2json. Setting os.Stderr = os.Stdout will make
  2267  		// them share a single pfd, which will hold a lock for each program
  2268  		// write, preventing any interleaving.
  2269  		//
  2270  		// It might be nice to set Stderr = Stdout always, or perhaps if
  2271  		// we can tell they are the same file, but for now -v=json is
  2272  		// a very clear signal. Making the two files the same may cause
  2273  		// surprises if programs close os.Stdout but expect to be able
  2274  		// to continue to write to os.Stderr, but it's hard to see why a
  2275  		// test would think it could take over global state that way.
  2276  		//
  2277  		// This fix only helps programs where the output is coming directly
  2278  		// from Go code. It does not help programs in which a subprocess is
  2279  		// writing to stderr or stdout at the same time that a Go test is writing output.
  2280  		// It also does not help when the output is coming from the runtime,
  2281  		// such as when using the print/println functions, since that code writes
  2282  		// directly to fd 2 without any locking.
  2283  		// We keep realStderr around to prevent fd 2 from being closed.
  2284  		//
  2285  		// See go.dev/issue/33419.
  2286  		realStderr = os.Stderr
  2287  		os.Stderr = os.Stdout
  2288  	}
  2289  
  2290  	if *parallel < 1 {
  2291  		fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer")
  2292  		flag.Usage()
  2293  		m.exitCode = 2
  2294  		return
  2295  	}
  2296  	if *matchFuzz != "" && *fuzzCacheDir == "" {
  2297  		fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set")
  2298  		flag.Usage()
  2299  		m.exitCode = 2
  2300  		return
  2301  	}
  2302  
  2303  	if *matchList != "" {
  2304  		listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples)
  2305  		m.exitCode = 0
  2306  		return
  2307  	}
  2308  
  2309  	if *shuffle != "off" {
  2310  		var n int64
  2311  		var err error
  2312  		if *shuffle == "on" {
  2313  			n = time.Now().UnixNano()
  2314  		} else {
  2315  			n, err = strconv.ParseInt(*shuffle, 10, 64)
  2316  			if err != nil {
  2317  				fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err)
  2318  				m.exitCode = 2
  2319  				return
  2320  			}
  2321  		}
  2322  		fmt.Println("-test.shuffle", n)
  2323  		rng := rand.New(rand.NewSource(n))
  2324  		rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] })
  2325  		rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] })
  2326  	}
  2327  
  2328  	parseCpuList()
  2329  
  2330  	m.before()
  2331  	defer m.after()
  2332  
  2333  	// Run tests, examples, and benchmarks unless this is a fuzz worker process.
  2334  	// Workers start after this is done by their parent process, and they should
  2335  	// not repeat this work.
  2336  	if !*isFuzzWorker {
  2337  		deadline := m.startAlarm()
  2338  		haveExamples = len(m.examples) > 0
  2339  		testRan, testOk := runTests(m.deps.MatchString, m.tests, deadline)
  2340  		fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline)
  2341  		exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples)
  2342  		m.stopAlarm()
  2343  		if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" {
  2344  			fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  2345  			if testingTesting && *match != "^$" {
  2346  				// If this happens during testing of package testing it could be that
  2347  				// package testing's own logic for when to run a test is broken,
  2348  				// in which case every test will run nothing and succeed,
  2349  				// with no obvious way to detect this problem (since no tests are running).
  2350  				// So make 'no tests to run' a hard failure when testing package testing itself.
  2351  				fmt.Print(chatty.prefix(), "FAIL: package testing must run tests\n")
  2352  				testOk = false
  2353  			}
  2354  		}
  2355  		anyFailed := !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks)
  2356  		if !anyFailed && race.Errors() > 0 {
  2357  			fmt.Print(chatty.prefix(), "testing: race detected outside of test execution\n")
  2358  			anyFailed = true
  2359  		}
  2360  		if anyFailed {
  2361  			fmt.Print(chatty.prefix(), "FAIL\n")
  2362  			m.exitCode = 1
  2363  			return
  2364  		}
  2365  	}
  2366  
  2367  	fuzzingOk := runFuzzing(m.deps, m.fuzzTargets)
  2368  	if !fuzzingOk {
  2369  		fmt.Print(chatty.prefix(), "FAIL\n")
  2370  		if *isFuzzWorker {
  2371  			m.exitCode = fuzzWorkerExitCode
  2372  		} else {
  2373  			m.exitCode = 1
  2374  		}
  2375  		return
  2376  	}
  2377  
  2378  	m.exitCode = 0
  2379  	if !*isFuzzWorker {
  2380  		fmt.Print(chatty.prefix(), "PASS\n")
  2381  	}
  2382  	return
  2383  }
  2384  
  2385  func (t *T) report() {
  2386  	if t.parent == nil {
  2387  		return
  2388  	}
  2389  	if t.isSynctest {
  2390  		return // t.parent will handle reporting
  2391  	}
  2392  	dstr := fmtDuration(t.duration)
  2393  	format := "--- %s: %s (%s)\n"
  2394  	if t.Failed() {
  2395  		t.flushToParent(t.name, format, "FAIL", t.name, dstr)
  2396  	} else if t.chatty != nil {
  2397  		if t.Skipped() {
  2398  			t.flushToParent(t.name, format, "SKIP", t.name, dstr)
  2399  		} else {
  2400  			t.flushToParent(t.name, format, "PASS", t.name, dstr)
  2401  		}
  2402  	}
  2403  }
  2404  
  2405  func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) {
  2406  	if _, err := matchString(*matchList, "non-empty"); err != nil {
  2407  		fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err)
  2408  		os.Exit(1)
  2409  	}
  2410  
  2411  	for _, test := range tests {
  2412  		if ok, _ := matchString(*matchList, test.Name); ok {
  2413  			fmt.Println(test.Name)
  2414  		}
  2415  	}
  2416  	for _, bench := range benchmarks {
  2417  		if ok, _ := matchString(*matchList, bench.Name); ok {
  2418  			fmt.Println(bench.Name)
  2419  		}
  2420  	}
  2421  	for _, fuzzTarget := range fuzzTargets {
  2422  		if ok, _ := matchString(*matchList, fuzzTarget.Name); ok {
  2423  			fmt.Println(fuzzTarget.Name)
  2424  		}
  2425  	}
  2426  	for _, example := range examples {
  2427  		if ok, _ := matchString(*matchList, example.Name); ok {
  2428  			fmt.Println(example.Name)
  2429  		}
  2430  	}
  2431  }
  2432  
  2433  // RunTests is an internal function but exported because it is cross-package;
  2434  // it is part of the implementation of the "go test" command.
  2435  func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {
  2436  	var deadline time.Time
  2437  	if *timeout > 0 {
  2438  		deadline = time.Now().Add(*timeout)
  2439  	}
  2440  	ran, ok := runTests(matchString, tests, deadline)
  2441  	if !ran && !haveExamples {
  2442  		fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  2443  	}
  2444  	return ok
  2445  }
  2446  
  2447  func runTests(matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
  2448  	ok = true
  2449  	for _, procs := range cpuList {
  2450  		runtime.GOMAXPROCS(procs)
  2451  		for i := uint(0); i < *count; i++ {
  2452  			if shouldFailFast() {
  2453  				break
  2454  			}
  2455  			if i > 0 && !ran {
  2456  				// There were no tests to run on the first
  2457  				// iteration. This won't change, so no reason
  2458  				// to keep trying.
  2459  				break
  2460  			}
  2461  			ctx, cancelCtx := context.WithCancel(context.Background())
  2462  			tstate := newTestState(*parallel, newMatcher(matchString, *match, "-test.run", *skip))
  2463  			tstate.deadline = deadline
  2464  			t := &T{
  2465  				common: common{
  2466  					signal:    make(chan bool, 1),
  2467  					barrier:   make(chan bool),
  2468  					w:         os.Stdout,
  2469  					ctx:       ctx,
  2470  					cancelCtx: cancelCtx,
  2471  				},
  2472  				tstate: tstate,
  2473  			}
  2474  			if Verbose() {
  2475  				t.chatty = newChattyPrinter(t.w)
  2476  			}
  2477  			tRunner(t, func(t *T) {
  2478  				for _, test := range tests {
  2479  					t.Run(test.Name, test.F)
  2480  				}
  2481  			})
  2482  			select {
  2483  			case <-t.signal:
  2484  			default:
  2485  				panic("internal error: tRunner exited without sending on t.signal")
  2486  			}
  2487  			ok = ok && !t.Failed()
  2488  			ran = ran || t.ran
  2489  		}
  2490  	}
  2491  	return ran, ok
  2492  }
  2493  
  2494  // before runs before all testing.
  2495  func (m *M) before() {
  2496  	if *memProfileRate > 0 {
  2497  		runtime.MemProfileRate = *memProfileRate
  2498  	}
  2499  	if *cpuProfile != "" {
  2500  		f, err := os.Create(toOutputDir(*cpuProfile))
  2501  		if err != nil {
  2502  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2503  			return
  2504  		}
  2505  		if err := m.deps.StartCPUProfile(f); err != nil {
  2506  			fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err)
  2507  			f.Close()
  2508  			return
  2509  		}
  2510  		// Could save f so after can call f.Close; not worth the effort.
  2511  	}
  2512  	if *traceFile != "" {
  2513  		f, err := os.Create(toOutputDir(*traceFile))
  2514  		if err != nil {
  2515  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2516  			return
  2517  		}
  2518  		if err := trace.Start(f); err != nil {
  2519  			fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err)
  2520  			f.Close()
  2521  			return
  2522  		}
  2523  		// Could save f so after can call f.Close; not worth the effort.
  2524  	}
  2525  	if *blockProfile != "" && *blockProfileRate >= 0 {
  2526  		runtime.SetBlockProfileRate(*blockProfileRate)
  2527  	}
  2528  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  2529  		runtime.SetMutexProfileFraction(*mutexProfileFraction)
  2530  	}
  2531  	if *coverProfile != "" && CoverMode() == "" {
  2532  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
  2533  		os.Exit(2)
  2534  	}
  2535  	if *gocoverdir != "" && CoverMode() == "" {
  2536  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.gocoverdir because test binary was not built with coverage enabled\n")
  2537  		os.Exit(2)
  2538  	}
  2539  	if *testlog != "" {
  2540  		// Note: Not using toOutputDir.
  2541  		// This file is for use by cmd/go, not users.
  2542  		var f *os.File
  2543  		var err error
  2544  		if m.numRun == 1 {
  2545  			f, err = os.Create(*testlog)
  2546  		} else {
  2547  			f, err = os.OpenFile(*testlog, os.O_WRONLY, 0)
  2548  			if err == nil {
  2549  				f.Seek(0, io.SeekEnd)
  2550  			}
  2551  		}
  2552  		if err != nil {
  2553  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2554  			os.Exit(2)
  2555  		}
  2556  		m.deps.StartTestLog(f)
  2557  		testlogFile = f
  2558  	}
  2559  	if *panicOnExit0 {
  2560  		m.deps.SetPanicOnExit0(true)
  2561  	}
  2562  }
  2563  
  2564  // after runs after all testing.
  2565  func (m *M) after() {
  2566  	m.afterOnce.Do(func() {
  2567  		m.writeProfiles()
  2568  	})
  2569  
  2570  	// Restore PanicOnExit0 after every run, because we set it to true before
  2571  	// every run. Otherwise, if m.Run is called multiple times the behavior of
  2572  	// os.Exit(0) will not be restored after the second run.
  2573  	if *panicOnExit0 {
  2574  		m.deps.SetPanicOnExit0(false)
  2575  	}
  2576  }
  2577  
  2578  func (m *M) writeProfiles() {
  2579  	if *testlog != "" {
  2580  		if err := m.deps.StopTestLog(); err != nil {
  2581  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  2582  			os.Exit(2)
  2583  		}
  2584  		if err := testlogFile.Close(); err != nil {
  2585  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  2586  			os.Exit(2)
  2587  		}
  2588  	}
  2589  	if *cpuProfile != "" {
  2590  		m.deps.StopCPUProfile() // flushes profile to disk
  2591  	}
  2592  	if *traceFile != "" {
  2593  		trace.Stop() // flushes trace to disk
  2594  	}
  2595  	if *memProfile != "" {
  2596  		f, err := os.Create(toOutputDir(*memProfile))
  2597  		if err != nil {
  2598  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2599  			os.Exit(2)
  2600  		}
  2601  		runtime.GC() // materialize all statistics
  2602  		if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil {
  2603  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err)
  2604  			os.Exit(2)
  2605  		}
  2606  		f.Close()
  2607  	}
  2608  	if *blockProfile != "" && *blockProfileRate >= 0 {
  2609  		f, err := os.Create(toOutputDir(*blockProfile))
  2610  		if err != nil {
  2611  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2612  			os.Exit(2)
  2613  		}
  2614  		if err = m.deps.WriteProfileTo("block", f, 0); err != nil {
  2615  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err)
  2616  			os.Exit(2)
  2617  		}
  2618  		f.Close()
  2619  	}
  2620  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  2621  		f, err := os.Create(toOutputDir(*mutexProfile))
  2622  		if err != nil {
  2623  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2624  			os.Exit(2)
  2625  		}
  2626  		if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil {
  2627  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err)
  2628  			os.Exit(2)
  2629  		}
  2630  		f.Close()
  2631  	}
  2632  	if CoverMode() != "" {
  2633  		coverReport()
  2634  	}
  2635  }
  2636  
  2637  // toOutputDir returns the file name relocated, if required, to outputDir.
  2638  // Simple implementation to avoid pulling in path/filepath.
  2639  func toOutputDir(path string) string {
  2640  	if *outputDir == "" || path == "" {
  2641  		return path
  2642  	}
  2643  	// On Windows, it's clumsy, but we can be almost always correct
  2644  	// by just looking for a drive letter and a colon.
  2645  	// Absolute paths always have a drive letter (ignoring UNC).
  2646  	// Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
  2647  	// what to do, but even then path/filepath doesn't help.
  2648  	// TODO: Worth doing better? Probably not, because we're here only
  2649  	// under the management of go test.
  2650  	if runtime.GOOS == "windows" && len(path) >= 2 {
  2651  		letter, colon := path[0], path[1]
  2652  		if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' {
  2653  			// If path starts with a drive letter we're stuck with it regardless.
  2654  			return path
  2655  		}
  2656  	}
  2657  	if os.IsPathSeparator(path[0]) {
  2658  		return path
  2659  	}
  2660  	return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path)
  2661  }
  2662  
  2663  // startAlarm starts an alarm if requested.
  2664  func (m *M) startAlarm() time.Time {
  2665  	if *timeout <= 0 {
  2666  		return time.Time{}
  2667  	}
  2668  
  2669  	deadline := time.Now().Add(*timeout)
  2670  	m.timer = time.AfterFunc(*timeout, func() {
  2671  		m.after()
  2672  		debug.SetTraceback("all")
  2673  		extra := ""
  2674  
  2675  		if list := runningList(); len(list) > 0 {
  2676  			var b strings.Builder
  2677  			b.WriteString("\nrunning tests:")
  2678  			for _, name := range list {
  2679  				b.WriteString("\n\t")
  2680  				b.WriteString(name)
  2681  			}
  2682  			extra = b.String()
  2683  		}
  2684  		panic(fmt.Sprintf("test timed out after %v%s", *timeout, extra))
  2685  	})
  2686  	return deadline
  2687  }
  2688  
  2689  // runningList returns the list of running tests.
  2690  func runningList() []string {
  2691  	var list []string
  2692  	running.Range(func(k, v any) bool {
  2693  		list = append(list, fmt.Sprintf("%s (%v)", k.(string), highPrecisionTimeSince(v.(highPrecisionTime)).Round(time.Second)))
  2694  		return true
  2695  	})
  2696  	slices.Sort(list)
  2697  	return list
  2698  }
  2699  
  2700  // stopAlarm turns off the alarm.
  2701  func (m *M) stopAlarm() {
  2702  	if *timeout > 0 {
  2703  		m.timer.Stop()
  2704  	}
  2705  }
  2706  
  2707  func parseCpuList() {
  2708  	for val := range strings.SplitSeq(*cpuListStr, ",") {
  2709  		val = strings.TrimSpace(val)
  2710  		if val == "" {
  2711  			continue
  2712  		}
  2713  		cpu, err := strconv.Atoi(val)
  2714  		if err != nil || cpu <= 0 {
  2715  			fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val)
  2716  			os.Exit(1)
  2717  		}
  2718  		cpuList = append(cpuList, cpu)
  2719  	}
  2720  	if cpuList == nil {
  2721  		cpuList = append(cpuList, runtime.GOMAXPROCS(-1))
  2722  	}
  2723  }
  2724  
  2725  func shouldFailFast() bool {
  2726  	return *failFast && numFailed.Load() > 0
  2727  }
  2728  

View as plain text