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

View as plain text