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

View as plain text