Source file src/testing/testing.go

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

View as plain text