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  		// Check if the test panicked or Goexited inappropriately.
  2041  		//
  2042  		// If this happens in a normal test, print output but continue panicking.
  2043  		// tRunner is called in its own goroutine, so this terminates the process.
  2044  		//
  2045  		// If this happens while fuzzing, recover from the panic and treat it like a
  2046  		// normal failure. It's important that the process keeps running in order to
  2047  		// find short inputs that cause panics.
  2048  		err := recover()
  2049  		signal := true
  2050  
  2051  		t.mu.RLock()
  2052  		finished := t.finished
  2053  		t.mu.RUnlock()
  2054  		if !finished && err == nil {
  2055  			err = errNilPanicOrGoexit
  2056  			for p := t.parent; p != nil; p = p.parent {
  2057  				p.mu.RLock()
  2058  				finished = p.finished
  2059  				p.mu.RUnlock()
  2060  				if finished {
  2061  					if !t.isParallel {
  2062  						t.Errorf("%v: subtest may have called FailNow on a parent test", err)
  2063  						err = nil
  2064  					}
  2065  					signal = false
  2066  					break
  2067  				}
  2068  			}
  2069  		}
  2070  
  2071  		if err != nil && t.tstate.isFuzzing {
  2072  			prefix := "panic: "
  2073  			if err == errNilPanicOrGoexit {
  2074  				prefix = ""
  2075  			}
  2076  			t.Errorf("%s%s\n%s\n", prefix, err, string(debug.Stack()))
  2077  			t.mu.Lock()
  2078  			t.finished = true
  2079  			t.mu.Unlock()
  2080  			err = nil
  2081  		}
  2082  
  2083  		// Use a deferred call to ensure that we report that the test is
  2084  		// complete even if a cleanup function calls t.FailNow. See issue 41355.
  2085  		didPanic := false
  2086  		defer func() {
  2087  			// Only report that the test is complete if it doesn't panic,
  2088  			// as otherwise the test binary can exit before the panic is
  2089  			// reported to the user. See issue 41479.
  2090  			if didPanic {
  2091  				return
  2092  			}
  2093  			if err != nil {
  2094  				panic(err)
  2095  			}
  2096  			running.Delete(t.name)
  2097  			if t.isParallel {
  2098  				parallelStop.Add(1)
  2099  			}
  2100  			t.signal <- signal
  2101  		}()
  2102  
  2103  		doPanic := func(err any) {
  2104  			t.Fail()
  2105  			if r := t.runCleanup(recoverAndReturnPanic); r != nil {
  2106  				t.Logf("cleanup panicked with %v", r)
  2107  			}
  2108  			// Flush the output log up to the root before dying.
  2109  			// Skip this if this *T is a synctest bubble, because we're not a subtest.
  2110  			for root := &t.common; !root.isSynctest && root.parent != nil; root = root.parent {
  2111  				root.mu.Lock()
  2112  				root.duration += highPrecisionTimeSince(root.start)
  2113  				d := root.duration
  2114  				root.mu.Unlock()
  2115  				// Output buffered logs.
  2116  				root.flushPartial()
  2117  				root.flushToParent(root.name, "--- FAIL: %s (%s)\n", root.name, fmtDuration(d))
  2118  				if r := root.parent.runCleanup(recoverAndReturnPanic); r != nil {
  2119  					fmt.Fprintf(root.parent.w, "cleanup panicked with %v", r)
  2120  				}
  2121  			}
  2122  			didPanic = true
  2123  			panic(err)
  2124  		}
  2125  		if err != nil {
  2126  			doPanic(err)
  2127  		}
  2128  
  2129  		t.duration += highPrecisionTimeSince(t.start)
  2130  
  2131  		if len(t.sub) > 0 {
  2132  			// Run parallel subtests.
  2133  
  2134  			// Decrease the running count for this test and mark it as no longer running.
  2135  			t.tstate.release()
  2136  			running.Delete(t.name)
  2137  
  2138  			// Release the parallel subtests.
  2139  			close(t.barrier)
  2140  			// Wait for subtests to complete.
  2141  			for _, sub := range t.sub {
  2142  				<-sub.signal
  2143  			}
  2144  
  2145  			// Run any cleanup callbacks, marking the test as running
  2146  			// in case the cleanup hangs.
  2147  			cleanupStart := highPrecisionTimeNow()
  2148  			running.Store(t.name, cleanupStart)
  2149  			err := t.runCleanup(recoverAndReturnPanic)
  2150  			t.duration += highPrecisionTimeSince(cleanupStart)
  2151  			if err != nil {
  2152  				doPanic(err)
  2153  			}
  2154  			t.checkRaces()
  2155  			if !t.isParallel {
  2156  				// Reacquire the count for sequential tests. See comment in Run.
  2157  				t.tstate.waitParallel()
  2158  			}
  2159  		} else if t.isParallel {
  2160  			// Only release the count for this test if it was run as a parallel
  2161  			// test. See comment in Run method.
  2162  			t.tstate.release()
  2163  		}
  2164  		// Output buffered logs.
  2165  		for root := &t.common; root.parent != nil; root = root.parent {
  2166  			root.flushPartial()
  2167  		}
  2168  
  2169  		// Record this test's failure for -failfast. This must happen after the
  2170  		// test's cleanup functions have run, since a cleanup may call t.Fail.
  2171  		// See go.dev/issue/61034.
  2172  		if t.Failed() {
  2173  			numFailed.Add(1)
  2174  		}
  2175  
  2176  		t.report() // Report after all subtests have finished.
  2177  
  2178  		// Do not lock t.done to allow race detector to detect race in case
  2179  		// the user does not appropriately synchronize a goroutine.
  2180  		t.done = true
  2181  		if t.parent != nil && !t.hasSub.Load() {
  2182  			t.setRan()
  2183  		}
  2184  	}()
  2185  	defer func() {
  2186  		if len(t.sub) == 0 {
  2187  			t.runCleanup(normalPanic)
  2188  		}
  2189  	}()
  2190  
  2191  	t.start = highPrecisionTimeNow()
  2192  	t.resetRaces()
  2193  	fn(t)
  2194  
  2195  	// code beyond here will not be executed when FailNow is invoked
  2196  	t.mu.Lock()
  2197  	t.finished = true
  2198  	t.mu.Unlock()
  2199  }
  2200  
  2201  // Run runs f as a subtest of t called name. It runs f in a separate goroutine
  2202  // and blocks until f returns or calls t.Parallel to become a parallel test.
  2203  // Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
  2204  //
  2205  // Run may be called simultaneously from multiple goroutines, but all such calls
  2206  // must return before the outer test function for t returns.
  2207  func (t *T) Run(name string, f func(t *T)) bool {
  2208  	if t.isSynctest {
  2209  		panic("testing: t.Run called inside synctest bubble")
  2210  	}
  2211  	if t.cleanupStarted.Load() {
  2212  		panic("testing: t.Run called during t.Cleanup")
  2213  	}
  2214  
  2215  	t.hasSub.Store(true)
  2216  	testName, ok, _ := t.tstate.match.fullName(&t.common, name)
  2217  	if !ok || shouldFailFast() {
  2218  		return true
  2219  	}
  2220  	// Record the stack trace at the point of this call so that if the subtest
  2221  	// function - which runs in a separate stack - is marked as a helper, we can
  2222  	// continue walking the stack into the parent test.
  2223  	var pc [maxStackLen]uintptr
  2224  	n := runtime.Callers(2, pc[:])
  2225  
  2226  	// There's no reason to inherit this context from parent. The user's code can't observe
  2227  	// the difference between the background context and the one from the parent test.
  2228  	ctx, cancelCtx := context.WithCancel(context.Background())
  2229  	t = &T{
  2230  		common: common{
  2231  			barrier:    make(chan bool),
  2232  			signal:     make(chan bool, 1),
  2233  			name:       testName,
  2234  			modulePath: t.modulePath,
  2235  			importPath: t.importPath,
  2236  			parent:     &t.common,
  2237  			level:      t.level + 1,
  2238  			creator:    pc[:n],
  2239  			chatty:     t.chatty,
  2240  			ctx:        ctx,
  2241  			cancelCtx:  cancelCtx,
  2242  		},
  2243  		tstate: t.tstate,
  2244  	}
  2245  	t.w = indenter{&t.common}
  2246  	t.setOutputWriter()
  2247  
  2248  	if t.chatty != nil {
  2249  		t.chatty.Updatef(t.name, "=== RUN   %s\n", t.name)
  2250  	}
  2251  	running.Store(t.name, highPrecisionTimeNow())
  2252  
  2253  	// Instead of reducing the running count of this test before calling the
  2254  	// tRunner and increasing it afterwards, we rely on tRunner keeping the
  2255  	// count correct. This ensures that a sequence of sequential tests runs
  2256  	// without being preempted, even when their parent is a parallel test. This
  2257  	// may especially reduce surprises if *parallel == 1.
  2258  	go tRunner(t, f)
  2259  
  2260  	// The parent goroutine will block until the subtest either finishes or calls
  2261  	// Parallel, but in general we don't know whether the parent goroutine is the
  2262  	// top-level test function or some other goroutine it has spawned.
  2263  	// To avoid confusing false-negatives, we leave the parent in the running map
  2264  	// even though in the typical case it is blocked.
  2265  
  2266  	if !<-t.signal {
  2267  		// At this point, it is likely that FailNow was called on one of the
  2268  		// parent tests by one of the subtests. Continue aborting up the chain.
  2269  		runtime.Goexit()
  2270  	}
  2271  
  2272  	if t.chatty != nil && t.chatty.json {
  2273  		t.chatty.Updatef(t.parent.name, "=== NAME  %s\n", t.parent.name)
  2274  	}
  2275  	return !t.failed
  2276  }
  2277  
  2278  // testingSynctestTest runs f within a synctest bubble.
  2279  // It is called by synctest.Test, from within an already-created bubble.
  2280  //
  2281  //go:linkname testingSynctestTest testing/synctest.testingSynctestTest
  2282  func testingSynctestTest(t *T, f func(*T)) (ok bool) {
  2283  	if t.cleanupStarted.Load() {
  2284  		panic("testing: synctest.Run called during t.Cleanup")
  2285  	}
  2286  
  2287  	var pc [maxStackLen]uintptr
  2288  	n := runtime.Callers(2, pc[:])
  2289  
  2290  	ctx, cancelCtx := context.WithCancel(context.Background())
  2291  	t2 := &T{
  2292  		common: common{
  2293  			barrier:    make(chan bool),
  2294  			signal:     make(chan bool, 1),
  2295  			name:       t.name,
  2296  			parent:     &t.common,
  2297  			level:      t.level + 1,
  2298  			creator:    pc[:n],
  2299  			chatty:     t.chatty,
  2300  			ctx:        ctx,
  2301  			cancelCtx:  cancelCtx,
  2302  			isSynctest: true,
  2303  		},
  2304  		tstate: t.tstate,
  2305  	}
  2306  
  2307  	go tRunner(t2, f)
  2308  	if !<-t2.signal {
  2309  		// At this point, it is likely that FailNow was called on one of the
  2310  		// parent tests by one of the subtests. Continue aborting up the chain.
  2311  		runtime.Goexit()
  2312  	}
  2313  	return !t2.failed
  2314  }
  2315  
  2316  // Deadline reports the time at which the test binary will have
  2317  // exceeded the timeout specified by the -timeout flag.
  2318  //
  2319  // The ok result is false if the -timeout flag indicates “no timeout” (0).
  2320  func (t *T) Deadline() (deadline time.Time, ok bool) {
  2321  	if t.isSynctest {
  2322  		// There's no point in returning a real-clock deadline to
  2323  		// a test using a fake clock. We could return "no timeout",
  2324  		// but panicking makes it easier for users to catch the error.
  2325  		panic("testing: t.Deadline called inside synctest bubble")
  2326  	}
  2327  	deadline = t.tstate.deadline
  2328  	return deadline, !deadline.IsZero()
  2329  }
  2330  
  2331  // testState holds all fields that are common to all tests. This includes
  2332  // synchronization primitives to run at most *parallel tests.
  2333  type testState struct {
  2334  	match    *matcher
  2335  	deadline time.Time
  2336  
  2337  	// isFuzzing is true in the state used when generating random inputs
  2338  	// for fuzz targets. isFuzzing is false when running normal tests and
  2339  	// when running fuzz tests as unit tests (without -fuzz or when -fuzz
  2340  	// does not match).
  2341  	isFuzzing bool
  2342  
  2343  	mu sync.Mutex
  2344  
  2345  	// Channel used to signal tests that are ready to be run in parallel.
  2346  	startParallel chan bool
  2347  
  2348  	// running is the number of tests currently running in parallel.
  2349  	// This does not include tests that are waiting for subtests to complete.
  2350  	running int
  2351  
  2352  	// numWaiting is the number tests waiting to be run in parallel.
  2353  	numWaiting int
  2354  
  2355  	// maxParallel is a copy of the parallel flag.
  2356  	maxParallel int
  2357  }
  2358  
  2359  func newTestState(maxParallel int, m *matcher) *testState {
  2360  	return &testState{
  2361  		match:         m,
  2362  		startParallel: make(chan bool),
  2363  		maxParallel:   maxParallel,
  2364  		running:       1, // Set the count to 1 for the main (sequential) test.
  2365  	}
  2366  }
  2367  
  2368  func (s *testState) waitParallel() {
  2369  	s.mu.Lock()
  2370  	if s.running < s.maxParallel {
  2371  		s.running++
  2372  		s.mu.Unlock()
  2373  		return
  2374  	}
  2375  	s.numWaiting++
  2376  	s.mu.Unlock()
  2377  	<-s.startParallel
  2378  }
  2379  
  2380  func (s *testState) release() {
  2381  	s.mu.Lock()
  2382  	if s.numWaiting == 0 {
  2383  		s.running--
  2384  		s.mu.Unlock()
  2385  		return
  2386  	}
  2387  	s.numWaiting--
  2388  	s.mu.Unlock()
  2389  	s.startParallel <- true // Pick a waiting test to be run.
  2390  }
  2391  
  2392  // No one should be using func Main anymore.
  2393  // See the doc comment on func Main and use MainStart instead.
  2394  var errMain = errors.New("testing: unexpected use of func Main")
  2395  
  2396  type matchStringOnly func(pat, str string) (bool, error)
  2397  
  2398  func (f matchStringOnly) MatchString(pat, str string) (bool, error)   { return f(pat, str) }
  2399  func (f matchStringOnly) StartCPUProfile(w io.Writer) error           { return errMain }
  2400  func (f matchStringOnly) StopCPUProfile()                             {}
  2401  func (f matchStringOnly) WriteProfileTo(string, io.Writer, int) error { return errMain }
  2402  func (f matchStringOnly) ModulePath() string                          { return "" }
  2403  func (f matchStringOnly) ImportPath() string                          { return "" }
  2404  func (f matchStringOnly) StartTestLog(io.Writer)                      {}
  2405  func (f matchStringOnly) StopTestLog() error                          { return errMain }
  2406  func (f matchStringOnly) SetPanicOnExit0(bool)                        {}
  2407  func (f matchStringOnly) CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error {
  2408  	return errMain
  2409  }
  2410  func (f matchStringOnly) RunFuzzWorker(func(corpusEntry) error) error { return errMain }
  2411  func (f matchStringOnly) ReadCorpus(string, []reflect.Type) ([]corpusEntry, error) {
  2412  	return nil, errMain
  2413  }
  2414  func (f matchStringOnly) CheckCorpus([]any, []reflect.Type) error { return nil }
  2415  func (f matchStringOnly) ResetCoverage()                          {}
  2416  func (f matchStringOnly) SnapshotCoverage()                       {}
  2417  
  2418  func (f matchStringOnly) InitRuntimeCoverage() (mode string, tearDown func(string, string) (string, error), snapcov func() float64) {
  2419  	return
  2420  }
  2421  
  2422  // Main is an internal function, part of the implementation of the "go test" command.
  2423  // It was exported because it is cross-package and predates "internal" packages.
  2424  // It is no longer used by "go test" but preserved, as much as possible, for other
  2425  // systems that simulate "go test" using Main, but Main sometimes cannot be updated as
  2426  // new functionality is added to the testing package.
  2427  // Systems simulating "go test" should be updated to use [MainStart].
  2428  func Main(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, examples []InternalExample) {
  2429  	os.Exit(MainStart(matchStringOnly(matchString), tests, benchmarks, nil, examples).Run())
  2430  }
  2431  
  2432  // M is a type passed to a TestMain function to run the actual tests.
  2433  type M struct {
  2434  	deps        testDeps
  2435  	tests       []InternalTest
  2436  	benchmarks  []InternalBenchmark
  2437  	fuzzTargets []InternalFuzzTarget
  2438  	examples    []InternalExample
  2439  
  2440  	timer     *time.Timer
  2441  	afterOnce sync.Once
  2442  
  2443  	numRun int
  2444  
  2445  	// value to pass to os.Exit, the outer test func main
  2446  	// harness calls os.Exit with this code. See #34129.
  2447  	exitCode int
  2448  }
  2449  
  2450  // testDeps is an internal interface of functionality that is
  2451  // passed into this package by a test's generated main package.
  2452  // The canonical implementation of this interface is
  2453  // testing/internal/testdeps's TestDeps.
  2454  type testDeps interface {
  2455  	ImportPath() string
  2456  	ModulePath() string
  2457  	MatchString(pat, str string) (bool, error)
  2458  	SetPanicOnExit0(bool)
  2459  	StartCPUProfile(io.Writer) error
  2460  	StopCPUProfile()
  2461  	StartTestLog(io.Writer)
  2462  	StopTestLog() error
  2463  	WriteProfileTo(string, io.Writer, int) error
  2464  	CoordinateFuzzing(time.Duration, int64, time.Duration, int64, int, []corpusEntry, []reflect.Type, string, string) error
  2465  	RunFuzzWorker(func(corpusEntry) error) error
  2466  	ReadCorpus(string, []reflect.Type) ([]corpusEntry, error)
  2467  	CheckCorpus([]any, []reflect.Type) error
  2468  	ResetCoverage()
  2469  	SnapshotCoverage()
  2470  	InitRuntimeCoverage() (mode string, tearDown func(coverprofile string, gocoverdir string) (string, error), snapcov func() float64)
  2471  }
  2472  
  2473  // MainStart is meant for use by tests generated by 'go test'.
  2474  // It is not meant to be called directly and is not subject to the Go 1 compatibility document.
  2475  // It may change signature from release to release.
  2476  func MainStart(deps testDeps, tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) *M {
  2477  	registerCover(deps.InitRuntimeCoverage())
  2478  	Init()
  2479  	return &M{
  2480  		deps:        deps,
  2481  		tests:       tests,
  2482  		benchmarks:  benchmarks,
  2483  		fuzzTargets: fuzzTargets,
  2484  		examples:    examples,
  2485  	}
  2486  }
  2487  
  2488  var (
  2489  	testingTesting bool
  2490  	realStderr     *os.File
  2491  )
  2492  
  2493  // Run runs the tests. It returns an exit code to pass to os.Exit.
  2494  // The exit code is zero when all tests pass, and non-zero for any kind
  2495  // of failure. For machine readable test results, parse the output of
  2496  // 'go test -json'.
  2497  func (m *M) Run() (code int) {
  2498  	defer func() {
  2499  		code = m.exitCode
  2500  	}()
  2501  
  2502  	// Count the number of calls to m.Run.
  2503  	// We only ever expected 1, but we didn't enforce that,
  2504  	// and now there are tests in the wild that call m.Run multiple times.
  2505  	// Sigh. go.dev/issue/23129.
  2506  	m.numRun++
  2507  
  2508  	// TestMain may have already called flag.Parse.
  2509  	if !flag.Parsed() {
  2510  		flag.Parse()
  2511  	}
  2512  
  2513  	if chatty.json {
  2514  		// With -v=json, stdout and stderr are pointing to the same pipe,
  2515  		// which is leading into test2json. In general, operating systems
  2516  		// do a good job of ensuring that writes to the same pipe through
  2517  		// different file descriptors are delivered whole, so that writing
  2518  		// AAA to stdout and BBB to stderr simultaneously produces
  2519  		// AAABBB or BBBAAA on the pipe, not something like AABBBA.
  2520  		// However, the exception to this is when the pipe fills: in that
  2521  		// case, Go's use of non-blocking I/O means that writing AAA
  2522  		// or BBB might be split across multiple system calls, making it
  2523  		// entirely possible to get output like AABBBA. The same problem
  2524  		// happens inside the operating system kernel if we switch to
  2525  		// blocking I/O on the pipe. This interleaved output can do things
  2526  		// like print unrelated messages in the middle of a TestFoo line,
  2527  		// which confuses test2json. Setting os.Stderr = os.Stdout will make
  2528  		// them share a single pfd, which will hold a lock for each program
  2529  		// write, preventing any interleaving.
  2530  		//
  2531  		// It might be nice to set Stderr = Stdout always, or perhaps if
  2532  		// we can tell they are the same file, but for now -v=json is
  2533  		// a very clear signal. Making the two files the same may cause
  2534  		// surprises if programs close os.Stdout but expect to be able
  2535  		// to continue to write to os.Stderr, but it's hard to see why a
  2536  		// test would think it could take over global state that way.
  2537  		//
  2538  		// This fix only helps programs where the output is coming directly
  2539  		// from Go code. It does not help programs in which a subprocess is
  2540  		// writing to stderr or stdout at the same time that a Go test is writing output.
  2541  		// It also does not help when the output is coming from the runtime,
  2542  		// such as when using the print/println functions, since that code writes
  2543  		// directly to fd 2 without any locking.
  2544  		// We keep realStderr around to prevent fd 2 from being closed.
  2545  		//
  2546  		// See go.dev/issue/33419.
  2547  		realStderr = os.Stderr
  2548  		os.Stderr = os.Stdout
  2549  	}
  2550  
  2551  	if *parallel < 1 {
  2552  		fmt.Fprintln(os.Stderr, "testing: -parallel can only be given a positive integer")
  2553  		flag.Usage()
  2554  		m.exitCode = 2
  2555  		return
  2556  	}
  2557  	if *matchFuzz != "" && *fuzzCacheDir == "" {
  2558  		fmt.Fprintln(os.Stderr, "testing: -test.fuzzcachedir must be set if -test.fuzz is set")
  2559  		flag.Usage()
  2560  		m.exitCode = 2
  2561  		return
  2562  	}
  2563  
  2564  	if *matchList != "" {
  2565  		listTests(m.deps.MatchString, m.tests, m.benchmarks, m.fuzzTargets, m.examples)
  2566  		m.exitCode = 0
  2567  		return
  2568  	}
  2569  
  2570  	if *shuffle != "off" {
  2571  		var n int64
  2572  		var err error
  2573  		if *shuffle == "on" {
  2574  			n = time.Now().UnixNano()
  2575  		} else {
  2576  			n, err = strconv.ParseInt(*shuffle, 10, 64)
  2577  			if err != nil {
  2578  				fmt.Fprintln(os.Stderr, `testing: -shuffle should be "off", "on", or a valid integer:`, err)
  2579  				m.exitCode = 2
  2580  				return
  2581  			}
  2582  		}
  2583  		fmt.Println("-test.shuffle", n)
  2584  		rng := rand.New(rand.NewSource(n))
  2585  		rng.Shuffle(len(m.tests), func(i, j int) { m.tests[i], m.tests[j] = m.tests[j], m.tests[i] })
  2586  		rng.Shuffle(len(m.benchmarks), func(i, j int) { m.benchmarks[i], m.benchmarks[j] = m.benchmarks[j], m.benchmarks[i] })
  2587  	}
  2588  
  2589  	parseCpuList()
  2590  
  2591  	m.before()
  2592  	defer m.after()
  2593  
  2594  	// Run tests, examples, and benchmarks unless this is a fuzz worker process.
  2595  	// Workers start after this is done by their parent process, and they should
  2596  	// not repeat this work.
  2597  	if !*isFuzzWorker {
  2598  		deadline := m.startAlarm()
  2599  		haveExamples = len(m.examples) > 0
  2600  		testRan, testOk := runTests(m.deps.ModulePath(), m.deps.ImportPath(), m.deps.MatchString, m.tests, deadline)
  2601  		fuzzTargetsRan, fuzzTargetsOk := runFuzzTests(m.deps, m.fuzzTargets, deadline)
  2602  		exampleRan, exampleOk := runExamples(m.deps.MatchString, m.examples)
  2603  		m.stopAlarm()
  2604  		if !testRan && !exampleRan && !fuzzTargetsRan && *matchBenchmarks == "" && *matchFuzz == "" {
  2605  			fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  2606  			if testingTesting && *match != "^$" {
  2607  				// If this happens during testing of package testing it could be that
  2608  				// package testing's own logic for when to run a test is broken,
  2609  				// in which case every test will run nothing and succeed,
  2610  				// with no obvious way to detect this problem (since no tests are running).
  2611  				// So make 'no tests to run' a hard failure when testing package testing itself.
  2612  				fmt.Print(chatty.prefix(), "FAIL: package testing must run tests\n")
  2613  				testOk = false
  2614  			}
  2615  		}
  2616  		anyFailed := !testOk || !exampleOk || !fuzzTargetsOk || !runBenchmarks(m.deps.ImportPath(), m.deps.MatchString, m.benchmarks)
  2617  		if !anyFailed && race.Errors() > 0 {
  2618  			fmt.Print(chatty.prefix(), "testing: race detected outside of test execution\n")
  2619  			anyFailed = true
  2620  		}
  2621  		if anyFailed {
  2622  			fmt.Print(chatty.prefix(), "FAIL\n")
  2623  			m.exitCode = 1
  2624  			return
  2625  		}
  2626  	}
  2627  
  2628  	fuzzingOk := runFuzzing(m.deps, m.fuzzTargets)
  2629  	if !fuzzingOk {
  2630  		fmt.Print(chatty.prefix(), "FAIL\n")
  2631  		if *isFuzzWorker {
  2632  			m.exitCode = fuzzWorkerExitCode
  2633  		} else {
  2634  			m.exitCode = 1
  2635  		}
  2636  		return
  2637  	}
  2638  
  2639  	m.exitCode = 0
  2640  	if !*isFuzzWorker {
  2641  		fmt.Print(chatty.prefix(), "PASS\n")
  2642  	}
  2643  	return
  2644  }
  2645  
  2646  func (t *T) report() {
  2647  	if t.parent == nil {
  2648  		return
  2649  	}
  2650  	if t.isSynctest {
  2651  		return // t.parent will handle reporting
  2652  	}
  2653  	dstr := fmtDuration(t.duration)
  2654  	format := "--- %s: %s (%s)\n"
  2655  	if t.Failed() {
  2656  		t.flushToParent(t.name, format, "FAIL", t.name, dstr)
  2657  	} else if t.chatty != nil {
  2658  		if t.Skipped() {
  2659  			t.flushToParent(t.name, format, "SKIP", t.name, dstr)
  2660  		} else {
  2661  			t.flushToParent(t.name, format, "PASS", t.name, dstr)
  2662  		}
  2663  	}
  2664  }
  2665  
  2666  func listTests(matchString func(pat, str string) (bool, error), tests []InternalTest, benchmarks []InternalBenchmark, fuzzTargets []InternalFuzzTarget, examples []InternalExample) {
  2667  	if _, err := matchString(*matchList, "non-empty"); err != nil {
  2668  		fmt.Fprintf(os.Stderr, "testing: invalid regexp in -test.list (%q): %s\n", *matchList, err)
  2669  		os.Exit(1)
  2670  	}
  2671  
  2672  	for _, test := range tests {
  2673  		if ok, _ := matchString(*matchList, test.Name); ok {
  2674  			fmt.Println(test.Name)
  2675  		}
  2676  	}
  2677  	for _, bench := range benchmarks {
  2678  		if ok, _ := matchString(*matchList, bench.Name); ok {
  2679  			fmt.Println(bench.Name)
  2680  		}
  2681  	}
  2682  	for _, fuzzTarget := range fuzzTargets {
  2683  		if ok, _ := matchString(*matchList, fuzzTarget.Name); ok {
  2684  			fmt.Println(fuzzTarget.Name)
  2685  		}
  2686  	}
  2687  	for _, example := range examples {
  2688  		if ok, _ := matchString(*matchList, example.Name); ok {
  2689  			fmt.Println(example.Name)
  2690  		}
  2691  	}
  2692  }
  2693  
  2694  // RunTests is an internal function but exported because it is cross-package;
  2695  // it is part of the implementation of the "go test" command.
  2696  func RunTests(matchString func(pat, str string) (bool, error), tests []InternalTest) (ok bool) {
  2697  	var deadline time.Time
  2698  	if *timeout > 0 {
  2699  		deadline = time.Now().Add(*timeout)
  2700  	}
  2701  	ran, ok := runTests("", "", matchString, tests, deadline)
  2702  	if !ran && !haveExamples {
  2703  		fmt.Fprintln(os.Stderr, "testing: warning: no tests to run")
  2704  	}
  2705  	return ok
  2706  }
  2707  
  2708  func runTests(modulePath, importPath string, matchString func(pat, str string) (bool, error), tests []InternalTest, deadline time.Time) (ran, ok bool) {
  2709  	ok = true
  2710  	for _, procs := range cpuList {
  2711  		runtime.GOMAXPROCS(procs)
  2712  		for i := uint(0); i < *count; i++ {
  2713  			if shouldFailFast() {
  2714  				break
  2715  			}
  2716  			if i > 0 && !ran {
  2717  				// There were no tests to run on the first
  2718  				// iteration. This won't change, so no reason
  2719  				// to keep trying.
  2720  				break
  2721  			}
  2722  			ctx, cancelCtx := context.WithCancel(context.Background())
  2723  			tstate := newTestState(*parallel, newMatcher(matchString, *match, "-test.run", *skip))
  2724  			tstate.deadline = deadline
  2725  			t := &T{
  2726  				common: common{
  2727  					signal:     make(chan bool, 1),
  2728  					barrier:    make(chan bool),
  2729  					w:          os.Stdout,
  2730  					ctx:        ctx,
  2731  					cancelCtx:  cancelCtx,
  2732  					modulePath: modulePath,
  2733  					importPath: importPath,
  2734  				},
  2735  				tstate: tstate,
  2736  			}
  2737  			if Verbose() {
  2738  				t.chatty = newChattyPrinter(t.w)
  2739  			}
  2740  			tRunner(t, func(t *T) {
  2741  				for _, test := range tests {
  2742  					t.Run(test.Name, test.F)
  2743  				}
  2744  			})
  2745  			select {
  2746  			case <-t.signal:
  2747  			default:
  2748  				panic("internal error: tRunner exited without sending on t.signal")
  2749  			}
  2750  			ok = ok && !t.Failed()
  2751  			ran = ran || t.ran
  2752  		}
  2753  	}
  2754  	return ran, ok
  2755  }
  2756  
  2757  // before runs before all testing.
  2758  func (m *M) before() {
  2759  	if *memProfileRate > 0 {
  2760  		runtime.MemProfileRate = *memProfileRate
  2761  	}
  2762  	if *cpuProfile != "" {
  2763  		f, err := os.Create(toOutputDir(*cpuProfile))
  2764  		if err != nil {
  2765  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2766  			return
  2767  		}
  2768  		if err := m.deps.StartCPUProfile(f); err != nil {
  2769  			fmt.Fprintf(os.Stderr, "testing: can't start cpu profile: %s\n", err)
  2770  			f.Close()
  2771  			return
  2772  		}
  2773  		// Could save f so after can call f.Close; not worth the effort.
  2774  	}
  2775  	if *traceFile != "" {
  2776  		f, err := os.Create(toOutputDir(*traceFile))
  2777  		if err != nil {
  2778  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2779  			return
  2780  		}
  2781  		if err := trace.Start(f); err != nil {
  2782  			fmt.Fprintf(os.Stderr, "testing: can't start tracing: %s\n", err)
  2783  			f.Close()
  2784  			return
  2785  		}
  2786  		// Could save f so after can call f.Close; not worth the effort.
  2787  	}
  2788  	if *blockProfile != "" && *blockProfileRate >= 0 {
  2789  		runtime.SetBlockProfileRate(*blockProfileRate)
  2790  	}
  2791  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  2792  		runtime.SetMutexProfileFraction(*mutexProfileFraction)
  2793  	}
  2794  	if *coverProfile != "" && CoverMode() == "" {
  2795  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.coverprofile because test binary was not built with coverage enabled\n")
  2796  		os.Exit(2)
  2797  	}
  2798  	if *gocoverdir != "" && CoverMode() == "" {
  2799  		fmt.Fprintf(os.Stderr, "testing: cannot use -test.gocoverdir because test binary was not built with coverage enabled\n")
  2800  		os.Exit(2)
  2801  	}
  2802  	if *artifacts {
  2803  		var err error
  2804  		artifactDir, err = filepath.Abs(toOutputDir("_artifacts"))
  2805  		if err != nil {
  2806  			fmt.Fprintf(os.Stderr, "testing: cannot make -test.outputdir absolute: %v\n", err)
  2807  			os.Exit(2)
  2808  		}
  2809  		if err := os.Mkdir(artifactDir, 0o777); err != nil && !errors.Is(err, os.ErrExist) {
  2810  			fmt.Fprintf(os.Stderr, "testing: %v\n", err)
  2811  			os.Exit(2)
  2812  		}
  2813  	}
  2814  	if *testlog != "" {
  2815  		// Note: Not using toOutputDir.
  2816  		// This file is for use by cmd/go, not users.
  2817  		var f *os.File
  2818  		var err error
  2819  		if m.numRun == 1 {
  2820  			f, err = os.Create(*testlog)
  2821  		} else {
  2822  			f, err = os.OpenFile(*testlog, os.O_WRONLY, 0)
  2823  			if err == nil {
  2824  				f.Seek(0, io.SeekEnd)
  2825  			}
  2826  		}
  2827  		if err != nil {
  2828  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2829  			os.Exit(2)
  2830  		}
  2831  		m.deps.StartTestLog(f)
  2832  		testlogFile = f
  2833  	}
  2834  	if *panicOnExit0 {
  2835  		m.deps.SetPanicOnExit0(true)
  2836  	}
  2837  }
  2838  
  2839  // after runs after all testing.
  2840  func (m *M) after() {
  2841  	m.afterOnce.Do(func() {
  2842  		m.writeProfiles()
  2843  	})
  2844  
  2845  	// Restore PanicOnExit0 after every run, because we set it to true before
  2846  	// every run. Otherwise, if m.Run is called multiple times the behavior of
  2847  	// os.Exit(0) will not be restored after the second run.
  2848  	if *panicOnExit0 {
  2849  		m.deps.SetPanicOnExit0(false)
  2850  	}
  2851  }
  2852  
  2853  func (m *M) writeProfiles() {
  2854  	if *testlog != "" {
  2855  		if err := m.deps.StopTestLog(); err != nil {
  2856  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  2857  			os.Exit(2)
  2858  		}
  2859  		if err := testlogFile.Close(); err != nil {
  2860  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *testlog, err)
  2861  			os.Exit(2)
  2862  		}
  2863  	}
  2864  	if *cpuProfile != "" {
  2865  		m.deps.StopCPUProfile() // flushes profile to disk
  2866  	}
  2867  	if *traceFile != "" {
  2868  		trace.Stop() // flushes trace to disk
  2869  	}
  2870  	if *memProfile != "" {
  2871  		f, err := os.Create(toOutputDir(*memProfile))
  2872  		if err != nil {
  2873  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2874  			os.Exit(2)
  2875  		}
  2876  		runtime.GC() // materialize all statistics
  2877  		if err = m.deps.WriteProfileTo("allocs", f, 0); err != nil {
  2878  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *memProfile, err)
  2879  			os.Exit(2)
  2880  		}
  2881  		f.Close()
  2882  	}
  2883  	if *blockProfile != "" && *blockProfileRate >= 0 {
  2884  		f, err := os.Create(toOutputDir(*blockProfile))
  2885  		if err != nil {
  2886  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2887  			os.Exit(2)
  2888  		}
  2889  		if err = m.deps.WriteProfileTo("block", f, 0); err != nil {
  2890  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *blockProfile, err)
  2891  			os.Exit(2)
  2892  		}
  2893  		f.Close()
  2894  	}
  2895  	if *mutexProfile != "" && *mutexProfileFraction >= 0 {
  2896  		f, err := os.Create(toOutputDir(*mutexProfile))
  2897  		if err != nil {
  2898  			fmt.Fprintf(os.Stderr, "testing: %s\n", err)
  2899  			os.Exit(2)
  2900  		}
  2901  		if err = m.deps.WriteProfileTo("mutex", f, 0); err != nil {
  2902  			fmt.Fprintf(os.Stderr, "testing: can't write %s: %s\n", *mutexProfile, err)
  2903  			os.Exit(2)
  2904  		}
  2905  		f.Close()
  2906  	}
  2907  	if CoverMode() != "" {
  2908  		coverReport()
  2909  	}
  2910  }
  2911  
  2912  // toOutputDir returns the file name relocated, if required, to outputDir.
  2913  // Simple implementation to avoid pulling in path/filepath.
  2914  func toOutputDir(path string) string {
  2915  	if *outputDir == "" || path == "" {
  2916  		return path
  2917  	}
  2918  	// On Windows, it's clumsy, but we can be almost always correct
  2919  	// by just looking for a drive letter and a colon.
  2920  	// Absolute paths always have a drive letter (ignoring UNC).
  2921  	// Problem: if path == "C:A" and outputdir == "C:\Go" it's unclear
  2922  	// what to do, but even then path/filepath doesn't help.
  2923  	// TODO: Worth doing better? Probably not, because we're here only
  2924  	// under the management of go test.
  2925  	if runtime.GOOS == "windows" && len(path) >= 2 {
  2926  		letter, colon := path[0], path[1]
  2927  		if ('a' <= letter && letter <= 'z' || 'A' <= letter && letter <= 'Z') && colon == ':' {
  2928  			// If path starts with a drive letter we're stuck with it regardless.
  2929  			return path
  2930  		}
  2931  	}
  2932  	if os.IsPathSeparator(path[0]) {
  2933  		return path
  2934  	}
  2935  	return fmt.Sprintf("%s%c%s", *outputDir, os.PathSeparator, path)
  2936  }
  2937  
  2938  // startAlarm starts an alarm if requested.
  2939  func (m *M) startAlarm() time.Time {
  2940  	if *timeout <= 0 {
  2941  		return time.Time{}
  2942  	}
  2943  
  2944  	deadline := time.Now().Add(*timeout)
  2945  	m.timer = time.AfterFunc(*timeout, func() {
  2946  		m.after()
  2947  		debug.SetTraceback("all")
  2948  		extra := ""
  2949  
  2950  		if list := runningList(); len(list) > 0 {
  2951  			var b strings.Builder
  2952  			b.WriteString("\nrunning tests:")
  2953  			for _, name := range list {
  2954  				b.WriteString("\n\t")
  2955  				b.WriteString(name)
  2956  			}
  2957  			extra = b.String()
  2958  		}
  2959  		panic(fmt.Sprintf("test timed out after %v%s", *timeout, extra))
  2960  	})
  2961  	return deadline
  2962  }
  2963  
  2964  // runningList returns the list of running tests.
  2965  func runningList() []string {
  2966  	var list []string
  2967  	running.Range(func(k, v any) bool {
  2968  		list = append(list, fmt.Sprintf("%s (%v)", k.(string), highPrecisionTimeSince(v.(highPrecisionTime)).Round(time.Second)))
  2969  		return true
  2970  	})
  2971  	slices.Sort(list)
  2972  	return list
  2973  }
  2974  
  2975  // stopAlarm turns off the alarm.
  2976  func (m *M) stopAlarm() {
  2977  	if *timeout > 0 {
  2978  		m.timer.Stop()
  2979  	}
  2980  }
  2981  
  2982  func parseCpuList() {
  2983  	for val := range strings.SplitSeq(*cpuListStr, ",") {
  2984  		val = strings.TrimSpace(val)
  2985  		if val == "" {
  2986  			continue
  2987  		}
  2988  		cpu, err := strconv.Atoi(val)
  2989  		if err != nil || cpu <= 0 {
  2990  			fmt.Fprintf(os.Stderr, "testing: invalid value %q for -test.cpu\n", val)
  2991  			os.Exit(1)
  2992  		}
  2993  		cpuList = append(cpuList, cpu)
  2994  	}
  2995  	if cpuList == nil {
  2996  		cpuList = append(cpuList, runtime.GOMAXPROCS(-1))
  2997  	}
  2998  }
  2999  
  3000  func shouldFailFast() bool {
  3001  	return *failFast && numFailed.Load() > 0
  3002  }
  3003  

View as plain text