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

View as plain text