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  	_ "unsafe" // for linkname
   424  )
   425  
   426  var initRan bool
   427  
   428  var (
   429  	parallelStart atomic.Int64 // number of parallel tests started
   430  	parallelStop  atomic.Int64 // number of parallel tests stopped
   431  )
   432  
   433  // Init registers testing flags. These flags are automatically registered by
   434  // the "go test" command before running test functions, so Init is only needed
   435  // when calling functions such as Benchmark without using "go test".
   436  //
   437  // Init is not safe to call concurrently. It has no effect if it was already called.
   438  func Init() {
   439  	if initRan {
   440  		return
   441  	}
   442  	initRan = true
   443  	// The short flag requests that tests run more quickly, but its functionality
   444  	// is provided by test writers themselves. The testing package is just its
   445  	// home. The all.bash installation script sets it to make installation more
   446  	// efficient, but by default the flag is off so a plain "go test" will do a
   447  	// full test of the package.
   448  	short = flag.Bool("test.short", false, "run smaller test suite to save time")
   449  
   450  	// The failfast flag requests that test execution stop after the first test failure.
   451  	failFast = flag.Bool("test.failfast", false, "do not start new tests after the first test failure")
   452  
   453  	// The directory in which to create profile files and the like. When run from
   454  	// "go test", the binary always runs in the source directory for the package;
   455  	// this flag lets "go test" tell the binary to write the files in the directory where
   456  	// the "go test" command is run.
   457  	outputDir = flag.String("test.outputdir", "", "write profiles to `dir`")
   458  	artifacts = flag.Bool("test.artifacts", false, "store test artifacts in test.,outputdir")
   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  	artifacts            *bool
   493  	chatty               chattyFlag
   494  	count                *uint
   495  	coverProfile         *string
   496  	gocoverdir           *string
   497  	matchList            *string
   498  	match                *string
   499  	skip                 *string
   500  	memProfile           *string
   501  	memProfileRate       *int
   502  	cpuProfile           *string
   503  	blockProfile         *string
   504  	blockProfileRate     *int
   505  	mutexProfile         *string
   506  	mutexProfileFraction *int
   507  	panicOnExit0         *bool
   508  	traceFile            *string
   509  	timeout              *time.Duration
   510  	cpuListStr           *string
   511  	parallel             *int
   512  	shuffle              *string
   513  	testlog              *string
   514  	fullPath             *bool
   515  
   516  	haveExamples bool // are there examples?
   517  
   518  	cpuList     []int
   519  	testlogFile *os.File
   520  	artifactDir string
   521  
   522  	numFailed atomic.Uint32 // number of test failures
   523  
   524  	running sync.Map // map[string]time.Time of running, unpaused tests
   525  )
   526  
   527  type chattyFlag struct {
   528  	on   bool // -v is set in some form
   529  	json bool // -v=test2json is set, to make output better for test2json
   530  }
   531  
   532  func (*chattyFlag) IsBoolFlag() bool { return true }
   533  
   534  func (f *chattyFlag) Set(arg string) error {
   535  	switch arg {
   536  	default:
   537  		return fmt.Errorf("invalid flag -test.v=%s", arg)
   538  	case "true", "test2json":
   539  		f.on = true
   540  		f.json = arg == "test2json"
   541  	case "false":
   542  		f.on = false
   543  		f.json = false
   544  	}
   545  	return nil
   546  }
   547  
   548  func (f *chattyFlag) String() string {
   549  	if f.json {
   550  		return "test2json"
   551  	}
   552  	if f.on {
   553  		return "true"
   554  	}
   555  	return "false"
   556  }
   557  
   558  func (f *chattyFlag) Get() any {
   559  	if f.json {
   560  		return "test2json"
   561  	}
   562  	return f.on
   563  }
   564  
   565  const (
   566  	markFraming  byte = 'V' &^ '@' // ^V: framing
   567  	markErrBegin byte = 'O' &^ '@' // ^O: start of error
   568  	markErrEnd   byte = 'N' &^ '@' // ^N: end of error
   569  	markEscape   byte = '[' &^ '@' // ^[: escape
   570  )
   571  
   572  func (f *chattyFlag) prefix() string {
   573  	if f.json {
   574  		return string(markFraming)
   575  	}
   576  	return ""
   577  }
   578  
   579  type chattyPrinter struct {
   580  	w          io.Writer
   581  	lastNameMu sync.Mutex // guards lastName
   582  	lastName   string     // last printed test name in chatty mode
   583  	json       bool       // -v=json output mode
   584  }
   585  
   586  func newChattyPrinter(w io.Writer) *chattyPrinter {
   587  	return &chattyPrinter{w: w, json: chatty.json}
   588  }
   589  
   590  // prefix is like chatty.prefix but using p.json instead of chatty.json.
   591  // Using p.json allows tests to check the json behavior without modifying
   592  // the global variable. For convenience, we allow p == nil and treat
   593  // that as not in json mode (because it's not chatty at all).
   594  func (p *chattyPrinter) prefix() string {
   595  	if p != nil && p.json {
   596  		return string(markFraming)
   597  	}
   598  	return ""
   599  }
   600  
   601  // Updatef prints a message about the status of the named test to w.
   602  //
   603  // The formatted message must include the test name itself.
   604  func (p *chattyPrinter) Updatef(testName, format string, args ...any) {
   605  	p.lastNameMu.Lock()
   606  	defer p.lastNameMu.Unlock()
   607  
   608  	// Since the message already implies an association with a specific new test,
   609  	// we don't need to check what the old test name was or log an extra NAME line
   610  	// for it. (We're updating it anyway, and the current message already includes
   611  	// the test name.)
   612  	p.lastName = testName
   613  	fmt.Fprintf(p.w, p.prefix()+format, args...)
   614  }
   615  
   616  // Printf prints a message, generated by the named test, that does not
   617  // necessarily mention that tests's name itself.
   618  func (p *chattyPrinter) Printf(testName, format string, args ...any) {
   619  	p.lastNameMu.Lock()
   620  	defer p.lastNameMu.Unlock()
   621  
   622  	if p.lastName == "" {
   623  		p.lastName = testName
   624  	} else if p.lastName != testName {
   625  		fmt.Fprintf(p.w, "%s=== NAME  %s\n", p.prefix(), testName)
   626  		p.lastName = testName
   627  	}
   628  
   629  	fmt.Fprintf(p.w, format, args...)
   630  }
   631  
   632  type stringWriter interface {
   633  	io.Writer
   634  	io.StringWriter
   635  }
   636  
   637  // escapeWriter is a [io.Writer] that escapes test framing markers.
   638  type escapeWriter struct {
   639  	w stringWriter
   640  }
   641  
   642  func (w escapeWriter) WriteString(s string) (int, error) {
   643  	return w.Write([]byte(s))
   644  }
   645  
   646  func (w escapeWriter) Write(p []byte) (int, error) {
   647  	var n, m int
   648  	var err error
   649  	for len(p) > 0 {
   650  		i := w.nextMark(p)
   651  		if i < 0 {
   652  			break
   653  		}
   654  
   655  		m, err = w.w.Write(p[:i])
   656  		n += m
   657  		if err != nil {
   658  			break
   659  		}
   660  
   661  		m, err = w.w.Write([]byte{markEscape, p[i]})
   662  		if err != nil {
   663  			break
   664  		}
   665  		if m != 2 {
   666  			return n, fmt.Errorf("short write")
   667  		}
   668  		n++
   669  		p = p[i+1:]
   670  	}
   671  	m, err = w.w.Write(p)
   672  	n += m
   673  	return n, err
   674  }
   675  
   676  func (escapeWriter) nextMark(p []byte) int {
   677  	for i, b := range p {
   678  		switch b {
   679  		case markFraming, markErrBegin, markErrEnd, markEscape:
   680  			return i
   681  		}
   682  	}
   683  	return -1
   684  }
   685  
   686  // The maximum number of stack frames to go through when skipping helper functions for
   687  // the purpose of decorating log messages.
   688  const maxStackLen = 50
   689  
   690  // common holds the elements common between T and B and
   691  // captures common methods such as Errorf.
   692  type common struct {
   693  	mu          sync.RWMutex         // guards this group of fields
   694  	output      []byte               // Output generated by test or benchmark.
   695  	w           io.Writer            // For flushToParent.
   696  	o           *outputWriter        // Writes output.
   697  	ran         bool                 // Test or benchmark (or one of its subtests) was executed.
   698  	failed      bool                 // Test or benchmark has failed.
   699  	skipped     bool                 // Test or benchmark has been skipped.
   700  	done        bool                 // Test is finished and all subtests have completed.
   701  	helperPCs   map[uintptr]struct{} // functions to be skipped when writing file/line info
   702  	helperNames map[string]struct{}  // helperPCs converted to function names
   703  	cleanups    []func()             // optional functions to be called at the end of the test
   704  	cleanupName string               // Name of the cleanup function.
   705  	cleanupPc   []uintptr            // The stack trace at the point where Cleanup was called.
   706  	finished    bool                 // Test function has completed.
   707  	inFuzzFn    bool                 // Whether the fuzz target, if this is one, is running.
   708  	isSynctest  bool
   709  
   710  	chatty         *chattyPrinter // A copy of chattyPrinter, if the chatty flag is set.
   711  	bench          bool           // Whether the current test is a benchmark.
   712  	hasSub         atomic.Bool    // whether there are sub-benchmarks.
   713  	cleanupStarted atomic.Bool    // Registered cleanup callbacks have started to execute
   714  	runner         string         // Function name of tRunner running the test.
   715  	isParallel     bool           // Whether the test is parallel.
   716  
   717  	parent     *common
   718  	level      int       // Nesting depth of test or benchmark.
   719  	creator    []uintptr // If level > 0, the stack trace at the point where the parent called t.Run.
   720  	modulePath string
   721  	importPath string
   722  	name       string            // Name of test or benchmark.
   723  	start      highPrecisionTime // Time test or benchmark started
   724  	duration   time.Duration
   725  	barrier    chan bool // To signal parallel subtests they may start. Nil when T.Parallel is not present (B) or not usable (when fuzzing).
   726  	signal     chan bool // To signal a test is done.
   727  	sub        []*T      // Queue of subtests to be run in parallel.
   728  
   729  	lastRaceErrors  atomic.Int64 // Max value of race.Errors seen during the test or its subtests.
   730  	raceErrorLogged atomic.Bool
   731  
   732  	tempDirMu  sync.Mutex
   733  	tempDir    string
   734  	tempDirErr error
   735  	tempDirSeq int32
   736  
   737  	artifactDirOnce sync.Once
   738  	artifactDir     string
   739  	artifactDirErr  error
   740  
   741  	ctx       context.Context
   742  	cancelCtx context.CancelFunc
   743  }
   744  
   745  // Short reports whether the -test.short flag is set.
   746  func Short() bool {
   747  	if short == nil {
   748  		panic("testing: Short called before Init")
   749  	}
   750  	// Catch code that calls this from TestMain without first calling flag.Parse.
   751  	if !flag.Parsed() {
   752  		panic("testing: Short called before Parse")
   753  	}
   754  
   755  	return *short
   756  }
   757  
   758  // testBinary is set by cmd/go to "1" if this is a binary built by "go test".
   759  // The value is set to "1" by a -X option to cmd/link. We assume that
   760  // because this is possible, the compiler will not optimize testBinary
   761  // into a constant on the basis that it is an unexported package-scope
   762  // variable that is never changed. If the compiler ever starts implementing
   763  // such an optimization, we will need some technique to mark this variable
   764  // as "changed by a cmd/link -X option".
   765  var testBinary = "0"
   766  
   767  // Testing reports whether the current code is being run in a test.
   768  // This will report true in programs created by "go test",
   769  // false in programs created by "go build".
   770  func Testing() bool {
   771  	return testBinary == "1"
   772  }
   773  
   774  // CoverMode reports what the test coverage mode is set to. The
   775  // values are "set", "count", or "atomic". The return value will be
   776  // empty if test coverage is not enabled.
   777  func CoverMode() string {
   778  	return cover.mode
   779  }
   780  
   781  // Verbose reports whether the -test.v flag is set.
   782  func Verbose() bool {
   783  	// Same as in Short.
   784  	if !flag.Parsed() {
   785  		panic("testing: Verbose called before Parse")
   786  	}
   787  	return chatty.on
   788  }
   789  
   790  func (c *common) checkFuzzFn(name string) {
   791  	if c.inFuzzFn {
   792  		panic(fmt.Sprintf("testing: f.%s was called inside the fuzz target, use t.%s instead", name, name))
   793  	}
   794  }
   795  
   796  // frameSkip searches, starting after skip frames, for the first caller frame
   797  // in a function not marked as a helper and returns that frame.
   798  // The search stops if it finds a tRunner function that
   799  // was the entry point into the test and the test is not a subtest.
   800  // This function must be called with c.mu held.
   801  func (c *common) frameSkip(skip int) runtime.Frame {
   802  	// If the search continues into the parent test, we'll have to hold
   803  	// its mu temporarily. If we then return, we need to unlock it.
   804  	shouldUnlock := false
   805  	defer func() {
   806  		if shouldUnlock {
   807  			c.mu.Unlock()
   808  		}
   809  	}()
   810  	var pc [maxStackLen]uintptr
   811  	// Skip two extra frames to account for this function
   812  	// and runtime.Callers itself.
   813  	n := runtime.Callers(skip+2, pc[:])
   814  	if n == 0 {
   815  		panic("testing: zero callers found")
   816  	}
   817  	frames := runtime.CallersFrames(pc[:n])
   818  	var firstFrame, prevFrame, frame runtime.Frame
   819  	skipRange := false
   820  	for more := true; more; prevFrame = frame {
   821  		frame, more = frames.Next()
   822  		if skipRange {
   823  			// Skip the iterator function when a helper
   824  			// functions does a range over function.
   825  			skipRange = false
   826  			continue
   827  		}
   828  		if frame.Function == "runtime.gopanic" {
   829  			continue
   830  		}
   831  		if frame.Function == c.cleanupName {
   832  			frames = runtime.CallersFrames(c.cleanupPc)
   833  			continue
   834  		}
   835  		if firstFrame.PC == 0 {
   836  			firstFrame = frame
   837  		}
   838  		if frame.Function == c.runner {
   839  			// We've gone up all the way to the tRunner calling
   840  			// the test function (so the user must have
   841  			// called tb.Helper from inside that test function).
   842  			// If this is a top-level test, only skip up to the test function itself.
   843  			// If we're in a subtest, continue searching in the parent test,
   844  			// starting from the point of the call to Run which created this subtest.
   845  			if c.level > 1 {
   846  				frames = runtime.CallersFrames(c.creator)
   847  				parent := c.parent
   848  				// We're no longer looking at the current c after this point,
   849  				// so we should unlock its mu, unless it's the original receiver,
   850  				// in which case our caller doesn't expect us to do that.
   851  				if shouldUnlock {
   852  					c.mu.Unlock()
   853  				}
   854  				c = parent
   855  				// Remember to unlock c.mu when we no longer need it, either
   856  				// because we went up another nesting level, or because we
   857  				// returned.
   858  				shouldUnlock = true
   859  				c.mu.Lock()
   860  				continue
   861  			}
   862  			return prevFrame
   863  		}
   864  		// If more helper PCs have been added since we last did the conversion
   865  		if c.helperNames == nil {
   866  			c.helperNames = make(map[string]struct{})
   867  			for pc := range c.helperPCs {
   868  				c.helperNames[pcToName(pc)] = struct{}{}
   869  			}
   870  		}
   871  
   872  		fnName := frame.Function
   873  		// Ignore trailing -rangeN used for iterator functions.
   874  		const rangeSuffix = "-range"
   875  		if suffixIdx := strings.LastIndex(fnName, rangeSuffix); suffixIdx > 0 {
   876  			ok := true
   877  			for i := suffixIdx + len(rangeSuffix); i < len(fnName); i++ {
   878  				if fnName[i] < '0' || fnName[i] > '9' {
   879  					ok = false
   880  					break
   881  				}
   882  			}
   883  			if ok {
   884  				fnName = fnName[:suffixIdx]
   885  				skipRange = true
   886  			}
   887  		}
   888  
   889  		if _, ok := c.helperNames[fnName]; !ok {
   890  			// Found a frame that wasn't inside a helper function.
   891  			return frame
   892  		}
   893  	}
   894  	return firstFrame
   895  }
   896  
   897  // flushToParent writes c.output to the parent after first writing the header
   898  // with the given format and arguments.
   899  func (c *common) flushToParent(testName, format string, args ...any) {
   900  	p := c.parent
   901  	p.mu.Lock()
   902  	defer p.mu.Unlock()
   903  
   904  	c.mu.Lock()
   905  	defer c.mu.Unlock()
   906  
   907  	if len(c.output) > 0 {
   908  		// Add the current c.output to the print,
   909  		// and then arrange for the print to replace c.output.
   910  		// (This displays the logged output after the --- FAIL line.)
   911  		format += "%s"
   912  		args = append(args[:len(args):len(args)], c.output)
   913  		c.output = c.output[:0]
   914  	}
   915  
   916  	if c.chatty != nil && (p.w == c.chatty.w || c.chatty.json) {
   917  		// We're flushing to the actual output, so track that this output is
   918  		// associated with a specific test (and, specifically, that the next output
   919  		// is *not* associated with that test).
   920  		//
   921  		// Moreover, if c.output is non-empty it is important that this write be
   922  		// atomic with respect to the output of other tests, so that we don't end up
   923  		// with confusing '=== NAME' lines in the middle of our '--- PASS' block.
   924  		// Neither humans nor cmd/test2json can parse those easily.
   925  		// (See https://go.dev/issue/40771.)
   926  		//
   927  		// If test2json is used, we never flush to parent tests,
   928  		// so that the json stream shows subtests as they finish.
   929  		// (See https://go.dev/issue/29811.)
   930  		c.chatty.Updatef(testName, format, args...)
   931  	} else {
   932  		// We're flushing to the output buffer of the parent test, which will
   933  		// itself follow a test-name header when it is finally flushed to stdout.
   934  		fmt.Fprintf(p.w, c.chatty.prefix()+format, args...)
   935  	}
   936  }
   937  
   938  type indenter struct {
   939  	c *common
   940  }
   941  
   942  const indent = "    "
   943  
   944  func (w indenter) Write(b []byte) (n int, err error) {
   945  	n = len(b)
   946  	for len(b) > 0 {
   947  		end := bytes.IndexByte(b, '\n')
   948  		if end == -1 {
   949  			end = len(b)
   950  		} else {
   951  			end++
   952  		}
   953  		// An indent of 4 spaces will neatly align the dashes with the status
   954  		// indicator of the parent.
   955  		line := b[:end]
   956  		if line[0] == markFraming {
   957  			w.c.output = append(w.c.output, markFraming)
   958  			line = line[1:]
   959  		}
   960  		w.c.output = append(w.c.output, indent...)
   961  		w.c.output = append(w.c.output, line...)
   962  		b = b[end:]
   963  	}
   964  	return
   965  }
   966  
   967  // fmtDuration returns a string representing d in the form "87.00s".
   968  func fmtDuration(d time.Duration) string {
   969  	return fmt.Sprintf("%.2fs", d.Seconds())
   970  }
   971  
   972  // TB is the interface common to [T], [B], and [F].
   973  type TB interface {
   974  	ArtifactDir() string
   975  	Attr(key, value string)
   976  	Cleanup(func())
   977  	Error(args ...any)
   978  	Errorf(format string, args ...any)
   979  	Fail()
   980  	FailNow()
   981  	Failed() bool
   982  	Fatal(args ...any)
   983  	Fatalf(format string, args ...any)
   984  	Helper()
   985  	Log(args ...any)
   986  	Logf(format string, args ...any)
   987  	Name() string
   988  	Setenv(key, value string)
   989  	Chdir(dir string)
   990  	Skip(args ...any)
   991  	SkipNow()
   992  	Skipf(format string, args ...any)
   993  	Skipped() bool
   994  	TempDir() string
   995  	Context() context.Context
   996  	Output() io.Writer
   997  
   998  	// A private method to prevent users implementing the
   999  	// interface and so future additions to it will not
  1000  	// violate Go 1 compatibility.
  1001  	private()
  1002  }
  1003  
  1004  var (
  1005  	_ TB = (*T)(nil)
  1006  	_ TB = (*B)(nil)
  1007  )
  1008  
  1009  // T is a type passed to Test functions to manage test state and support formatted test logs.
  1010  //
  1011  // A test ends when its Test function returns or calls any of the methods
  1012  // [T.FailNow], [T.Fatal], [T.Fatalf], [T.SkipNow], [T.Skip], or [T.Skipf]. Those methods, as well as
  1013  // the [T.Parallel] method, must be called only from the goroutine running the
  1014  // Test function.
  1015  //
  1016  // The other reporting methods, such as the variations of [T.Log] and [T.Error],
  1017  // may be called simultaneously from multiple goroutines.
  1018  type T struct {
  1019  	common
  1020  	// denyParallel, if non-empty, is the operation (such as "t.Setenv") that
  1021  	// forbids a later call to t.Parallel.
  1022  	denyParallel string
  1023  	tstate       *testState // For running tests and subtests.
  1024  }
  1025  
  1026  func (c *common) private() {}
  1027  
  1028  // Name returns the name of the running (sub-) test or benchmark.
  1029  //
  1030  // The name will include the name of the test along with the names of
  1031  // any nested sub-tests. If two sibling sub-tests have the same name,
  1032  // Name will append a suffix to guarantee the returned name is unique.
  1033  func (c *common) Name() string {
  1034  	return c.name
  1035  }
  1036  
  1037  func (c *common) setRan() {
  1038  	if c.parent != nil {
  1039  		c.parent.setRan()
  1040  	}
  1041  	c.mu.Lock()
  1042  	defer c.mu.Unlock()
  1043  	c.ran = true
  1044  }
  1045  
  1046  // Fail marks the function as having failed but continues execution.
  1047  func (c *common) Fail() {
  1048  	if c.parent != nil {
  1049  		c.parent.Fail()
  1050  	}
  1051  	c.mu.Lock()
  1052  	defer c.mu.Unlock()
  1053  	// c.done needs to be locked to synchronize checks to c.done in parent tests.
  1054  	if c.done {
  1055  		panic("Fail in goroutine after " + c.name + " has completed")
  1056  	}
  1057  	c.failed = true
  1058  }
  1059  
  1060  // Failed reports whether the function has failed.
  1061  func (c *common) Failed() bool {
  1062  	c.mu.RLock()
  1063  	defer c.mu.RUnlock()
  1064  
  1065  	if !c.done && int64(race.Errors()) > c.lastRaceErrors.Load() {
  1066  		c.mu.RUnlock()
  1067  		c.checkRaces()
  1068  		c.mu.RLock()
  1069  	}
  1070  
  1071  	return c.failed
  1072  }
  1073  
  1074  // FailNow marks the function as having failed and stops its execution
  1075  // by calling [runtime.Goexit] (which then runs all deferred calls in the
  1076  // current goroutine).
  1077  // Execution will continue at the next test or benchmark.
  1078  // FailNow must be called from the goroutine running the
  1079  // test or benchmark function, not from other goroutines
  1080  // created during the test. Calling FailNow does not stop
  1081  // those other goroutines.
  1082  func (c *common) FailNow() {
  1083  	c.checkFuzzFn("FailNow")
  1084  	c.Fail()
  1085  
  1086  	// Calling runtime.Goexit will exit the goroutine, which
  1087  	// will run the deferred functions in this goroutine,
  1088  	// which will eventually run the deferred lines in tRunner,
  1089  	// which will signal to the test loop that this test is done.
  1090  	//
  1091  	// A previous version of this code said:
  1092  	//
  1093  	//	c.duration = ...
  1094  	//	c.signal <- c.self
  1095  	//	runtime.Goexit()
  1096  	//
  1097  	// This previous version duplicated code (those lines are in
  1098  	// tRunner no matter what), but worse the goroutine teardown
  1099  	// implicit in runtime.Goexit was not guaranteed to complete
  1100  	// before the test exited. If a test deferred an important cleanup
  1101  	// function (like removing temporary files), there was no guarantee
  1102  	// it would run on a test failure. Because we send on c.signal during
  1103  	// a top-of-stack deferred function now, we know that the send
  1104  	// only happens after any other stacked defers have completed.
  1105  	c.mu.Lock()
  1106  	c.finished = true
  1107  	c.mu.Unlock()
  1108  	runtime.Goexit()
  1109  }
  1110  
  1111  // log generates the output. It is always at the same stack depth. log inserts
  1112  // indentation and the final newline if necessary. It prefixes the string
  1113  // with the file and line of the call site.
  1114  func (c *common) log(s string, isErr bool) {
  1115  	s = strings.TrimSuffix(s, "\n")
  1116  
  1117  	// Second and subsequent lines are indented 4 spaces. This is in addition to
  1118  	// the indentation provided by outputWriter.
  1119  	s = strings.ReplaceAll(s, "\n", "\n"+indent)
  1120  	s += "\n"
  1121  
  1122  	n := c.destination()
  1123  	if n == nil {
  1124  		// The test and all its parents are done. The log cannot be output.
  1125  		panic("Log in goroutine after " + c.name + " has completed: " + s)
  1126  	}
  1127  
  1128  	// Prefix with the call site. It is located by skipping 3 functions:
  1129  	// callSite + log + public function
  1130  	s = n.callSite(3) + s
  1131  
  1132  	// Output buffered logs.
  1133  	n.flushPartial()
  1134  
  1135  	n.o.write([]byte(s), isErr)
  1136  }
  1137  
  1138  // destination selects the test to which output should be appended. It returns the
  1139  // test if it is incomplete. Otherwise, it finds its closest incomplete parent.
  1140  func (c *common) destination() *common {
  1141  	c.mu.Lock()
  1142  	defer c.mu.Unlock()
  1143  
  1144  	if !c.done && !c.isSynctest {
  1145  		return c
  1146  	}
  1147  	for parent := c.parent; parent != nil; parent = parent.parent {
  1148  		parent.mu.Lock()
  1149  		defer parent.mu.Unlock()
  1150  		if !parent.done {
  1151  			return parent
  1152  		}
  1153  	}
  1154  	return nil
  1155  }
  1156  
  1157  // callSite retrieves and formats the file and line of the call site.
  1158  func (c *common) callSite(skip int) string {
  1159  	c.mu.Lock()
  1160  	defer c.mu.Unlock()
  1161  
  1162  	frame := c.frameSkip(skip)
  1163  	file := frame.File
  1164  	line := frame.Line
  1165  	if file != "" {
  1166  		if *fullPath {
  1167  			// If relative path, truncate file name at last file name separator.
  1168  		} else {
  1169  			file = filepath.Base(file)
  1170  		}
  1171  	} else {
  1172  		file = "???"
  1173  	}
  1174  	if line == 0 {
  1175  		line = 1
  1176  	}
  1177  
  1178  	return fmt.Sprintf("%s:%d: ", file, line)
  1179  }
  1180  
  1181  // flushPartial checks the buffer for partial logs and outputs them.
  1182  func (c *common) flushPartial() {
  1183  	partial := func() bool {
  1184  		c.mu.Lock()
  1185  		defer c.mu.Unlock()
  1186  		return (c.o != nil) && (len(c.o.partial) > 0)
  1187  	}
  1188  
  1189  	if partial() {
  1190  		c.o.Write([]byte("\n"))
  1191  	}
  1192  }
  1193  
  1194  // Output returns a Writer that writes to the same test output stream as TB.Log.
  1195  // The output is indented like TB.Log lines, but Output does not
  1196  // add source locations or newlines. The output is internally line
  1197  // buffered, and a call to TB.Log or the end of the test will implicitly
  1198  // flush the buffer, followed by a newline. After a test function and all its
  1199  // parents return, neither Output nor the Write method may be called.
  1200  func (c *common) Output() io.Writer {
  1201  	c.checkFuzzFn("Output")
  1202  	n := c.destination()
  1203  	if n == nil {
  1204  		panic("Output called after " + c.name + " has completed")
  1205  	}
  1206  	return n.o
  1207  }
  1208  
  1209  // setOutputWriter initializes an outputWriter and sets it as a common field.
  1210  func (c *common) setOutputWriter() {
  1211  	c.o = &outputWriter{c: c}
  1212  }
  1213  
  1214  // outputWriter buffers, formats and writes log messages.
  1215  type outputWriter struct {
  1216  	c       *common
  1217  	partial []byte // incomplete ('\n'-free) suffix of last Write
  1218  }
  1219  
  1220  // Write writes a log message to the test's output stream, properly formatted and
  1221  // indented. It may not be called after a test function and all its parents return.
  1222  func (o *outputWriter) Write(p []byte) (int, error) {
  1223  	return o.write(p, false)
  1224  }
  1225  
  1226  func (o *outputWriter) write(p []byte, isErr bool) (int, error) {
  1227  	// o can be nil if this is called from a top-level *TB that is no longer active.
  1228  	// Just ignore the message in that case.
  1229  	if o == nil || o.c == nil {
  1230  		return 0, nil
  1231  	}
  1232  	if o.c.destination() == nil {
  1233  		panic("Write called after " + o.c.name + " has completed")
  1234  	}
  1235  
  1236  	o.c.mu.Lock()
  1237  	defer o.c.mu.Unlock()
  1238  
  1239  	// The last element is a partial line.
  1240  	lines := bytes.SplitAfter(p, []byte("\n"))
  1241  	last := len(lines) - 1 // Inv: 0 <= last
  1242  	for i, line := range lines[:last] {
  1243  		// Emit partial line from previous call.
  1244  		if i == 0 && len(o.partial) > 0 {
  1245  			line = slices.Concat(o.partial, line)
  1246  			o.partial = o.partial[:0]
  1247  		}
  1248  		o.writeLine(line, isErr && i == 0, isErr && i == last-1)
  1249  	}
  1250  	// Save partial line for next call.
  1251  	o.partial = append(o.partial, lines[last]...)
  1252  
  1253  	return len(p), nil
  1254  }
  1255  
  1256  // writeLine generates the output for a given line.
  1257  func (o *outputWriter) writeLine(b []byte, errBegin, errEnd bool) {
  1258  	if o.c.done || (o.c.chatty == nil) {
  1259  		o.c.output = append(o.c.output, indent...)
  1260  		o.c.output = append(o.c.output, b...)
  1261  		return
  1262  	}
  1263  
  1264  	// Escape the framing marker.
  1265  	if o.c.chatty.json {
  1266  		b = escapeMarkers(b)
  1267  	}
  1268  
  1269  	// If this is the start of an error, add ^O to the start of the output.
  1270  	var strErrBegin, strErrEnd string
  1271  	if errBegin && o.c.chatty.json {
  1272  		strErrBegin = string(markErrBegin)
  1273  	}
  1274  
  1275  	// If this is the end of an error, add ^N to the end of the output. If the
  1276  	// last character of the output is \n, add ^N before the \n, otherwise
  1277  	// test2json will not handle it correctly.
  1278  	var c []byte
  1279  	if errEnd && o.c.chatty.json {
  1280  		i := len(b)
  1281  		if len(b) > 0 && b[i-1] == '\n' {
  1282  			b, c = b[:i-1], b[i-1:]
  1283  		}
  1284  		strErrEnd = string(markErrEnd)
  1285  	}
  1286  
  1287  	if o.c.bench {
  1288  		// Benchmarks don't print === CONT, so we should skip the test
  1289  		// printer and just print straight to stdout.
  1290  		fmt.Printf("%s%s%s%s%s", strErrBegin, indent, b, strErrEnd, c)
  1291  	} else {
  1292  		o.c.chatty.Printf(o.c.name, "%s%s%s%s%s", strErrBegin, indent, b, strErrEnd, c)
  1293  	}
  1294  }
  1295  
  1296  func escapeMarkers(b []byte) []byte {
  1297  	j := nextMark(b)
  1298  	if j < 0 {
  1299  		// Allocation-free fast path.
  1300  		return b
  1301  	}
  1302  
  1303  	c := make([]byte, 0, len(b)+10)
  1304  	i := 0
  1305  	for i < len(b) && j >= i {
  1306  		if j > i {
  1307  			c = append(c, b[i:j]...)
  1308  		}
  1309  		c = append(c, markEscape, b[j])
  1310  		i = j + 1
  1311  		j = i + nextMark(b[i:])
  1312  	}
  1313  	if i < len(b) {
  1314  		c = append(c, b[i:]...)
  1315  	}
  1316  	return c
  1317  }
  1318  
  1319  func nextMark(b []byte) int {
  1320  	for i, b := range b {
  1321  		switch b {
  1322  		case markFraming, markEscape, markErrBegin, markErrEnd:
  1323  			return i
  1324  		}
  1325  	}
  1326  	return -1
  1327  }
  1328  
  1329  // Log formats its arguments using default formatting, analogous to [fmt.Println],
  1330  // and records the text in the error log. For tests, the text will be printed only if
  1331  // the test fails or the -test.v flag is set. For benchmarks, the text is always
  1332  // printed to avoid having performance depend on the value of the -test.v flag.
  1333  // It is an error to call Log after a test or benchmark returns.
  1334  func (c *common) Log(args ...any) {
  1335  	c.checkFuzzFn("Log")
  1336  	c.log(fmt.Sprintln(args...), false)
  1337  }
  1338  
  1339  // Logf formats its arguments according to the format, analogous to [fmt.Printf], and
  1340  // records the text in the error log. A final newline is added if not provided. For
  1341  // tests, the text will be printed only if the test fails or the -test.v flag is
  1342  // set. For benchmarks, the text is always printed to avoid having performance
  1343  // depend on the value of the -test.v flag.
  1344  // It is an error to call Logf after a test or benchmark returns.
  1345  func (c *common) Logf(format string, args ...any) {
  1346  	c.checkFuzzFn("Logf")
  1347  	c.log(fmt.Sprintf(format, args...), false)
  1348  }
  1349  
  1350  // Error is equivalent to Log followed by Fail.
  1351  func (c *common) Error(args ...any) {
  1352  	c.checkFuzzFn("Error")
  1353  	c.log(fmt.Sprintln(args...), true)
  1354  	c.Fail()
  1355  }
  1356  
  1357  // Errorf is equivalent to Logf followed by Fail.
  1358  func (c *common) Errorf(format string, args ...any) {
  1359  	c.checkFuzzFn("Errorf")
  1360  	c.log(fmt.Sprintf(format, args...), true)
  1361  	c.Fail()
  1362  }
  1363  
  1364  // Fatal is equivalent to Log followed by FailNow.
  1365  func (c *common) Fatal(args ...any) {
  1366  	c.checkFuzzFn("Fatal")
  1367  	c.log(fmt.Sprintln(args...), true)
  1368  	c.FailNow()
  1369  }
  1370  
  1371  // Fatalf is equivalent to Logf followed by FailNow.
  1372  func (c *common) Fatalf(format string, args ...any) {
  1373  	c.checkFuzzFn("Fatalf")
  1374  	c.log(fmt.Sprintf(format, args...), true)
  1375  	c.FailNow()
  1376  }
  1377  
  1378  // Skip is equivalent to Log followed by SkipNow.
  1379  func (c *common) Skip(args ...any) {
  1380  	c.checkFuzzFn("Skip")
  1381  	c.log(fmt.Sprintln(args...), false)
  1382  	c.SkipNow()
  1383  }
  1384  
  1385  // Skipf is equivalent to Logf followed by SkipNow.
  1386  func (c *common) Skipf(format string, args ...any) {
  1387  	c.checkFuzzFn("Skipf")
  1388  	c.log(fmt.Sprintf(format, args...), false)
  1389  	c.SkipNow()
  1390  }
  1391  
  1392  // SkipNow marks the test as having been skipped and stops its execution
  1393  // by calling [runtime.Goexit].
  1394  // If a test fails (see Error, Errorf, Fail) and is then skipped,
  1395  // it is still considered to have failed.
  1396  // Execution will continue at the next test or benchmark. See also FailNow.
  1397  // SkipNow must be called from the goroutine running the test, not from
  1398  // other goroutines created during the test. Calling SkipNow does not stop
  1399  // those other goroutines.
  1400  func (c *common) SkipNow() {
  1401  	c.checkFuzzFn("SkipNow")
  1402  	c.mu.Lock()
  1403  	c.skipped = true
  1404  	c.finished = true
  1405  	c.mu.Unlock()
  1406  	runtime.Goexit()
  1407  }
  1408  
  1409  // Skipped reports whether the test was skipped.
  1410  func (c *common) Skipped() bool {
  1411  	c.mu.RLock()
  1412  	defer c.mu.RUnlock()
  1413  	return c.skipped
  1414  }
  1415  
  1416  // Helper marks the calling function as a test helper function.
  1417  // When printing file and line information, that function will be skipped.
  1418  // Helper may be called simultaneously from multiple goroutines.
  1419  func (c *common) Helper() {
  1420  	if c.isSynctest {
  1421  		c = c.parent
  1422  	}
  1423  	c.mu.Lock()
  1424  	defer c.mu.Unlock()
  1425  	if c.helperPCs == nil {
  1426  		c.helperPCs = make(map[uintptr]struct{})
  1427  	}
  1428  	// repeating code from callerName here to save walking a stack frame
  1429  	var pc [1]uintptr
  1430  	n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper
  1431  	if n == 0 {
  1432  		panic("testing: zero callers found")
  1433  	}
  1434  	if _, found := c.helperPCs[pc[0]]; !found {
  1435  		c.helperPCs[pc[0]] = struct{}{}
  1436  		c.helperNames = nil // map will be recreated next time it is needed
  1437  	}
  1438  }
  1439  
  1440  // Cleanup registers a function to be called when the test (or subtest) and all its
  1441  // subtests complete. Cleanup functions will be called in last added,
  1442  // first called order.
  1443  func (c *common) Cleanup(f func()) {
  1444  	c.checkFuzzFn("Cleanup")
  1445  	var pc [maxStackLen]uintptr
  1446  	// Skip two extra frames to account for this function and runtime.Callers itself.
  1447  	n := runtime.Callers(2, pc[:])
  1448  	cleanupPc := pc[:n]
  1449  
  1450  	fn := func() {
  1451  		defer func() {
  1452  			c.mu.Lock()
  1453  			defer c.mu.Unlock()
  1454  			c.cleanupName = ""
  1455  			c.cleanupPc = nil
  1456  		}()
  1457  
  1458  		name := callerName(0)
  1459  		c.mu.Lock()
  1460  		c.cleanupName = name
  1461  		c.cleanupPc = cleanupPc
  1462  		c.mu.Unlock()
  1463  
  1464  		f()
  1465  	}
  1466  
  1467  	c.mu.Lock()
  1468  	defer c.mu.Unlock()
  1469  	c.cleanups = append(c.cleanups, fn)
  1470  }
  1471  
  1472  // ArtifactDir returns a directory in which the test should store output files.
  1473  // When the -artifacts flag is provided, this directory is located
  1474  // under the output directory. Otherwise, ArtifactDir returns a temporary directory
  1475  // that is removed after the test completes.
  1476  //
  1477  // Each test or subtest within each test package has a unique artifact directory.
  1478  // Repeated calls to ArtifactDir in the same test or subtest return the same directory.
  1479  // Subtest outputs are not located under the parent test's output directory.
  1480  func (c *common) ArtifactDir() string {
  1481  	c.checkFuzzFn("ArtifactDir")
  1482  	c.artifactDirOnce.Do(func() {
  1483  		c.artifactDir, c.artifactDirErr = c.makeArtifactDir()
  1484  	})
  1485  	if c.artifactDirErr != nil {
  1486  		c.Fatalf("ArtifactDir: %v", c.artifactDirErr)
  1487  	}
  1488  	return c.artifactDir
  1489  }
  1490  
  1491  func hashString(s string) (h uint64) {
  1492  	// FNV, used here to avoid a dependency on maphash.
  1493  	for i := 0; i < len(s); i++ {
  1494  		h ^= uint64(s[i])
  1495  		h *= 1099511628211
  1496  	}
  1497  	return
  1498  }
  1499  
  1500  // makeArtifactDir creates the artifact directory for a test.
  1501  // The artifact directory is:
  1502  //
  1503  //	<output dir>/_artifacts/<test package>/<test name>/<random>
  1504  //
  1505  // The test package is the package import path with the module name prefix removed.
  1506  // The test name is truncated if too long.
  1507  // Special characters are removed from the path.
  1508  func (c *common) makeArtifactDir() (string, error) {
  1509  	if !*artifacts {
  1510  		return c.makeTempDir()
  1511  	}
  1512  
  1513  	artifactBase := filepath.Join(artifactDir, c.relativeArtifactBase())
  1514  	if err := os.MkdirAll(artifactBase, 0o777); err != nil {
  1515  		return "", err
  1516  	}
  1517  	dir, err := os.MkdirTemp(artifactBase, "")
  1518  	if err != nil {
  1519  		return "", err
  1520  	}
  1521  	if c.chatty != nil {
  1522  		c.chatty.Updatef(c.name, "=== ARTIFACTS %s %v\n", c.name, dir)
  1523  	}
  1524  	return dir, nil
  1525  }
  1526  
  1527  func (c *common) relativeArtifactBase() string {
  1528  	// If the test name is longer than maxNameSize, truncate it and replace the last
  1529  	// hashSize bytes with a hash of the full name.
  1530  	const maxNameSize = 64
  1531  	name := strings.ReplaceAll(c.name, "/", "__")
  1532  	if len(name) > maxNameSize {
  1533  		h := fmt.Sprintf("%0x", hashString(name))
  1534  		name = name[:maxNameSize-len(h)] + h
  1535  	}
  1536  
  1537  	// Remove the module path prefix from the import path.
  1538  	// If this is the root package, pkg will be empty.
  1539  	pkg := strings.TrimPrefix(c.importPath, c.modulePath)
  1540  	// Remove the leading slash.
  1541  	pkg = strings.TrimPrefix(pkg, "/")
  1542  
  1543  	base := name
  1544  	if pkg != "" {
  1545  		// Join with /, not filepath.Join: the import path is /-separated,
  1546  		// and we don't want removeSymbolsExcept to strip \ separators on Windows.
  1547  		base = pkg + "/" + name
  1548  	}
  1549  	base = removeSymbolsExcept(base, "!#$%&()+,-.=@^_{}~ /")
  1550  	base, err := filepath.Localize(base)
  1551  	if err != nil {
  1552  		// This name can't be safely converted into a local filepath.
  1553  		// Drop it and just use _artifacts/<random>.
  1554  		base = ""
  1555  	}
  1556  
  1557  	return base
  1558  }
  1559  
  1560  func removeSymbolsExcept(s, allowed string) string {
  1561  	mapper := func(r rune) rune {
  1562  		if unicode.IsLetter(r) ||
  1563  			unicode.IsNumber(r) ||
  1564  			strings.ContainsRune(allowed, r) {
  1565  			return r
  1566  		}
  1567  		return -1 // disallowed symbol
  1568  	}
  1569  	return strings.Map(mapper, s)
  1570  }
  1571  
  1572  // TempDir returns a temporary directory for the test to use.
  1573  // The directory is automatically removed when the test and
  1574  // all its subtests complete.
  1575  // Each subsequent call to TempDir returns a unique directory;
  1576  // if the directory creation fails, TempDir terminates the test by calling Fatal.
  1577  // If the environment variable GOTMPDIR is set, the temporary directory will
  1578  // be created somewhere beneath it.
  1579  func (c *common) TempDir() string {
  1580  	c.checkFuzzFn("TempDir")
  1581  	dir, err := c.makeTempDir()
  1582  	if err != nil {
  1583  		c.Fatalf("TempDir: %v", err)
  1584  	}
  1585  	return dir
  1586  }
  1587  
  1588  func (c *common) makeTempDir() (string, error) {
  1589  	// Use a single parent directory for all the temporary directories
  1590  	// created by a test, each numbered sequentially.
  1591  	c.tempDirMu.Lock()
  1592  	var nonExistent bool
  1593  	if c.tempDir == "" { // Usually the case with js/wasm
  1594  		nonExistent = true
  1595  	} else {
  1596  		_, err := os.Stat(c.tempDir)
  1597  		nonExistent = os.IsNotExist(err)
  1598  		if err != nil && !nonExistent {
  1599  			return "", err
  1600  		}
  1601  	}
  1602  
  1603  	if nonExistent {
  1604  		c.Helper()
  1605  
  1606  		pattern := c.Name()
  1607  		// Limit length of file names on disk.
  1608  		// Invalid runes from slicing are dropped by strings.Map below.
  1609  		pattern = pattern[:min(len(pattern), 64)]
  1610  
  1611  		// Drop unusual characters (such as path separators or
  1612  		// characters interacting with globs) from the directory name to
  1613  		// avoid surprising os.MkdirTemp behavior.
  1614  		const allowed = "!#$%&()+,-.=@^_{}~ "
  1615  		pattern = removeSymbolsExcept(pattern, allowed)
  1616  
  1617  		c.tempDir, c.tempDirErr = os.MkdirTemp(os.Getenv("GOTMPDIR"), pattern)
  1618  		if c.tempDirErr == nil {
  1619  			c.Cleanup(func() {
  1620  				if err := removeAll(c.tempDir); err != nil {
  1621  					c.Errorf("TempDir RemoveAll cleanup: %v", err)
  1622  				}
  1623  			})
  1624  		}
  1625  	}
  1626  
  1627  	if c.tempDirErr == nil {
  1628  		c.tempDirSeq++
  1629  	}
  1630  	seq := c.tempDirSeq
  1631  	c.tempDirMu.Unlock()
  1632  
  1633  	if c.tempDirErr != nil {
  1634  		return "", c.tempDirErr
  1635  	}
  1636  
  1637  	dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)
  1638  	if err := os.Mkdir(dir, 0o777); err != nil {
  1639  		return "", err
  1640  	}
  1641  	return dir, nil
  1642  }
  1643  
  1644  // removeAll is like os.RemoveAll, but retries Windows "Access is denied."
  1645  // errors up to an arbitrary timeout.
  1646  //
  1647  // Those errors have been known to occur spuriously on at least the
  1648  // windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur
  1649  // legitimately if the test leaves behind a temp file that either is still open
  1650  // or the test otherwise lacks permission to delete. In the case of legitimate
  1651  // failures, a failing test may take a bit longer to fail, but once the test is
  1652  // fixed the extra latency will go away.
  1653  func removeAll(path string) error {
  1654  	const arbitraryTimeout = 2 * time.Second
  1655  	var (
  1656  		start     time.Time
  1657  		nextSleep = 1 * time.Millisecond
  1658  	)
  1659  	for {
  1660  		err := os.RemoveAll(path)
  1661  		if !isWindowsRetryable(err) {
  1662  			return err
  1663  		}
  1664  		if start.IsZero() {
  1665  			start = time.Now()
  1666  		} else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {
  1667  			return err
  1668  		}
  1669  		time.Sleep(nextSleep)
  1670  		nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))
  1671  	}
  1672  }
  1673  
  1674  // Setenv calls [os.Setenv] and uses Cleanup to
  1675  // restore the environment variable to its original value
  1676  // after the test.
  1677  //
  1678  // Because Setenv affects the whole process, it cannot be used
  1679  // in parallel tests or tests with parallel ancestors.
  1680  func (c *common) Setenv(key, value string) {
  1681  	c.checkFuzzFn("Setenv")
  1682  	prevValue, ok := os.LookupEnv(key)
  1683  
  1684  	if err := os.Setenv(key, value); err != nil {
  1685  		c.Fatalf("cannot set environment variable: %v", err)
  1686  	}
  1687  
  1688  	if ok {
  1689  		c.Cleanup(func() {
  1690  			os.Setenv(key, prevValue)
  1691  		})
  1692  	} else {
  1693  		c.Cleanup(func() {
  1694  			os.Unsetenv(key)
  1695  		})
  1696  	}
  1697  }
  1698  
  1699  // Chdir calls [os.Chdir] and uses Cleanup to restore the current
  1700  // working directory to its original value after the test. On Unix, it
  1701  // also sets PWD environment variable for the duration of the test.
  1702  //
  1703  // Because Chdir affects the whole process, it cannot be used
  1704  // in parallel tests or tests with parallel ancestors.
  1705  func (c *common) Chdir(dir string) {
  1706  	c.checkFuzzFn("Chdir")
  1707  	oldwd, err := os.Open(".")
  1708  	if err != nil {
  1709  		c.Fatal(err)
  1710  	}
  1711  	if err := os.Chdir(dir); err != nil {
  1712  		c.Fatal(err)
  1713  	}
  1714  	// On POSIX platforms, PWD represents “an absolute pathname of the
  1715  	// current working directory.” Since we are changing the working
  1716  	// directory, we should also set or update PWD to reflect that.
  1717  	switch runtime.GOOS {
  1718  	case "windows", "plan9":
  1719  		// Windows and Plan 9 do not use the PWD variable.
  1720  	default:
  1721  		if !filepath.IsAbs(dir) {
  1722  			dir, err = os.Getwd()
  1723  			if err != nil {
  1724  				c.Fatal(err)
  1725  			}
  1726  		}
  1727  		c.Setenv("PWD", dir)
  1728  	}
  1729  	c.Cleanup(func() {
  1730  		err := oldwd.Chdir()
  1731  		oldwd.Close()
  1732  		if err != nil {
  1733  			// It's not safe to continue with tests if we can't
  1734  			// get back to the original working directory. Since
  1735  			// we are holding a dirfd, this is highly unlikely.
  1736  			panic("testing.Chdir: " + err.Error())
  1737  		}
  1738  	})
  1739  }
  1740  
  1741  // Context returns a context that is canceled just before
  1742  // Cleanup-registered functions are called.
  1743  //
  1744  // Cleanup functions can wait for any resources
  1745  // that shut down on [context.Context.Done] before the test or benchmark completes.
  1746  func (c *common) Context() context.Context {
  1747  	c.checkFuzzFn("Context")
  1748  	return c.ctx
  1749  }
  1750  
  1751  // Attr emits a test attribute associated with this test.
  1752  //
  1753  // The key must not contain whitespace.
  1754  // The value must not contain newlines or carriage returns.
  1755  //
  1756  // The meaning of different attribute keys is left up to
  1757  // continuous integration systems and test frameworks.
  1758  //
  1759  // Test attributes are emitted immediately in the test log,
  1760  // but they are intended to be treated as unordered.
  1761  func (c *common) Attr(key, value string) {
  1762  	if strings.ContainsFunc(key, unicode.IsSpace) {
  1763  		c.Errorf("disallowed whitespace in attribute key %q", key)
  1764  		return
  1765  	}
  1766  	if strings.ContainsAny(value, "\r\n") {
  1767  		c.Errorf("disallowed newline in attribute value %q", value)
  1768  		return
  1769  	}
  1770  	if c.chatty == nil {
  1771  		return
  1772  	}
  1773  	c.chatty.Updatef(c.name, "=== ATTR  %s %v %v\n", c.name, key, value)
  1774  }
  1775  
  1776  // panicHandling controls the panic handling used by runCleanup.
  1777  type panicHandling int
  1778  
  1779  const (
  1780  	normalPanic panicHandling = iota
  1781  	recoverAndReturnPanic
  1782  )
  1783  
  1784  // runCleanup is called at the end of the test.
  1785  // If ph is recoverAndReturnPanic, it will catch panics, and return the
  1786  // recovered value if any.
  1787  func (c *common) runCleanup(ph panicHandling) (panicVal any) {
  1788  	c.cleanupStarted.Store(true)
  1789  	defer c.cleanupStarted.Store(false)
  1790  
  1791  	if ph == recoverAndReturnPanic {
  1792  		defer func() {
  1793  			panicVal = recover()
  1794  		}()
  1795  	}
  1796  
  1797  	// Make sure that if a cleanup function panics,
  1798  	// we still run the remaining cleanup functions.
  1799  	defer func() {
  1800  		c.mu.Lock()
  1801  		recur := len(c.cleanups) > 0
  1802  		c.mu.Unlock()
  1803  		if recur {
  1804  			c.runCleanup(normalPanic)
  1805  		}
  1806  	}()
  1807  
  1808  	if c.cancelCtx != nil {
  1809  		c.cancelCtx()
  1810  	}
  1811  
  1812  	for {
  1813  		var cleanup func()
  1814  		c.mu.Lock()
  1815  		if len(c.cleanups) > 0 {
  1816  			last := len(c.cleanups) - 1
  1817  			cleanup = c.cleanups[last]
  1818  			c.cleanups = c.cleanups[:last]
  1819  		}
  1820  		c.mu.Unlock()
  1821  		if cleanup == nil {
  1822  			return nil
  1823  		}
  1824  		cleanup()
  1825  	}
  1826  }
  1827  
  1828  // resetRaces updates c.parent's count of data race errors (or the global count,
  1829  // if c has no parent), and updates c.lastRaceErrors to match.
  1830  //
  1831  // Any races that occurred prior to this call to resetRaces will
  1832  // not be attributed to c.
  1833  func (c *common) resetRaces() {
  1834  	if c.parent == nil {
  1835  		c.lastRaceErrors.Store(int64(race.Errors()))
  1836  	} else {
  1837  		c.lastRaceErrors.Store(c.parent.checkRaces())
  1838  	}
  1839  }
  1840  
  1841  // checkRaces checks whether the global count of data race errors has increased
  1842  // since c's count was last reset.
  1843  //
  1844  // If so, it marks c as having failed due to those races (logging an error for
  1845  // the first such race), and updates the race counts for the parents of c so
  1846  // that if they are currently suspended (such as in a call to T.Run) they will
  1847  // not log separate errors for the race(s).
  1848  //
  1849  // Note that multiple tests may be marked as failed due to the same race if they
  1850  // are executing in parallel.
  1851  func (c *common) checkRaces() (raceErrors int64) {
  1852  	raceErrors = int64(race.Errors())
  1853  	for {
  1854  		last := c.lastRaceErrors.Load()
  1855  		if raceErrors <= last {
  1856  			// All races have already been reported.
  1857  			return raceErrors
  1858  		}
  1859  		if c.lastRaceErrors.CompareAndSwap(last, raceErrors) {
  1860  			break
  1861  		}
  1862  	}
  1863  
  1864  	if c.raceErrorLogged.CompareAndSwap(false, true) {
  1865  		// This is the first race we've encountered for this test.
  1866  		// Mark the test as failed, and log the reason why only once.
  1867  		// (Note that the race detector itself will still write a goroutine
  1868  		// dump for any further races it detects.)
  1869  		c.Errorf("race detected during execution of test")
  1870  	}
  1871  
  1872  	// Update the parent(s) of this test so that they don't re-report the race.
  1873  	parent := c.parent
  1874  	for parent != nil {
  1875  		for {
  1876  			last := parent.lastRaceErrors.Load()
  1877  			if raceErrors <= last {
  1878  				// This race was already reported by another (likely parallel) subtest.
  1879  				return raceErrors
  1880  			}
  1881  			if parent.lastRaceErrors.CompareAndSwap(last, raceErrors) {
  1882  				break
  1883  			}
  1884  		}
  1885  		parent = parent.parent
  1886  	}
  1887  
  1888  	return raceErrors
  1889  }
  1890  
  1891  // callerName gives the function name (qualified with a package path)
  1892  // for the caller after skip frames (where 0 means the current function).
  1893  func callerName(skip int) string {
  1894  	var pc [1]uintptr
  1895  	n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName
  1896  	if n == 0 {
  1897  		panic("testing: zero callers found")
  1898  	}
  1899  	return pcToName(pc[0])
  1900  }
  1901  
  1902  func pcToName(pc uintptr) string {
  1903  	pcs := []uintptr{pc}
  1904  	frames := runtime.CallersFrames(pcs)
  1905  	frame, _ := frames.Next()
  1906  	return frame.Function
  1907  }
  1908  
  1909  // parallelConflict returns the panic message for a conflict between t.Parallel
  1910  // and op, the operation that cannot be combined with a parallel test: one of
  1911  // "t.Setenv", "t.Chdir", or "cryptotest.SetGlobalRandom".
  1912  func parallelConflict(op string) string {
  1913  	return "testing: test using " + op + " can not use t.Parallel"
  1914  }
  1915  
  1916  // Parallel signals that this test is to be run in parallel with (and only with)
  1917  // other parallel tests, and pauses until all non-parallel tests have finished.
  1918  //
  1919  // When a test is run multiple times due to use of -test.count or -test.cpu,
  1920  // multiple instances of a single test never run in parallel with each other.
  1921  func (t *T) Parallel() {
  1922  	if t.isParallel {
  1923  		panic("testing: t.Parallel called multiple times")
  1924  	}
  1925  	if t.isSynctest {
  1926  		panic("testing: t.Parallel called inside synctest bubble")
  1927  	}
  1928  	if t.denyParallel != "" {
  1929  		panic(parallelConflict(t.denyParallel))
  1930  	}
  1931  	if t.parent.barrier == nil {
  1932  		// T.Parallel has no effect when fuzzing.
  1933  		// Multiple processes may run in parallel, but only one input can run at a
  1934  		// time per process so we can attribute crashes to specific inputs.
  1935  		return
  1936  	}
  1937  
  1938  	t.isParallel = true
  1939  
  1940  	// We don't want to include the time we spend waiting for serial tests
  1941  	// in the test duration. Record the elapsed time thus far and reset the
  1942  	// timer afterwards.
  1943  	t.duration += highPrecisionTimeSince(t.start)
  1944  
  1945  	// Add to the list of tests to be released by the parent.
  1946  	t.parent.sub = append(t.parent.sub, t)
  1947  
  1948  	// Report any races during execution of this test up to this point.
  1949  	//
  1950  	// We will assume that any races that occur between here and the point where
  1951  	// we unblock are not caused by this subtest. That assumption usually holds,
  1952  	// although it can be wrong if the test spawns a goroutine that races in the
  1953  	// background while the rest of the test is blocked on the call to Parallel.
  1954  	// If that happens, we will misattribute the background race to some other
  1955  	// test, or to no test at all — but that false-negative is so unlikely that it
  1956  	// is not worth adding race-report noise for the common case where the test is
  1957  	// completely suspended during the call to Parallel.
  1958  	t.checkRaces()
  1959  
  1960  	if t.chatty != nil {
  1961  		t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)
  1962  	}
  1963  	running.Delete(t.name)
  1964  
  1965  	t.signal <- true   // Release calling test.
  1966  	<-t.parent.barrier // Wait for the parent test to complete.
  1967  	t.tstate.waitParallel()
  1968  	parallelStart.Add(1)
  1969  
  1970  	if t.chatty != nil {
  1971  		t.chatty.Updatef(t.name, "=== CONT  %s\n", t.name)
  1972  	}
  1973  	running.Store(t.name, highPrecisionTimeNow())
  1974  	t.start = highPrecisionTimeNow()
  1975  
  1976  	// Reset the local race counter to ignore any races that happened while this
  1977  	// goroutine was blocked, such as in the parent test or in other parallel
  1978  	// subtests.
  1979  	//
  1980  	// (Note that we don't call parent.checkRaces here:
  1981  	// if other parallel subtests have already introduced races, we want to
  1982  	// let them report those races instead of attributing them to the parent.)
  1983  	t.lastRaceErrors.Store(int64(race.Errors()))
  1984  }
  1985  
  1986  // checkParallel is called by [testing/cryptotest.SetGlobalRandom].
  1987  //
  1988  //go:linkname checkParallel testing.checkParallel
  1989  func checkParallel(t *T) {
  1990  	t.checkParallel("cryptotest.SetGlobalRandom")
  1991  }
  1992  
  1993  func (t *T) checkParallel(op string) {
  1994  	// Non-parallel subtests that have parallel ancestors may still
  1995  	// run in parallel with other tests: they are only non-parallel
  1996  	// with respect to the other subtests of the same parent.
  1997  	// Since calls like SetEnv or Chdir affects the whole process, we need
  1998  	// to deny those if the current test or any parent is parallel.
  1999  	for c := &t.common; c != nil; c = c.parent {
  2000  		if c.isParallel {
  2001  			panic(parallelConflict(op))
  2002  		}
  2003  	}
  2004  
  2005  	t.denyParallel = op
  2006  }
  2007  
  2008  // Setenv calls os.Setenv(key, value) and uses Cleanup to
  2009  // restore the environment variable to its original value
  2010  // after the test.
  2011  //
  2012  // Because Setenv affects the whole process, it cannot be used
  2013  // in parallel tests or tests with parallel ancestors.
  2014  func (t *T) Setenv(key, value string) {
  2015  	t.checkParallel("t.Setenv")
  2016  	t.common.Setenv(key, value)
  2017  }
  2018  
  2019  // Chdir calls [os.Chdir] and uses Cleanup to restore the current
  2020  // working directory to its original value after the test. On Unix, it
  2021  // also sets PWD environment variable for the duration of the test.
  2022  //
  2023  // Because Chdir affects the whole process, it cannot be used
  2024  // in parallel tests or tests with parallel ancestors.
  2025  func (t *T) Chdir(dir string) {
  2026  	t.checkParallel("t.Chdir")
  2027  	t.common.Chdir(dir)
  2028  }
  2029  
  2030  // InternalTest is an internal type but exported because it is cross-package;
  2031  // it is part of the implementation of the "go test" command.
  2032  type InternalTest struct {
  2033  	Name string
  2034  	F    func(*T)
  2035  }
  2036  
  2037  var errNilPanicOrGoexit = errors.New("test executed panic(nil) or runtime.Goexit")
  2038  
  2039  func tRunner(t *T, fn func(t *T)) {
  2040  	t.runner = callerName(0)
  2041  
  2042  	// When this goroutine is done, either because fn(t)
  2043  	// returned normally or because a test failure triggered
  2044  	// a call to runtime.Goexit, record the duration and send
  2045  	// a signal saying that the test is done.
  2046  	defer func() {
  2047  		t.checkRaces()
  2048  
  2049  		// Check if the test panicked or Goexited inappropriately.
  2050  		//
  2051  		// If this happens in a normal test, print output but continue panicking.
  2052  		// tRunner is called in its own goroutine, so this terminates the process.
  2053  		//
  2054  		// If this happens while fuzzing, recover from the panic and treat it like a
  2055  		// normal failure. It's important that the process keeps running in order to
  2056  		// find short inputs that cause panics.
  2057  		err := recover()
  2058  		signal := true
  2059  
  2060  		t.mu.RLock()
  2061  		finished := t.finished
  2062  		t.mu.RUnlock()
  2063  		if !finished && err == nil {
  2064  			err = errNilPanicOrGoexit
  2065  			for p := t.parent; p != nil; p = p.parent {
  2066  				p.mu.RLock()
  2067  				finished = p.finished
  2068  				p.mu.RUnlock()
  2069  				if finished {
  2070  					if !t.isParallel {
  2071  						t.Errorf("%v: subtest may have called FailNow on a parent test", err)
  2072  						err = nil
  2073  					}
  2074  					signal = false
  2075  					break
  2076  				}
  2077  			}
  2078  		}
  2079  
  2080  		if err != nil && t.tstate.isFuzzing {
  2081  			prefix := "panic: "
  2082  			if err == errNilPanicOrGoexit {
  2083  				prefix = ""
  2084  			}
  2085  			t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack()))
  2086  			t.mu.Lock()
  2087  			t.finished = true
  2088  			t.mu.Unlock()
  2089  			err = nil
  2090  		}
  2091  
  2092  		// Use a deferred call to ensure that we report that the test is
  2093  		// complete even if a cleanup function calls t.FailNow. See issue 41355.
  2094  		didPanic := false
  2095  		defer func() {
  2096  			// Only report that the test is complete if it doesn't panic,
  2097  			// as otherwise the test binary can exit before the panic is
  2098  			// reported to the user. See issue 41479.
  2099  			if didPanic {
  2100  				return
  2101  			}
  2102  			if err != nil {
  2103  				panic(err)
  2104  			}
  2105  			running.Delete(t.name)
  2106  			if t.isParallel {
  2107  				parallelStop.Add(1)
  2108  			}
  2109  			t.signal <- signal
  2110  		}()
  2111  
  2112  		doPanic := func(err any) {
  2113  			t.Fail()
  2114  			if r := t.runCleanup(recoverAndReturnPanic); r != nil {
  2115  				t.Logf("cleanup panicked with %v", r)
  2116  			}
  2117  			// Flush the output log up to the root before dying.
  2118  			// Skip this if this *T is a synctest bubble, because we're not a subtest.
  2119  			for root := &t.common; !root.isSynctest && root.parent != nil; root = root.parent {
  2120  				root.mu.Lock()
  2121  				root.duration += highPrecisionTimeSince(root.start)
  2122  				d := root.duration
  2123  				root.mu.Unlock()
  2124  				// Output buffered logs.
  2125  				root.flushPartial()
  2126  				root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d))
  2127  				if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil {
  2128  					fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r)
  2129  				}
  2130  			}
  2131  			didPanic = true
  2132  			panic(err)
  2133  		}
  2134  		if err != nil {
  2135  			doPanic(err)
  2136  		}
  2137  
  2138  		t.duration += highPrecisionTimeSince(t.start)
  2139  
  2140  		if len(t.sub) > 0 {
  2141  			// Run parallel subtests.
  2142  
  2143  			// Decrease the running count for this test and mark it as no longer running.
  2144  			t.tstate.release()
  2145  			running.Delete(t.name)
  2146  
  2147  			// Release the parallel subtests.
  2148  			close(t.barrier)
  2149  			// Wait for subtests to complete.
  2150  			for _, sub := range t.sub {
  2151  				<-sub.signal
  2152  			}
  2153  
  2154  			// Run any cleanup callbacks, marking the test as running
  2155  			// in case the cleanup hangs.
  2156  			cleanupStart := highPrecisionTimeNow()
  2157  			running.Store(t.name, cleanupStart)
  2158  			err := t.runCleanup(recoverAndReturnPanic)
  2159  			t.duration += highPrecisionTimeSince(cleanupStart)
  2160  			if err != nil {
  2161  				doPanic(err)
  2162  			}
  2163  			t.checkRaces()
  2164  			if !t.isParallel {
  2165  				// Reacquire the count for sequential tests. See comment in Run.
  2166  				t.tstate.waitParallel()
  2167  			}
  2168  		} else if t.isParallel {
  2169  			// Only release the count for this test if it was run as a parallel
  2170  			// test. See comment in Run method.
  2171  			t.tstate.release()
  2172  		}
  2173  		// Output buffered logs.
  2174  		for root := &t.common; root.parent != nil; root = root.parent {
  2175  			root.flushPartial()
  2176  		}
  2177  
  2178  		// Record this test's failure for -failfast. This must happen after the
  2179  		// test's cleanup functions have run, since a cleanup may call t.Fail.
  2180  		// See go.dev/issue/61034.
  2181  		if t.Failed() {
  2182  			numFailed.Add(1)
  2183  		}
  2184  
  2185  		t.report() // Report after all subtests have finished.
  2186  
  2187  		// Do not lock t.done to allow race detector to detect race in case
  2188  		// the user does not appropriately synchronize a goroutine.
  2189  		t.done = true
  2190  		if t.parent != nil && !t.hasSub.Load() {
  2191  			t.setRan()
  2192  		}
  2193  	}()
  2194  	defer func() {
  2195  		if len(t.sub) == 0 {
  2196  			t.runCleanup(normalPanic)
  2197  		}
  2198  	}()
  2199  
  2200  	t.start = highPrecisionTimeNow()
  2201  	t.resetRaces()
  2202  	fn(t)
  2203  
  2204  	// code beyond here will not be executed when FailNow is invoked
  2205  	t.mu.Lock()
  2206  	t.finished = true
  2207  	t.mu.Unlock()
  2208  }
  2209  
  2210  // Run runs f as a subtest of t called name. It runs f in a separate goroutine
  2211  // and blocks until f returns or calls t.Parallel to become a parallel test.
  2212  // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
  2213  //
  2214  // Run may be called simultaneously from multiple goroutines, but all such calls
  2215  // must return before the outer test function for t returns.
  2216  func (t *T) Run(name string, f func(t *T)) bool {
  2217  	if t.isSynctest {
  2218  		panic("testing: t.Run called inside synctest bubble")
  2219  	}
  2220  	if t.cleanupStarted.Load() {
  2221  		panic("testing: t.Run called during t.Cleanup")
  2222  	}
  2223  
  2224  	t.hasSub.Store(true)
  2225  	testName, ok, _ := t.tstate.match.fullName(&t.common, name)
  2226  	if !ok || shouldFailFast() {
  2227  		return true
  2228  	}
  2229  	// Record the stack trace at the point of this call so that if the subtest
  2230  	// function - which runs in a separate stack - is marked as a helper, we can
  2231  	// continue walking the stack into the parent test.
  2232  	var pc [maxStackLen]uintptr
  2233  	n := runtime.Callers(2, pc[:])
  2234  
  2235  	// There's no reason to inherit this context from parent. The user's code can't observe
  2236  	// the difference between the background context and the one from the parent test.
  2237  	ctx, cancelCtx := context.WithCancel(context.Background())
  2238  	t = &T{
  2239  		common: common{
  2240  			barrier:    make(chan bool),
  2241  			signal:     make(chan bool, 1),
  2242  			name:       testName,
  2243  			modulePath: t.modulePath,
  2244  			importPath: t.importPath,
  2245  			parent:     &t.common,
  2246  			level:      t.level + 1,
  2247  			creator:    pc[:n],
  2248  			chatty:     t.chatty,
  2249  			ctx:        ctx,
  2250  			cancelCtx:  cancelCtx,
  2251  		},
  2252  		tstate: t.tstate,
  2253  	}
  2254  	t.w = indenter{&t.common}
  2255  	t.setOutputWriter()
  2256  
  2257  	if t.chatty != nil {
  2258  		t.chatty.Updatef(t.name, "=== RUN   %s\n", t.name)
  2259  	}
  2260  	running.Store(t.name, highPrecisionTimeNow())
  2261  
  2262  	// Instead of reducing the running count of this test before calling the
  2263  	// tRunner and increasing it afterwards, we rely on tRunner keeping the
  2264  	// count correct. This ensures that a sequence of sequential tests runs
  2265  	// without being preempted, even when their parent is a parallel test. This
  2266  	// may especially reduce surprises if *parallel == 1.
  2267  	go tRunner(t, f)
  2268  
  2269  	// The parent goroutine will block until the subtest either finishes or calls
  2270  	// Parallel, but in general we don't know whether the parent goroutine is the
  2271  	// top-level test function or some other goroutine it has spawned.
  2272  	// To avoid confusing false-negatives, we leave the parent in the running map
  2273  	// even though in the typical case it is blocked.
  2274  
  2275  	if !<-t.signal {
  2276  		// At this point, it is likely that FailNow was called on one of the
  2277  		// parent tests by one of the subtests. Continue aborting up the chain.
  2278  		runtime.Goexit()
  2279  	}
  2280  
  2281  	if t.chatty != nil && t.chatty.json {
  2282  		t.chatty.Updatef(t.parent.name, "=== NAME  %s\n", t.parent.name)
  2283  	}
  2284  	return !t.failed
  2285  }
  2286  
  2287  // testingSynctestTest runs f within a synctest bubble.
  2288  // It is called by synctest.Test, from within an already-created bubble.
  2289  //
  2290  //go:linkname testingSynctestTest testing/synctest.testingSynctestTest
  2291  func testingSynctestTest(t *T, f func(*T)) (ok bool) {
  2292  	if t.cleanupStarted.Load() {
  2293  		panic("testing: synctest.Run called during t.Cleanup")
  2294  	}
  2295  
  2296  	var pc [maxStackLen]uintptr
  2297  	n := runtime.Callers(2, pc[:])
  2298  
  2299  	ctx, cancelCtx := context.WithCancel(context.Background())
  2300  	t2 := &T{
  2301  		common: common{
  2302  			barrier:    make(chan bool),
  2303  			signal:     make(chan bool, 1),
  2304  			name:       t.name,
  2305  			parent:     &t.common,
  2306  			level:      t.level + 1,
  2307  			creator:    pc[:n],
  2308  			chatty:     t.chatty,
  2309  			ctx:        ctx,
  2310  			cancelCtx:  cancelCtx,
  2311  			isSynctest: true,
  2312  		},
  2313  		tstate: t.tstate,
  2314  	}
  2315  
  2316  	go tRunner(t2, f)
  2317  	if !<-t2.signal {
  2318  		// At this point, it is likely that FailNow was called on one of the
  2319  		// parent tests by one of the subtests. Continue aborting up the chain.
  2320  		runtime.Goexit()
  2321  	}
  2322  	return !t2.failed
  2323  }
  2324  
  2325  // Deadline reports the time at which the test binary will have
  2326  // exceeded the timeout specified by the -timeout flag.
  2327  //
  2328  // The ok result is false if the -timeout flag indicates “no timeout” (0).
  2329  func (t *T) Deadline() (deadline time.Time, ok bool) {
  2330  	if t.isSynctest {
  2331  		// There's no point in returning a real-clock deadline to
  2332  		// a test using a fake clock. We could return "no timeout",
  2333  		// but panicking makes it easier for users to catch the error.
  2334  		panic("testing: t.Deadline called inside synctest bubble")
  2335  	}
  2336  	deadline = t.tstate.deadline
  2337  	return deadline, !deadline.IsZero()
  2338  }
  2339  
  2340  // testState holds all fields that are common to all tests. This includes
  2341  // synchronization primitives to run at most *parallel tests.
  2342  type testState struct {
  2343  	match    *matcher
  2344  	deadline time.Time
  2345  
  2346  	// isFuzzing is true in the state used when generating random inputs
  2347  	// for fuzz targets. isFuzzing is false when running normal tests and
  2348  	// when running fuzz tests as unit tests (without -fuzz or when -fuzz
  2349  	// does not match).
  2350  	isFuzzing bool
  2351  
  2352  	mu sync.Mutex
  2353  
  2354  	// Channel used to signal tests that are ready to be run in parallel.
  2355  	startParallel chan bool
  2356  
  2357  	// running is the number of tests currently running in parallel.
  2358  	// This does not include tests that are waiting for subtests to complete.
  2359  	running int
  2360  
  2361  	// numWaiting is the number tests waiting to be run in parallel.
  2362  	numWaiting int
  2363  
  2364  	// maxParallel is a copy of the parallel flag.
  2365  	maxParallel int
  2366  }
  2367  
  2368  func newTestState(maxParallel int, m *matcher) *testState {
  2369  	return &testState{
  2370  		match:         m,
  2371  		startParallel: make(chan bool),
  2372  		maxParallel:   maxParallel,
  2373  		running:       1, // Set the count to 1 for the main (sequential) test.
  2374  	}
  2375  }
  2376  
  2377  func (s *testState) waitParallel() {
  2378  	s.mu.Lock()
  2379  	if s.running < s.maxParallel {
  2380  		s.running++
  2381  		s.mu.Unlock()
  2382  		return
  2383  	}
  2384  	s.numWaiting++
  2385  	s.mu.Unlock()
  2386  	<-s.startParallel
  2387  }
  2388  
  2389  func (s *testState) release() {
  2390  	s.mu.Lock()
  2391  	if s.numWaiting == 0 {
  2392  		s.running--
  2393  		s.mu.Unlock()
  2394  		return
  2395  	}
  2396  	s.numWaiting--
  2397  	s.mu.Unlock()
  2398  	s.startParallel <- true // Pick a waiting test to be run.
  2399  }
  2400  
  2401  // No one should be using func Main anymore.
  2402  // See the doc comment on func Main and use MainStart instead.
  2403  var errMain = errors.New("testing: unexpected use of func Main")
  2404  
  2405  type matchStringOnly func(pat, str string) (bool, error)
  2406  
  2407  func (f matchStringOnly) MatchString(pat, str string) (bool, error)   { return f(pat, str) }
  2408  func (f matchStringOnly) StartCPUProfile(w io.Writer) error           { return errMain }
  2409  func (f matchStringOnly) StopCPUProfile()                             {}
  2410  func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain }
  2411  func (f matchStringOnly) ModulePath() string                          { return "" }
  2412  func (f matchStringOnly) ImportPath() string                          { return "" }
  2413  func (f matchStringOnly) StartTestLog(io.Writer)                      {}
  2414  func (f matchStringOnly) StopTestLog() error                          { return errMain }
  2415  func (f matchStringOnly) SetPanicOnExit0(bool)                        {}
  2416  func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error {
  2417  	return errMain
  2418  }
  2419  func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain }
  2420  func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) {
  2421  	return nil, errMain
  2422  }
  2423  func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil }
  2424  func (f matchStringOnly) ResetCoverage()                          {}
  2425  func (f matchStringOnly) SnapshotCoverage()                       {}
  2426  
  2427  func (f matchStringOnly) InitRuntimeCoverage() (mode string, tearDown func(string, string) (string, error), snapcov func() float64) {
  2428  	return
  2429  }
  2430  
  2431  // Main is an internal function, part of the implementation of the "go test" command.
  2432  // It was exported because it is cross-package and predates "internal" packages.
  2433  // It is no longer used by "go test" but preserved, as much as possible, for other
  2434  // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
  2435  // new functionality is added to the testing package.
  2436  // Systems simulating "go test" should be updated to use [MainStart].
  2437  func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {
  2438  	os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run())
  2439  }
  2440  
  2441  // M is a type passed to a TestMain function to run the actual tests.
  2442  type M struct {
  2443  	deps        testDeps
  2444  	tests       []InternalTest
  2445  	benchmarks  []InternalBenchmark
  2446  	fuzzTargets []InternalFuzzTarget
  2447  	examples    []InternalExample
  2448  
  2449  	timer     *time.Timer
  2450  	afterOnce sync.Once
  2451  
  2452  	numRun int
  2453  
  2454  	// value to pass to os.Exit, the outer test func main
  2455  	// harness calls os.Exit with this code. See #34129.
  2456  	exitCode int
  2457  }
  2458  
  2459  // testDeps is an internal interface of functionality that is
  2460  // passed into this package by a test's generated main package.
  2461  // The canonical implementation of this interface is
  2462  // testing/internal/testdeps's TestDeps.
  2463  type testDeps interface {
  2464  	ImportPath() string
  2465  	ModulePath() string
  2466  	MatchString(pat, str string) (bool, error)
  2467  	SetPanicOnExit0(bool)
  2468  	StartCPUProfile(io.Writer) error
  2469  	StopCPUProfile()
  2470  	StartTestLog(io.Writer)
  2471  	StopTestLog() error
  2472  	WriteProfileTo(string, io.Writer, int) error
  2473  	CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error
  2474  	RunFuzzWorker(func(corpusEntry) error) error
  2475  	ReadCorpus(string, []reflect.Type) ([]corpusEntry, error)
  2476  	CheckCorpus([]any, []reflect.Type) error
  2477  	ResetCoverage()
  2478  	SnapshotCoverage()
  2479  	InitRuntimeCoverage() (mode string, tearDown func(coverprofile string, gocoverdir string) (string, error), snapcov func() float64)
  2480  }
  2481  
  2482  // MainStart is meant for use by tests generated by 'go test'.
  2483  // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
  2484  // It may change signature from release to release.
  2485  func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M {
  2486  	registerCover(deps.InitRuntimeCoverage())
  2487  	Init()
  2488  	return &M{
  2489  		deps:        deps,
  2490  		tests:       tests,
  2491  		benchmarks:  benchmarks,
  2492  		fuzzTargets: fuzzTargets,
  2493  		examples:    examples,
  2494  	}
  2495  }
  2496  
  2497  var (
  2498  	testingTesting bool
  2499  	realStderr     *os.File
  2500  )
  2501  
  2502  // Run runs the tests. It returns an exit code to pass to os.Exit.
  2503  // The exit code is zero when all tests pass, and non-zero for any kind
  2504  // of failure. For machine readable test results, parse the output of
  2505  // 'go test -json'.
  2506  func (m *M) Run() (code int) {
  2507  	defer func() {
  2508  		code = m.exitCode
  2509  	}()
  2510  
  2511  	// Count the number of calls to m.Run.
  2512  	// We only ever expected 1, but we didn't enforce that,
  2513  	// and now there are tests in the wild that call m.Run multiple times.
  2514  	// Sigh. go.dev/issue/23129.
  2515  	m.numRun++
  2516  
  2517  	// TestMain may have already called flag.Parse.
  2518  	if !flag.Parsed() {
  2519  		flag.Parse()
  2520  	}
  2521  
  2522  	if chatty.json {
  2523  		// With -v=json, stdout and stderr are pointing to the same pipe,
  2524  		// which is leading into test2json. In general, operating systems
  2525  		// do a good job of ensuring that writes to the same pipe through
  2526  		// different file descriptors are delivered whole, so that writing
  2527  		// AAA to stdout and BBB to stderr simultaneously produces
  2528  		// AAABBB or BBBAAA on the pipe, not something like AABBBA.
  2529  		// However, the exception to this is when the pipe fills: in that
  2530  		// case, Go's use of non-blocking I/O means that writing AAA
  2531  		// or BBB might be split across multiple system calls, making it
  2532  		// entirely possible to get output like AABBBA. The same problem
  2533  		// happens inside the operating system kernel if we switch to
  2534  		// blocking I/O on the pipe. This interleaved output can do things
  2535  		// like print unrelated messages in the middle of a TestFoo line,
  2536  		// which confuses test2json. Setting os.Stderr = os.Stdout will make
  2537  		// them share a single pfd, which will hold a lock for each program
  2538  		// write, preventing any interleaving.
  2539  		//
  2540  		// It might be nice to set Stderr = Stdout always, or perhaps if
  2541  		// we can tell they are the same file, but for now -v=json is
  2542  		// a very clear signal. Making the two files the same may cause
  2543  		// surprises if programs close os.Stdout but expect to be able
  2544  		// to continue to write to os.Stderr, but it's hard to see why a
  2545  		// test would think it could take over global state that way.
  2546  		//
  2547  		// This fix only helps programs where the output is coming directly
  2548  		// from Go code. It does not help programs in which a subprocess is
  2549  		// writing to stderr or stdout at the same time that a Go test is writing output.
  2550  		// It also does not help when the output is coming from the runtime,
  2551  		// such as when using the print/println functions, since that code writes
  2552  		// directly to fd 2 without any locking.
  2553  		// We keep realStderr around to prevent fd 2 from being closed.
  2554  		//
  2555  		// See go.dev/issue/33419.
  2556  		realStderr = os.Stderr
  2557  		os.Stderr = os.Stdout
  2558  	}
  2559  
  2560  	if *parallel < 1 {
  2561  		fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer")
  2562  		flag.Usage()
  2563  		m.exitCode = 2
  2564  		return
  2565  	}
  2566  	if *matchFuzz != "" && *fuzzCacheDir == "" {
  2567  		fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set")
  2568  		flag.Usage()
  2569  		m.exitCode = 2
  2570  		return
  2571  	}
  2572  
  2573  	if *matchList != "" {
  2574  		listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples)
  2575  		m.exitCode = 0
  2576  		return
  2577  	}
  2578  
  2579  	if *shuffle != "off" {
  2580  		var n int64
  2581  		var err error
  2582  		if *shuffle == "on" {
  2583  			n = time.Now().UnixNano()
  2584  		} else {
  2585  			n, err = strconv.ParseInt(*shuffle, 10, 64)
  2586  			if err != nil {
  2587  				fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err)
  2588  				m.exitCode = 2
  2589  				return
  2590  			}
  2591  		}
  2592  		fmt.Println("-test.shuffle", n)
  2593  		rng := rand.New(rand.NewSource(n))
  2594  		rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] })
  2595  		rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] })
  2596  	}
  2597  
  2598  	parseCpuList()
  2599  
  2600  	m.before()
  2601  	defer m.after()
  2602  
  2603  	// Run tests, examples, and benchmarks unless this is a fuzz worker process.
  2604  	// Workers start after this is done by their parent process, and they should
  2605  	// not repeat this work.
  2606  	if !*isFuzzWorker {
  2607  		deadline := m.startAlarm()
  2608  		haveExamples = len(m.examples) > 0
  2609  		testRan, testOk := runTests(m.deps.ModulePath(), m.deps.ImportPath(), m.deps.MatchString, m.tests, deadline)
  2610  		fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline)
  2611  		exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples)
  2612  		m.stopAlarm()
  2613  		if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" {
  2614  			fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  2615  			if testingTesting && *match != "^$" {
  2616  				// If this happens during testing of package testing it could be that
  2617  				// package testing's own logic for when to run a test is broken,
  2618  				// in which case every test will run nothing and succeed,
  2619  				// with no obvious way to detect this problem (since no tests are running).
  2620  				// So make 'no tests to run' a hard failure when testing package testing itself.
  2621  				fmt.Print(chatty.prefix(), "FAIL: package testing must run tests\n")
  2622  				testOk = false
  2623  			}
  2624  		}
  2625  		anyFailed := !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks)
  2626  		if !anyFailed && race.Errors() > 0 {
  2627  			fmt.Print(chatty.prefix(), "testing: race detected outside of test execution\n")
  2628  			anyFailed = true
  2629  		}
  2630  		if anyFailed {
  2631  			fmt.Print(chatty.prefix(), "FAIL\n")
  2632  			m.exitCode = 1
  2633  			return
  2634  		}
  2635  	}
  2636  
  2637  	fuzzingOk := runFuzzing(m.deps, m.fuzzTargets)
  2638  	if !fuzzingOk {
  2639  		fmt.Print(chatty.prefix(), "FAIL\n")
  2640  		if *isFuzzWorker {
  2641  			m.exitCode = fuzzWorkerExitCode
  2642  		} else {
  2643  			m.exitCode = 1
  2644  		}
  2645  		return
  2646  	}
  2647  
  2648  	m.exitCode = 0
  2649  	if !*isFuzzWorker {
  2650  		fmt.Print(chatty.prefix(), "PASS\n")
  2651  	}
  2652  	return
  2653  }
  2654  
  2655  func (t *T) report() {
  2656  	if t.parent == nil {
  2657  		return
  2658  	}
  2659  	if t.isSynctest {
  2660  		return // t.parent will handle reporting
  2661  	}
  2662  	dstr := fmtDuration(t.duration)
  2663  	format := "--- %s: %s (%s)\n"
  2664  	if t.Failed() {
  2665  		t.flushToParent(t.name, format, "FAIL", t.name, dstr)
  2666  	} else if t.chatty != nil {
  2667  		if t.Skipped() {
  2668  			t.flushToParent(t.name, format, "SKIP", t.name, dstr)
  2669  		} else {
  2670  			t.flushToParent(t.name, format, "PASS", t.name, dstr)
  2671  		}
  2672  	}
  2673  }
  2674  
  2675  func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) {
  2676  	if _, err := matchString(*matchList, "non-empty"); err != nil {
  2677  		fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err)
  2678  		os.Exit(1)
  2679  	}
  2680  
  2681  	for _, test := range tests {
  2682  		if ok, _ := matchString(*matchList, test.Name); ok {
  2683  			fmt.Println(test.Name)
  2684  		}
  2685  	}
  2686  	for _, bench := range benchmarks {
  2687  		if ok, _ := matchString(*matchList, bench.Name); ok {
  2688  			fmt.Println(bench.Name)
  2689  		}
  2690  	}
  2691  	for _, fuzzTarget := range fuzzTargets {
  2692  		if ok, _ := matchString(*matchList, fuzzTarget.Name); ok {
  2693  			fmt.Println(fuzzTarget.Name)
  2694  		}
  2695  	}
  2696  	for _, example := range examples {
  2697  		if ok, _ := matchString(*matchList, example.Name); ok {
  2698  			fmt.Println(example.Name)
  2699  		}
  2700  	}
  2701  }
  2702  
  2703  // RunTests is an internal function but exported because it is cross-package;
  2704  // it is part of the implementation of the "go test" command.
  2705  func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {
  2706  	var deadline time.Time
  2707  	if *timeout > 0 {
  2708  		deadline = time.Now().Add(*timeout)
  2709  	}
  2710  	ran, ok := runTests("", "", matchString, tests, deadline)
  2711  	if !ran && !haveExamples {
  2712  		fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  2713  	}
  2714  	return ok
  2715  }
  2716  
  2717  func runTests(modulePath, importPath string, matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
  2718  	ok = true
  2719  	for _, procs := range cpuList {
  2720  		runtime.GOMAXPROCS(procs)
  2721  		for i := uint(0); i < *count; i++ {
  2722  			if shouldFailFast() {
  2723  				break
  2724  			}
  2725  			if i > 0 && !ran {
  2726  				// There were no tests to run on the first
  2727  				// iteration. This won't change, so no reason
  2728  				// to keep trying.
  2729  				break
  2730  			}
  2731  			ctx, cancelCtx := context.WithCancel(context.Background())
  2732  			tstate := newTestState(*parallel, newMatcher(matchString, *match, "-test.run", *skip))
  2733  			tstate.deadline = deadline
  2734  			t := &T{
  2735  				common: common{
  2736  					signal:     make(chan bool, 1),
  2737  					barrier:    make(chan bool),
  2738  					w:          os.Stdout,
  2739  					ctx:        ctx,
  2740  					cancelCtx:  cancelCtx,
  2741  					modulePath: modulePath,
  2742  					importPath: importPath,
  2743  				},
  2744  				tstate: tstate,
  2745  			}
  2746  			if Verbose() {
  2747  				t.chatty = newChattyPrinter(t.w)
  2748  			}
  2749  			tRunner(t, func(t *T) {
  2750  				for _, test := range tests {
  2751  					t.Run(test.Name, test.F)
  2752  				}
  2753  			})
  2754  			select {
  2755  			case <-t.signal:
  2756  			default:
  2757  				panic("internal error: tRunner exited without sending on t.signal")
  2758  			}
  2759  			ok = ok && !t.Failed()
  2760  			ran = ran || t.ran
  2761  		}
  2762  	}
  2763  	return ran, ok
  2764  }
  2765  
  2766  // before runs before all testing.
  2767  func (m *M) before() {
  2768  	if *memProfileRate > 0 {
  2769  		runtime.MemProfileRate = *memProfileRate
  2770  	}
  2771  	if *cpuProfile != "" {
  2772  		f, err := os.Create(toOutputDir(*cpuProfile))
  2773  		if err != nil {
  2774  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2775  			return
  2776  		}
  2777  		if err := m.deps.StartCPUProfile(f); err != nil {
  2778  			fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err)
  2779  			f.Close()
  2780  			return
  2781  		}
  2782  		// Could save f so after can call f.Close; not worth the effort.
  2783  	}
  2784  	if *traceFile != "" {
  2785  		f, err := os.Create(toOutputDir(*traceFile))
  2786  		if err != nil {
  2787  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2788  			return
  2789  		}
  2790  		if err := trace.Start(f); err != nil {
  2791  			fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err)
  2792  			f.Close()
  2793  			return
  2794  		}
  2795  		// Could save f so after can call f.Close; not worth the effort.
  2796  	}
  2797  	if *blockProfile != "" && *blockProfileRate >= 0 {
  2798  		runtime.SetBlockProfileRate(*blockProfileRate)
  2799  	}
  2800  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  2801  		runtime.SetMutexProfileFraction(*mutexProfileFraction)
  2802  	}
  2803  	if *coverProfile != "" && CoverMode() == "" {
  2804  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
  2805  		os.Exit(2)
  2806  	}
  2807  	if *gocoverdir != "" && CoverMode() == "" {
  2808  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.gocoverdir because test binary was not built with coverage enabled\n")
  2809  		os.Exit(2)
  2810  	}
  2811  	if *artifacts {
  2812  		var err error
  2813  		artifactDir, err = filepath.Abs(toOutputDir("_artifacts"))
  2814  		if err != nil {
  2815  			fmt.Fprintf(os.Stderr, "testing: cannot make -test.outputdir absolute: %v\n", err)
  2816  			os.Exit(2)
  2817  		}
  2818  		if err := os.Mkdir(artifactDir, 0o777); err != nil && !errors.Is(err, os.ErrExist) {
  2819  			fmt.Fprintf(os.Stderr, "testing: %v\n", err)
  2820  			os.Exit(2)
  2821  		}
  2822  	}
  2823  	if *testlog != "" {
  2824  		// Note: Not using toOutputDir.
  2825  		// This file is for use by cmd/go, not users.
  2826  		var f *os.File
  2827  		var err error
  2828  		if m.numRun == 1 {
  2829  			f, err = os.Create(*testlog)
  2830  		} else {
  2831  			f, err = os.OpenFile(*testlog, os.O_WRONLY, 0)
  2832  			if err == nil {
  2833  				f.Seek(0, io.SeekEnd)
  2834  			}
  2835  		}
  2836  		if err != nil {
  2837  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2838  			os.Exit(2)
  2839  		}
  2840  		m.deps.StartTestLog(f)
  2841  		testlogFile = f
  2842  	}
  2843  	if *panicOnExit0 {
  2844  		m.deps.SetPanicOnExit0(true)
  2845  	}
  2846  }
  2847  
  2848  // after runs after all testing.
  2849  func (m *M) after() {
  2850  	m.afterOnce.Do(func() {
  2851  		m.writeProfiles()
  2852  	})
  2853  
  2854  	// Restore PanicOnExit0 after every run, because we set it to true before
  2855  	// every run. Otherwise, if m.Run is called multiple times the behavior of
  2856  	// os.Exit(0) will not be restored after the second run.
  2857  	if *panicOnExit0 {
  2858  		m.deps.SetPanicOnExit0(false)
  2859  	}
  2860  }
  2861  
  2862  func (m *M) writeProfiles() {
  2863  	if *testlog != "" {
  2864  		if err := m.deps.StopTestLog(); err != nil {
  2865  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  2866  			os.Exit(2)
  2867  		}
  2868  		if err := testlogFile.Close(); err != nil {
  2869  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  2870  			os.Exit(2)
  2871  		}
  2872  	}
  2873  	if *cpuProfile != "" {
  2874  		m.deps.StopCPUProfile() // flushes profile to disk
  2875  	}
  2876  	if *traceFile != "" {
  2877  		trace.Stop() // flushes trace to disk
  2878  	}
  2879  	if *memProfile != "" {
  2880  		f, err := os.Create(toOutputDir(*memProfile))
  2881  		if err != nil {
  2882  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2883  			os.Exit(2)
  2884  		}
  2885  		runtime.GC() // materialize all statistics
  2886  		if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil {
  2887  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err)
  2888  			os.Exit(2)
  2889  		}
  2890  		f.Close()
  2891  	}
  2892  	if *blockProfile != "" && *blockProfileRate >= 0 {
  2893  		f, err := os.Create(toOutputDir(*blockProfile))
  2894  		if err != nil {
  2895  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2896  			os.Exit(2)
  2897  		}
  2898  		if err = m.deps.WriteProfileTo("block", f, 0); err != nil {
  2899  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err)
  2900  			os.Exit(2)
  2901  		}
  2902  		f.Close()
  2903  	}
  2904  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  2905  		f, err := os.Create(toOutputDir(*mutexProfile))
  2906  		if err != nil {
  2907  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2908  			os.Exit(2)
  2909  		}
  2910  		if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil {
  2911  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err)
  2912  			os.Exit(2)
  2913  		}
  2914  		f.Close()
  2915  	}
  2916  	if CoverMode() != "" {
  2917  		coverReport()
  2918  	}
  2919  }
  2920  
  2921  // toOutputDir returns the file name relocated, if required, to outputDir.
  2922  // Simple implementation to avoid pulling in path/filepath.
  2923  func toOutputDir(path string) string {
  2924  	if *outputDir == "" || path == "" {
  2925  		return path
  2926  	}
  2927  	// On Windows, it's clumsy, but we can be almost always correct
  2928  	// by just looking for a drive letter and a colon.
  2929  	// Absolute paths always have a drive letter (ignoring UNC).
  2930  	// Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
  2931  	// what to do, but even then path/filepath doesn't help.
  2932  	// TODO: Worth doing better? Probably not, because we're here only
  2933  	// under the management of go test.
  2934  	if runtime.GOOS == "windows" && len(path) >= 2 {
  2935  		letter, colon := path[0], path[1]
  2936  		if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' {
  2937  			// If path starts with a drive letter we're stuck with it regardless.
  2938  			return path
  2939  		}
  2940  	}
  2941  	if os.IsPathSeparator(path[0]) {
  2942  		return path
  2943  	}
  2944  	return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path)
  2945  }
  2946  
  2947  // startAlarm starts an alarm if requested.
  2948  func (m *M) startAlarm() time.Time {
  2949  	if *timeout <= 0 {
  2950  		return time.Time{}
  2951  	}
  2952  
  2953  	deadline := time.Now().Add(*timeout)
  2954  	m.timer = time.AfterFunc(*timeout, func() {
  2955  		m.after()
  2956  		debug.SetTraceback("all")
  2957  		extra := ""
  2958  
  2959  		if list := runningList(); len(list) > 0 {
  2960  			var b strings.Builder
  2961  			b.WriteString("\nrunning tests:")
  2962  			for _, name := range list {
  2963  				b.WriteString("\n\t")
  2964  				b.WriteString(name)
  2965  			}
  2966  			extra = b.String()
  2967  		}
  2968  		panic(fmt.Sprintf("test timed out after %v%s", *timeout, extra))
  2969  	})
  2970  	return deadline
  2971  }
  2972  
  2973  // runningList returns the list of running tests.
  2974  func runningList() []string {
  2975  	var list []string
  2976  	running.Range(func(k, v any) bool {
  2977  		list = append(list, fmt.Sprintf("%s (%v)", k.(string), highPrecisionTimeSince(v.(highPrecisionTime)).Round(time.Second)))
  2978  		return true
  2979  	})
  2980  	slices.Sort(list)
  2981  	return list
  2982  }
  2983  
  2984  // stopAlarm turns off the alarm.
  2985  func (m *M) stopAlarm() {
  2986  	if *timeout > 0 {
  2987  		m.timer.Stop()
  2988  	}
  2989  }
  2990  
  2991  func parseCpuList() {
  2992  	for val := range strings.SplitSeq(*cpuListStr, ",") {
  2993  		val = strings.TrimSpace(val)
  2994  		if val == "" {
  2995  			continue
  2996  		}
  2997  		cpu, err := strconv.Atoi(val)
  2998  		if err != nil || cpu <= 0 {
  2999  			fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val)
  3000  			os.Exit(1)
  3001  		}
  3002  		cpuList = append(cpuList, cpu)
  3003  	}
  3004  	if cpuList == nil {
  3005  		cpuList = append(cpuList, runtime.GOMAXPROCS(-1))
  3006  	}
  3007  }
  3008  
  3009  func shouldFailFast() bool {
  3010  	return *failFast && numFailed.Load() > 0
  3011  }
  3012  

View as plain text