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

View as plain text