1// Copyright 2009 The Go Authors. All rights reserved.2// Use of this source code is governed by a BSD-style3// license that can be found in the LICENSE file.45// 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 automates7// execution of any function of the form8//9//	func TestXxx(*testing.T)10//11// where Xxx does not start with a lowercase letter. The function name12// 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 that17// 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 regular20// 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 unexported26// identifiers within the package, as in this example:27//28//	package abs29//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 tested40// must be imported explicitly and only its exported identifiers may be used.41// This is known as "black box" testing.42//43//	package abs_test44//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// # Benchmarks61//62// Functions of the form63//64//	func BenchmarkXxx(*testing.B)65//66// are considered benchmarks, and are executed by the "go test" command when67// 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 output80//81//	BenchmarkRandInt-8   	68453040	        17.8 ns/op82//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 expensive86// setup before calling b.Loop, which will not be counted toward the87// 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 use97// the RunParallel helper function; such benchmarks are intended to be used with98// 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.Buffer104//	        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 given112// in https://go.dev/design/14313-benchmark-format.113//114// There are standard tools for working with benchmark results at115// [golang.org/x/perf/cmd].116// In particular, [golang.org/x/perf/cmd/benchstat] performs117// statistically robust A/B comparisons.118//119// # b.N-style benchmarks120//121// Prior to the introduction of [B.Loop], benchmarks were written in a122// 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 run131// the target code b.N times. The benchmark function is called132// multiple times with b.N adjusted until the benchmark function133// lasts long enough to be timed reliably. This also means any setup134// done before the loop may be run several times.135//136// If a benchmark needs some expensive setup before running, the timer137// 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 robust148// and more efficient.149//150// # Examples151//152// The package also runs and verifies example code. Example functions may153// include a concluding line comment that begins with "Output:" and is compared with154// the standard output of the function when the tests are run. (The comparison155// ignores leading and trailing space.) These are examples of an example:156//157//	func ExampleHello() {158//	    fmt.Println("hello")159//	    // Output: hello160//	}161//162//	func ExampleSalutations() {163//	    fmt.Println("hello, and")164//	    fmt.Println("goodbye")165//	    // Output:166//	    // hello, and167//	    // goodbye168//	}169//170// The comment prefix "Unordered output:" is like "Output:", but matches any171// line order:172//173//	func ExamplePerm() {174//	    for _, value := range Perm(5) {175//	        fmt.Println(value)176//	    }177//	    // Unordered output: 4178//	    // 2179//	    // 1180//	    // 3181//	    // 0182//	}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 and187// 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 by195// appending a distinct suffix to the name. The suffix must start with a196// 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 single204// example function, at least one other function, type, variable, or constant205// declaration, and no test or benchmark functions.206//207// # Fuzzing208//209// 'go test' and the testing package support fuzzing, a testing technique where210// a function is called with randomly generated inputs to find bugs not211// anticipated by unit tests.212//213// Functions of the form214//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 by238// default, and can seed input generation. Seed inputs may be registered by239// 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 containing241// the fuzz test. Seed inputs are optional, but the fuzzing engine may find242// bugs more efficiently when provided with a set of small seed inputs with good243// code coverage. These seed inputs can also serve as regression tests for bugs244// identified through fuzzing.245//246// The function passed to [F.Fuzz] within the fuzz test is considered the fuzz247// target. A fuzz target must accept a [*T] parameter, followed by one or more248// parameters for random inputs. The types of arguments passed to [F.Add] must249// be identical to the types of these parameters. The fuzz target may signal250// that it's found a problem the same way tests do: by calling [T.Fail] (or any251// 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 expression254// that matches a specific fuzz test), the fuzz target is called with arguments255// generated by repeatedly making random changes to the seed inputs. On256// supported platforms, 'go test' compiles the test executable with fuzzing257// coverage instrumentation. The fuzzing engine uses that instrumentation to258// find and cache inputs that expand coverage, increasing the likelihood of259// finding bugs. If the fuzz target fails for a given input, the fuzzing engine260// writes the inputs that caused the failure to a file in the directory261// testdata/fuzz/<Name> within the package directory. This file later serves as262// 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 to264// the fuzz cache directory within the build cache instead.265//266// When fuzzing is disabled, the fuzz target is called with the seed inputs267// registered with [F.Add] and seed inputs from testdata/fuzz/<Name>. In this268// mode, the fuzz test acts much like a regular test, with subtests started269// with [F.Fuzz] instead of [T.Run].270//271// See https://go.dev/doc/fuzz for documentation about fuzzing.272//273// # Skipping274//275// Tests or benchmarks may be skipped at run time with a call to276// [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-benchmarks301//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 uses304// 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 name316// of the top-level test and the sequence of names passed to Run, separated by317// 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 regular320// expression that matches the test's name. For tests with multiple slash-separated321// elements, such as subtests, the argument is itself slash-separated, with322// expressions matching each name element in turn. Because it is unanchored, an323// 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 seed333// corpus, for debugging. For example:334//335//	go test -run=FuzzFoo/9ddb952d9814336//337// The -fuzz and -run flags can both be set, in order to fuzz a target but338// skip the execution of all other tests.339//340// Subtests can also be used to control parallelism. A parent test will only341// complete once all of its subtests complete. In this example, all tests are342// run in parallel with each other, and only with each other, regardless of343// 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 way355// 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// # Main368//369// It is sometimes necessary for a test or benchmark program to do extra setup or teardown370// before or after it executes. It is also sometimes necessary to control371// 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 benchmarks377// directly. TestMain runs in the main goroutine and can do whatever setup378// and teardown is necessary around a call to m.Run. m.Run will return an exit379// code that may be passed to [os.Exit]. If TestMain returns, the test wrapper380// 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 on383// command-line flags, including those of the testing package, it should call384// [flag.Parse] explicitly. Command line flags are always parsed by the time test385// 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 flags391//		m.Run()392//	}393//394// TestMain is a low-level primitive and should not be necessary for casual395// testing needs, where ordinary test functions suffice.396//397// [go help test]: https://pkg.go.dev/cmd/go#hdr-Test_packages398// [go help testflag]: https://pkg.go.dev/cmd/go#hdr-Testing_flags399package testing400401import (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 linkname424)425426var initRan bool427428var (429	parallelStart atomic.Int64 // number of parallel tests started430	parallelStop  atomic.Int64 // number of parallel tests stopped431)432433// Init registers testing flags. These flags are automatically registered by434// the "go test" command before running test functions, so Init is only needed435// 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.438func Init() {439	if initRan {440		return441	}442	initRan = true443	// The short flag requests that tests run more quickly, but its functionality444	// is provided by test writers themselves. The testing package is just its445	// home. The all.bash installation script sets it to make installation more446	// efficient, but by default the flag is off so a plain "go test" will do a447	// full test of the package.448	short = flag.Bool("test.short", false, "run smaller test suite to save time")449450	// 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")452453	// The directory in which to create profile files and the like. When run from454	// "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 where456	// 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")482483	initBenchmarkFlags()484	initFuzzFlags()485}486487var (488	// Flags, registered during Init.489	short                *bool490	failFast             *bool491	outputDir            *string492	artifacts            *bool493	chatty               chattyFlag494	count                *uint495	coverProfile         *string496	gocoverdir           *string497	matchList            *string498	match                *string499	skip                 *string500	memProfile           *string501	memProfileRate       *int502	cpuProfile           *string503	blockProfile         *string504	blockProfileRate     *int505	mutexProfile         *string506	mutexProfileFraction *int507	panicOnExit0         *bool508	traceFile            *string509	timeout              *time.Duration510	cpuListStr           *string511	parallel             *int512	shuffle              *string513	testlog              *string514	fullPath             *bool515516	haveExamples bool // are there examples?517518	cpuList     []int519	testlogFile *os.File520	artifactDir string521522	numFailed atomic.Uint32 // number of test failures523524	running sync.Map // map[string]time.Time of running, unpaused tests525)526527type chattyFlag struct {528	on   bool // -v is set in some form529	json bool // -v=test2json is set, to make output better for test2json530}531532func (*chattyFlag) IsBoolFlag() bool { return true }533534func (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 = true540		f.json = arg == "test2json"541	case "false":542		f.on = false543		f.json = false544	}545	return nil546}547548func (f *chattyFlag) String() string {549	if f.json {550		return "test2json"551	}552	if f.on {553		return "true"554	}555	return "false"556}557558func (f *chattyFlag) Get() any {559	if f.json {560		return "test2json"561	}562	return f.on563}564565const (566	markFraming  byte = 'V' &^ '@' // ^V: framing567	markErrBegin byte = 'O' &^ '@' // ^O: start of error568	markErrEnd   byte = 'N' &^ '@' // ^N: end of error569	markEscape   byte = '[' &^ '@' // ^[: escape570)571572func (f *chattyFlag) prefix() string {573	if f.json {574		return string(markFraming)575	}576	return ""577}578579type chattyPrinter struct {580	w          io.Writer581	lastNameMu sync.Mutex // guards lastName582	lastName   string     // last printed test name in chatty mode583	json       bool       // -v=json output mode584}585586func newChattyPrinter(w io.Writer) *chattyPrinter {587	return &chattyPrinter{w: w, json: chatty.json}588}589590// prefix is like chatty.prefix but using p.json instead of chatty.json.591// Using p.json allows tests to check the json behavior without modifying592// the global variable. For convenience, we allow p == nil and treat593// that as not in json mode (because it's not chatty at all).594func (p *chattyPrinter) prefix() string {595	if p != nil && p.json {596		return string(markFraming)597	}598	return ""599}600601// Updatef prints a message about the status of the named test to w.602//603// The formatted message must include the test name itself.604func (p *chattyPrinter) Updatef(testName, format string, args ...any) {605	p.lastNameMu.Lock()606	defer p.lastNameMu.Unlock()607608	// Since the message already implies an association with a specific new test,609	// we don't need to check what the old test name was or log an extra NAME line610	// for it. (We're updating it anyway, and the current message already includes611	// the test name.)612	p.lastName = testName613	fmt.Fprintf(p.w, p.prefix()+format, args...)614}615616// Printf prints a message, generated by the named test, that does not617// necessarily mention that tests's name itself.618func (p *chattyPrinter) Printf(testName, format string, args ...any) {619	p.lastNameMu.Lock()620	defer p.lastNameMu.Unlock()621622	if p.lastName == "" {623		p.lastName = testName624	} else if p.lastName != testName {625		fmt.Fprintf(p.w, "%s=== NAME  %s\n", p.prefix(), testName)626		p.lastName = testName627	}628629	fmt.Fprintf(p.w, format, args...)630}631632type stringWriter interface {633	io.Writer634	io.StringWriter635}636637// escapeWriter is a [io.Writer] that escapes test framing markers.638type escapeWriter struct {639	w stringWriter640}641642func (w escapeWriter) WriteString(s string) (int, error) {643	return w.Write([]byte(s))644}645646func (w escapeWriter) Write(p []byte) (int, error) {647	var n, m int648	var err error649	for len(p) > 0 {650		i := w.nextMark(p)651		if i < 0 {652			break653		}654655		m, err = w.w.Write(p[:i])656		n += m657		if err != nil {658			break659		}660661		m, err = w.w.Write([]byte{markEscape, p[i]})662		if err != nil {663			break664		}665		if m != 2 {666			return n, fmt.Errorf("short write")667		}668		n++669		p = p[i+1:]670	}671	m, err = w.w.Write(p)672	n += m673	return n, err674}675676func (escapeWriter) nextMark(p []byte) int {677	for i, b := range p {678		switch b {679		case markFraming, markErrBegin, markErrEnd, markEscape:680			return i681		}682	}683	return -1684}685686// The maximum number of stack frames to go through when skipping helper functions for687// the purpose of decorating log messages.688const maxStackLen = 50689690// common holds the elements common between T and B and691// captures common methods such as Errorf.692type common struct {693	mu          sync.RWMutex         // guards this group of fields694	output      []byte               // Output generated by test or benchmark.695	w           io.Writer            // For flushToParent.696	o           *outputWriter        // Writes output.697	ran         bool                 // Test or benchmark (or one of its subtests) was executed.698	failed      bool                 // Test or benchmark has failed.699	skipped     bool                 // Test or benchmark has been skipped.700	done        bool                 // Test is finished and all subtests have completed.701	helperPCs   map[uintptr]struct{} // functions to be skipped when writing file/line info702	helperNames map[string]struct{}  // helperPCs converted to function names703	cleanups    []func()             // optional functions to be called at the end of the test704	cleanupName string               // Name of the cleanup function.705	cleanupPc   []uintptr            // The stack trace at the point where Cleanup was called.706	finished    bool                 // Test function has completed.707	inFuzzFn    bool                 // Whether the fuzz target, if this is one, is running.708	isSynctest  bool709710	chatty         *chattyPrinter // A copy of chattyPrinter, if the chatty flag is set.711	bench          bool           // Whether the current test is a benchmark.712	hasSub         atomic.Bool    // whether there are sub-benchmarks.713	cleanupStarted atomic.Bool    // Registered cleanup callbacks have started to execute714	runner         string         // Function name of tRunner running the test.715	isParallel     bool           // Whether the test is parallel.716717	parent     *common718	level      int       // Nesting depth of test or benchmark.719	creator    []uintptr // If level > 0, the stack trace at the point where the parent called t.Run.720	modulePath string721	importPath string722	name       string            // Name of test or benchmark.723	start      highPrecisionTime // Time test or benchmark started724	duration   time.Duration725	barrier    chan bool // To signal parallel subtests they may start. Nil when T.Parallel is not present (B) or not usable (when fuzzing).726	signal     chan bool // To signal a test is done.727	sub        []*T      // Queue of subtests to be run in parallel.728729	lastRaceErrors  atomic.Int64 // Max value of race.Errors seen during the test or its subtests.730	raceErrorLogged atomic.Bool731732	tempDirMu  sync.Mutex733	tempDir    string734	tempDirErr error735	tempDirSeq int32736737	artifactDirOnce sync.Once738	artifactDir     string739	artifactDirErr  error740741	ctx       context.Context742	cancelCtx context.CancelFunc743}744745// Short reports whether the -test.short flag is set.746func Short() bool {747	if short == nil {748		panic("testing: Short called before Init")749	}750	// Catch code that calls this from TestMain without first calling flag.Parse.751	if !flag.Parsed() {752		panic("testing: Short called before Parse")753	}754755	return *short756}757758// testBinary is set by cmd/go to "1" if this is a binary built by "go test".759// The value is set to "1" by a -X option to cmd/link. We assume that760// because this is possible, the compiler will not optimize testBinary761// into a constant on the basis that it is an unexported package-scope762// variable that is never changed. If the compiler ever starts implementing763// such an optimization, we will need some technique to mark this variable764// as "changed by a cmd/link -X option".765var testBinary = "0"766767// Testing reports whether the current code is being run in a test.768// This will report true in programs created by "go test",769// false in programs created by "go build".770func Testing() bool {771	return testBinary == "1"772}773774// CoverMode reports what the test coverage mode is set to. The775// values are "set", "count", or "atomic". The return value will be776// empty if test coverage is not enabled.777func CoverMode() string {778	return cover.mode779}780781// Verbose reports whether the -test.v flag is set.782func Verbose() bool {783	// Same as in Short.784	if !flag.Parsed() {785		panic("testing: Verbose called before Parse")786	}787	return chatty.on788}789790func (c *common) checkFuzzFn(name string) {791	if c.inFuzzFn {792		panic(fmt.Sprintf("testing: f.%s was called inside the fuzz target, use t.%s instead", name, name))793	}794}795796// frameSkip searches, starting after skip frames, for the first caller frame797// in a function not marked as a helper and returns that frame.798// The search stops if it finds a tRunner function that799// was the entry point into the test and the test is not a subtest.800// This function must be called with c.mu held.801func (c *common) frameSkip(skip int) runtime.Frame {802	// If the search continues into the parent test, we'll have to hold803	// its mu temporarily. If we then return, we need to unlock it.804	shouldUnlock := false805	defer func() {806		if shouldUnlock {807			c.mu.Unlock()808		}809	}()810	var pc [maxStackLen]uintptr811	// Skip two extra frames to account for this function812	// and runtime.Callers itself.813	n := runtime.Callers(skip+2, pc[:])814	if n == 0 {815		panic("testing: zero callers found")816	}817	frames := runtime.CallersFrames(pc[:n])818	var firstFrame, prevFrame, frame runtime.Frame819	skipRange := false820	for more := true; more; prevFrame = frame {821		frame, more = frames.Next()822		if skipRange {823			// Skip the iterator function when a helper824			// functions does a range over function.825			skipRange = false826			continue827		}828		if frame.Function == "runtime.gopanic" {829			continue830		}831		if frame.Function == c.cleanupName {832			frames = runtime.CallersFrames(c.cleanupPc)833			continue834		}835		if firstFrame.PC == 0 {836			firstFrame = frame837		}838		if frame.Function == c.runner {839			// We've gone up all the way to the tRunner calling840			// the test function (so the user must have841			// called tb.Helper from inside that test function).842			// If this is a top-level test, only skip up to the test function itself.843			// If we're in a subtest, continue searching in the parent test,844			// starting from the point of the call to Run which created this subtest.845			if c.level > 1 {846				frames = runtime.CallersFrames(c.creator)847				parent := c.parent848				// We're no longer looking at the current c after this point,849				// so we should unlock its mu, unless it's the original receiver,850				// in which case our caller doesn't expect us to do that.851				if shouldUnlock {852					c.mu.Unlock()853				}854				c = parent855				// Remember to unlock c.mu when we no longer need it, either856				// because we went up another nesting level, or because we857				// returned.858				shouldUnlock = true859				c.mu.Lock()860				continue861			}862			return prevFrame863		}864		// If more helper PCs have been added since we last did the conversion865		if c.helperNames == nil {866			c.helperNames = make(map[string]struct{})867			for pc := range c.helperPCs {868				c.helperNames[pcToName(pc)] = struct{}{}869			}870		}871872		fnName := frame.Function873		// Ignore trailing -rangeN used for iterator functions.874		const rangeSuffix = "-range"875		if suffixIdx := strings.LastIndex(fnName, rangeSuffix); suffixIdx > 0 {876			ok := true877			for i := suffixIdx + len(rangeSuffix); i < len(fnName); i++ {878				if fnName[i] < '0' || fnName[i] > '9' {879					ok = false880					break881				}882			}883			if ok {884				fnName = fnName[:suffixIdx]885				skipRange = true886			}887		}888889		if _, ok := c.helperNames[fnName]; !ok {890			// Found a frame that wasn't inside a helper function.891			return frame892		}893	}894	return firstFrame895}896897// flushToParent writes c.output to the parent after first writing the header898// with the given format and arguments.899func (c *common) flushToParent(testName, format string, args ...any) {900	p := c.parent901	p.mu.Lock()902	defer p.mu.Unlock()903904	c.mu.Lock()905	defer c.mu.Unlock()906907	if len(c.output) > 0 {908		// Add the current c.output to the print,909		// and then arrange for the print to replace c.output.910		// (This displays the logged output after the --- FAIL line.)911		format += "%s"912		args = append(args[:len(args):len(args)], c.output)913		c.output = c.output[:0]914	}915916	if c.chatty != nil && (p.w == c.chatty.w || c.chatty.json) {917		// We're flushing to the actual output, so track that this output is918		// associated with a specific test (and, specifically, that the next output919		// is *not* associated with that test).920		//921		// Moreover, if c.output is non-empty it is important that this write be922		// atomic with respect to the output of other tests, so that we don't end up923		// with confusing '=== NAME' lines in the middle of our '--- PASS' block.924		// Neither humans nor cmd/test2json can parse those easily.925		// (See https://go.dev/issue/40771.)926		//927		// If test2json is used, we never flush to parent tests,928		// so that the json stream shows subtests as they finish.929		// (See https://go.dev/issue/29811.)930		c.chatty.Updatef(testName, format, args...)931	} else {932		// We're flushing to the output buffer of the parent test, which will933		// itself follow a test-name header when it is finally flushed to stdout.934		fmt.Fprintf(p.w, c.chatty.prefix()+format, args...)935	}936}937938type indenter struct {939	c *common940}941942const indent = "    "943944func (w indenter) Write(b []byte) (n int, err error) {945	n = len(b)946	for len(b) > 0 {947		end := bytes.IndexByte(b, '\n')948		if end == -1 {949			end = len(b)950		} else {951			end++952		}953		// An indent of 4 spaces will neatly align the dashes with the status954		// indicator of the parent.955		line := b[:end]956		if line[0] == markFraming {957			w.c.output = append(w.c.output, markFraming)958			line = line[1:]959		}960		w.c.output = append(w.c.output, indent...)961		w.c.output = append(w.c.output, line...)962		b = b[end:]963	}964	return965}966967// fmtDuration returns a string representing d in the form "87.00s".968func fmtDuration(d time.Duration) string {969	return fmt.Sprintf("%.2fs", d.Seconds())970}971972// TB is the interface common to [T], [B], and [F].973type TB interface {974	ArtifactDir() string975	Attr(key, value string)976	Cleanup(func())977	Error(args ...any)978	Errorf(format string, args ...any)979	Fail()980	FailNow()981	Failed() bool982	Fatal(args ...any)983	Fatalf(format string, args ...any)984	Helper()985	Log(args ...any)986	Logf(format string, args ...any)987	Name() string988	Setenv(key, value string)989	Chdir(dir string)990	Skip(args ...any)991	SkipNow()992	Skipf(format string, args ...any)993	Skipped() bool994	TempDir() string995	Context() context.Context996	Output() io.Writer997998	// A private method to prevent users implementing the999	// interface and so future additions to it will not1000	// violate Go 1 compatibility.1001	private()1002}10031004var (1005	_ TB = (*T)(nil)1006	_ TB = (*B)(nil)1007)10081009// T is a type passed to Test functions to manage test state and support formatted test logs.1010//1011// A test ends when its Test function returns or calls any of the methods1012// [T.FailNow], [T.Fatal], [T.Fatalf], [T.SkipNow], [T.Skip], or [T.Skipf]. Those methods, as well as1013// the [T.Parallel] method, must be called only from the goroutine running the1014// Test function.1015//1016// The other reporting methods, such as the variations of [T.Log] and [T.Error],1017// may be called simultaneously from multiple goroutines.1018type T struct {1019	common1020	denyParallel bool1021	tstate       *testState // For running tests and subtests.1022}10231024func (c *common) private() {}10251026// Name returns the name of the running (sub-) test or benchmark.1027//1028// The name will include the name of the test along with the names of1029// any nested sub-tests. If two sibling sub-tests have the same name,1030// Name will append a suffix to guarantee the returned name is unique.1031func (c *common) Name() string {1032	return c.name1033}10341035func (c *common) setRan() {1036	if c.parent != nil {1037		c.parent.setRan()1038	}1039	c.mu.Lock()1040	defer c.mu.Unlock()1041	c.ran = true1042}10431044// Fail marks the function as having failed but continues execution.1045func (c *common) Fail() {1046	if c.parent != nil {1047		c.parent.Fail()1048	}1049	c.mu.Lock()1050	defer c.mu.Unlock()1051	// c.done needs to be locked to synchronize checks to c.done in parent tests.1052	if c.done {1053		panic("Fail in goroutine after " + c.name + " has completed")1054	}1055	c.failed = true1056}10571058// Failed reports whether the function has failed.1059func (c *common) Failed() bool {1060	c.mu.RLock()1061	defer c.mu.RUnlock()10621063	if !c.done && int64(race.Errors()) > c.lastRaceErrors.Load() {1064		c.mu.RUnlock()1065		c.checkRaces()1066		c.mu.RLock()1067	}10681069	return c.failed1070}10711072// FailNow marks the function as having failed and stops its execution1073// by calling [runtime.Goexit] (which then runs all deferred calls in the1074// current goroutine).1075// Execution will continue at the next test or benchmark.1076// FailNow must be called from the goroutine running the1077// test or benchmark function, not from other goroutines1078// created during the test. Calling FailNow does not stop1079// those other goroutines.1080func (c *common) FailNow() {1081	c.checkFuzzFn("FailNow")1082	c.Fail()10831084	// Calling runtime.Goexit will exit the goroutine, which1085	// will run the deferred functions in this goroutine,1086	// which will eventually run the deferred lines in tRunner,1087	// which will signal to the test loop that this test is done.1088	//1089	// A previous version of this code said:1090	//1091	//	c.duration = ...1092	//	c.signal <- c.self1093	//	runtime.Goexit()1094	//1095	// This previous version duplicated code (those lines are in1096	// tRunner no matter what), but worse the goroutine teardown1097	// implicit in runtime.Goexit was not guaranteed to complete1098	// before the test exited. If a test deferred an important cleanup1099	// function (like removing temporary files), there was no guarantee1100	// it would run on a test failure. Because we send on c.signal during1101	// a top-of-stack deferred function now, we know that the send1102	// only happens after any other stacked defers have completed.1103	c.mu.Lock()1104	c.finished = true1105	c.mu.Unlock()1106	runtime.Goexit()1107}11081109// log generates the output. It is always at the same stack depth. log inserts1110// indentation and the final newline if necessary. It prefixes the string1111// with the file and line of the call site.1112func (c *common) log(s string, isErr bool) {1113	s = strings.TrimSuffix(s, "\n")11141115	// Second and subsequent lines are indented 4 spaces. This is in addition to1116	// the indentation provided by outputWriter.1117	s = strings.ReplaceAll(s, "\n", "\n"+indent)1118	s += "\n"11191120	n := c.destination()1121	if n == nil {1122		// The test and all its parents are done. The log cannot be output.1123		panic("Log in goroutine after " + c.name + " has completed: " + s)1124	}11251126	// Prefix with the call site. It is located by skipping 3 functions:1127	// callSite + log + public function1128	s = n.callSite(3) + s11291130	// Output buffered logs.1131	n.flushPartial()11321133	n.o.write([]byte(s), isErr)1134}11351136// destination selects the test to which output should be appended. It returns the1137// test if it is incomplete. Otherwise, it finds its closest incomplete parent.1138func (c *common) destination() *common {1139	c.mu.Lock()1140	defer c.mu.Unlock()11411142	if !c.done && !c.isSynctest {1143		return c1144	}1145	for parent := c.parent; parent != nil; parent = parent.parent {1146		parent.mu.Lock()1147		defer parent.mu.Unlock()1148		if !parent.done {1149			return parent1150		}1151	}1152	return nil1153}11541155// callSite retrieves and formats the file and line of the call site.1156func (c *common) callSite(skip int) string {1157	c.mu.Lock()1158	defer c.mu.Unlock()11591160	frame := c.frameSkip(skip)1161	file := frame.File1162	line := frame.Line1163	if file != "" {1164		if *fullPath {1165			// If relative path, truncate file name at last file name separator.1166		} else {1167			file = filepath.Base(file)1168		}1169	} else {1170		file = "???"1171	}1172	if line == 0 {1173		line = 11174	}11751176	return fmt.Sprintf("%s:%d: ", file, line)1177}11781179// flushPartial checks the buffer for partial logs and outputs them.1180func (c *common) flushPartial() {1181	partial := func() bool {1182		c.mu.Lock()1183		defer c.mu.Unlock()1184		return (c.o != nil) && (len(c.o.partial) > 0)1185	}11861187	if partial() {1188		c.o.Write([]byte("\n"))1189	}1190}11911192// Output returns a Writer that writes to the same test output stream as TB.Log.1193// The output is indented like TB.Log lines, but Output does not1194// add source locations or newlines. The output is internally line1195// buffered, and a call to TB.Log or the end of the test will implicitly1196// flush the buffer, followed by a newline. After a test function and all its1197// parents return, neither Output nor the Write method may be called.1198func (c *common) Output() io.Writer {1199	c.checkFuzzFn("Output")1200	n := c.destination()1201	if n == nil {1202		panic("Output called after " + c.name + " has completed")1203	}1204	return n.o1205}12061207// setOutputWriter initializes an outputWriter and sets it as a common field.1208func (c *common) setOutputWriter() {1209	c.o = &outputWriter{c: c}1210}12111212// outputWriter buffers, formats and writes log messages.1213type outputWriter struct {1214	c       *common1215	partial []byte // incomplete ('\n'-free) suffix of last Write1216}12171218// Write writes a log message to the test's output stream, properly formatted and1219// indented. It may not be called after a test function and all its parents return.1220func (o *outputWriter) Write(p []byte) (int, error) {1221	return o.write(p, false)1222}12231224func (o *outputWriter) write(p []byte, isErr bool) (int, error) {1225	// o can be nil if this is called from a top-level *TB that is no longer active.1226	// Just ignore the message in that case.1227	if o == nil || o.c == nil {1228		return 0, nil1229	}1230	if o.c.destination() == nil {1231		panic("Write called after " + o.c.name + " has completed")1232	}12331234	o.c.mu.Lock()1235	defer o.c.mu.Unlock()12361237	// The last element is a partial line.1238	lines := bytes.SplitAfter(p, []byte("\n"))1239	last := len(lines) - 1 // Inv: 0 <= last1240	for i, line := range lines[:last] {1241		// Emit partial line from previous call.1242		if i == 0 && len(o.partial) > 0 {1243			line = slices.Concat(o.partial, line)1244			o.partial = o.partial[:0]1245		}1246		o.writeLine(line, isErr && i == 0, isErr && i == last-1)1247	}1248	// Save partial line for next call.1249	o.partial = append(o.partial, lines[last]...)12501251	return len(p), nil1252}12531254// writeLine generates the output for a given line.1255func (o *outputWriter) writeLine(b []byte, errBegin, errEnd bool) {1256	if o.c.done || (o.c.chatty == nil) {1257		o.c.output = append(o.c.output, indent...)1258		o.c.output = append(o.c.output, b...)1259		return1260	}12611262	// Escape the framing marker.1263	b = escapeMarkers(b)12641265	// If this is the start of an error, add ^O to the start of the output.1266	var strErrBegin, strErrEnd string1267	if errBegin && o.c.chatty.json {1268		strErrBegin = string(markErrBegin)1269	}12701271	// If this is the end of an error, add ^N to the end of the output. If the1272	// last character of the output is \n, add ^N before the \n, otherwise1273	// test2json will not handle it correctly.1274	var c []byte1275	if errEnd && o.c.chatty.json {1276		i := len(b)1277		if len(b) > 0 && b[i-1] == '\n' {1278			b, c = b[:i-1], b[i-1:]1279		}1280		strErrEnd = string(markErrEnd)1281	}12821283	if o.c.bench {1284		// Benchmarks don't print === CONT, so we should skip the test1285		// printer and just print straight to stdout.1286		fmt.Printf("%s%s%s%s%s", strErrBegin, indent, b, strErrEnd, c)1287	} else {1288		o.c.chatty.Printf(o.c.name, "%s%s%s%s%s", strErrBegin, indent, b, strErrEnd, c)1289	}1290}12911292func escapeMarkers(b []byte) []byte {1293	j := nextMark(b)1294	if j < 0 {1295		// Allocation-free fast path.1296		return b1297	}12981299	c := make([]byte, 0, len(b)+10)1300	i := 01301	for i < len(b) && j >= i {1302		if j > i {1303			c = append(c, b[i:j]...)1304		}1305		c = append(c, markEscape, b[j])1306		i = j + 11307		j = i + nextMark(b[i:])1308	}1309	if i < len(b) {1310		c = append(c, b[i:]...)1311	}1312	return c1313}13141315func nextMark(b []byte) int {1316	for i, b := range b {1317		switch b {1318		case markFraming, markEscape, markErrBegin, markErrEnd:1319			return i1320		}1321	}1322	return -11323}13241325// Log formats its arguments using default formatting, analogous to [fmt.Println],1326// and records the text in the error log. For tests, the text will be printed only if1327// the test fails or the -test.v flag is set. For benchmarks, the text is always1328// printed to avoid having performance depend on the value of the -test.v flag.1329// It is an error to call Log after a test or benchmark returns.1330func (c *common) Log(args ...any) {1331	c.checkFuzzFn("Log")1332	c.log(fmt.Sprintln(args...), false)1333}13341335// Logf formats its arguments according to the format, analogous to [fmt.Printf], and1336// records the text in the error log. A final newline is added if not provided. For1337// tests, the text will be printed only if the test fails or the -test.v flag is1338// set. For benchmarks, the text is always printed to avoid having performance1339// depend on the value of the -test.v flag.1340// It is an error to call Logf after a test or benchmark returns.1341func (c *common) Logf(format string, args ...any) {1342	c.checkFuzzFn("Logf")1343	c.log(fmt.Sprintf(format, args...), false)1344}13451346// Error is equivalent to Log followed by Fail.1347func (c *common) Error(args ...any) {1348	c.checkFuzzFn("Error")1349	c.log(fmt.Sprintln(args...), true)1350	c.Fail()1351}13521353// Errorf is equivalent to Logf followed by Fail.1354func (c *common) Errorf(format string, args ...any) {1355	c.checkFuzzFn("Errorf")1356	c.log(fmt.Sprintf(format, args...), true)1357	c.Fail()1358}13591360// Fatal is equivalent to Log followed by FailNow.1361func (c *common) Fatal(args ...any) {1362	c.checkFuzzFn("Fatal")1363	c.log(fmt.Sprintln(args...), true)1364	c.FailNow()1365}13661367// Fatalf is equivalent to Logf followed by FailNow.1368func (c *common) Fatalf(format string, args ...any) {1369	c.checkFuzzFn("Fatalf")1370	c.log(fmt.Sprintf(format, args...), true)1371	c.FailNow()1372}13731374// Skip is equivalent to Log followed by SkipNow.1375func (c *common) Skip(args ...any) {1376	c.checkFuzzFn("Skip")1377	c.log(fmt.Sprintln(args...), false)1378	c.SkipNow()1379}13801381// Skipf is equivalent to Logf followed by SkipNow.1382func (c *common) Skipf(format string, args ...any) {1383	c.checkFuzzFn("Skipf")1384	c.log(fmt.Sprintf(format, args...), false)1385	c.SkipNow()1386}13871388// SkipNow marks the test as having been skipped and stops its execution1389// by calling [runtime.Goexit].1390// If a test fails (see Error, Errorf, Fail) and is then skipped,1391// it is still considered to have failed.1392// Execution will continue at the next test or benchmark. See also FailNow.1393// SkipNow must be called from the goroutine running the test, not from1394// other goroutines created during the test. Calling SkipNow does not stop1395// those other goroutines.1396func (c *common) SkipNow() {1397	c.checkFuzzFn("SkipNow")1398	c.mu.Lock()1399	c.skipped = true1400	c.finished = true1401	c.mu.Unlock()1402	runtime.Goexit()1403}14041405// Skipped reports whether the test was skipped.1406func (c *common) Skipped() bool {1407	c.mu.RLock()1408	defer c.mu.RUnlock()1409	return c.skipped1410}14111412// Helper marks the calling function as a test helper function.1413// When printing file and line information, that function will be skipped.1414// Helper may be called simultaneously from multiple goroutines.1415func (c *common) Helper() {1416	if c.isSynctest {1417		c = c.parent1418	}1419	c.mu.Lock()1420	defer c.mu.Unlock()1421	if c.helperPCs == nil {1422		c.helperPCs = make(map[uintptr]struct{})1423	}1424	// repeating code from callerName here to save walking a stack frame1425	var pc [1]uintptr1426	n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper1427	if n == 0 {1428		panic("testing: zero callers found")1429	}1430	if _, found := c.helperPCs[pc[0]]; !found {1431		c.helperPCs[pc[0]] = struct{}{}1432		c.helperNames = nil // map will be recreated next time it is needed1433	}1434}14351436// Cleanup registers a function to be called when the test (or subtest) and all its1437// subtests complete. Cleanup functions will be called in last added,1438// first called order.1439func (c *common) Cleanup(f func()) {1440	c.checkFuzzFn("Cleanup")1441	var pc [maxStackLen]uintptr1442	// Skip two extra frames to account for this function and runtime.Callers itself.1443	n := runtime.Callers(2, pc[:])1444	cleanupPc := pc[:n]14451446	fn := func() {1447		defer func() {1448			c.mu.Lock()1449			defer c.mu.Unlock()1450			c.cleanupName = ""1451			c.cleanupPc = nil1452		}()14531454		name := callerName(0)1455		c.mu.Lock()1456		c.cleanupName = name1457		c.cleanupPc = cleanupPc1458		c.mu.Unlock()14591460		f()1461	}14621463	c.mu.Lock()1464	defer c.mu.Unlock()1465	c.cleanups = append(c.cleanups, fn)1466}14671468// ArtifactDir returns a directory in which the test should store output files.1469// When the -artifacts flag is provided, this directory is located1470// under the output directory. Otherwise, ArtifactDir returns a temporary directory1471// that is removed after the test completes.1472//1473// Each test or subtest within each test package has a unique artifact directory.1474// Repeated calls to ArtifactDir in the same test or subtest return the same directory.1475// Subtest outputs are not located under the parent test's output directory.1476func (c *common) ArtifactDir() string {1477	c.checkFuzzFn("ArtifactDir")1478	c.artifactDirOnce.Do(func() {1479		c.artifactDir, c.artifactDirErr = c.makeArtifactDir()1480	})1481	if c.artifactDirErr != nil {1482		c.Fatalf("ArtifactDir: %v", c.artifactDirErr)1483	}1484	return c.artifactDir1485}14861487func hashString(s string) (h uint64) {1488	// FNV, used here to avoid a dependency on maphash.1489	for i := 0; i < len(s); i++ {1490		h ^= uint64(s[i])1491		h *= 10995116282111492	}1493	return1494}14951496// makeArtifactDir creates the artifact directory for a test.1497// The artifact directory is:1498//1499//	<output dir>/_artifacts/<test package>/<test name>/<random>1500//1501// The test package is the package import path with the module name prefix removed.1502// The test name is truncated if too long.1503// Special characters are removed from the path.1504func (c *common) makeArtifactDir() (string, error) {1505	if !*artifacts {1506		return c.makeTempDir()1507	}15081509	artifactBase := filepath.Join(artifactDir, c.relativeArtifactBase())1510	if err := os.MkdirAll(artifactBase, 0o777); err != nil {1511		return "", err1512	}1513	dir, err := os.MkdirTemp(artifactBase, "")1514	if err != nil {1515		return "", err1516	}1517	if c.chatty != nil {1518		c.chatty.Updatef(c.name, "=== ARTIFACTS %s %v\n", c.name, dir)1519	}1520	return dir, nil1521}15221523func (c *common) relativeArtifactBase() string {1524	// If the test name is longer than maxNameSize, truncate it and replace the last1525	// hashSize bytes with a hash of the full name.1526	const maxNameSize = 641527	name := strings.ReplaceAll(c.name, "/", "__")1528	if len(name) > maxNameSize {1529		h := fmt.Sprintf("%0x", hashString(name))1530		name = name[:maxNameSize-len(h)] + h1531	}15321533	// Remove the module path prefix from the import path.1534	// If this is the root package, pkg will be empty.1535	pkg := strings.TrimPrefix(c.importPath, c.modulePath)1536	// Remove the leading slash.1537	pkg = strings.TrimPrefix(pkg, "/")15381539	base := name1540	if pkg != "" {1541		// Join with /, not filepath.Join: the import path is /-separated,1542		// and we don't want removeSymbolsExcept to strip \ separators on Windows.1543		base = pkg + "/" + name1544	}1545	base = removeSymbolsExcept(base, "!#$%&()+,-.=@^_{}~ /")1546	base, err := filepath.Localize(base)1547	if err != nil {1548		// This name can't be safely converted into a local filepath.1549		// Drop it and just use _artifacts/<random>.1550		base = ""1551	}15521553	return base1554}15551556func removeSymbolsExcept(s, allowed string) string {1557	mapper := func(r rune) rune {1558		if unicode.IsLetter(r) ||1559			unicode.IsNumber(r) ||1560			strings.ContainsRune(allowed, r) {1561			return r1562		}1563		return -1 // disallowed symbol1564	}1565	return strings.Map(mapper, s)1566}15671568// TempDir returns a temporary directory for the test to use.1569// The directory is automatically removed when the test and1570// all its subtests complete.1571// Each subsequent call to TempDir returns a unique directory;1572// if the directory creation fails, TempDir terminates the test by calling Fatal.1573// If the environment variable GOTMPDIR is set, the temporary directory will1574// be created somewhere beneath it.1575func (c *common) TempDir() string {1576	c.checkFuzzFn("TempDir")1577	dir, err := c.makeTempDir()1578	if err != nil {1579		c.Fatalf("TempDir: %v", err)1580	}1581	return dir1582}15831584func (c *common) makeTempDir() (string, error) {1585	// Use a single parent directory for all the temporary directories1586	// created by a test, each numbered sequentially.1587	c.tempDirMu.Lock()1588	var nonExistent bool1589	if c.tempDir == "" { // Usually the case with js/wasm1590		nonExistent = true1591	} else {1592		_, err := os.Stat(c.tempDir)1593		nonExistent = os.IsNotExist(err)1594		if err != nil && !nonExistent {1595			return "", err1596		}1597	}15981599	if nonExistent {1600		c.Helper()16011602		pattern := c.Name()1603		// Limit length of file names on disk.1604		// Invalid runes from slicing are dropped by strings.Map below.1605		pattern = pattern[:min(len(pattern), 64)]16061607		// Drop unusual characters (such as path separators or1608		// characters interacting with globs) from the directory name to1609		// avoid surprising os.MkdirTemp behavior.1610		const allowed = "!#$%&()+,-.=@^_{}~ "1611		pattern = removeSymbolsExcept(pattern, allowed)16121613		c.tempDir, c.tempDirErr = os.MkdirTemp(os.Getenv("GOTMPDIR"), pattern)1614		if c.tempDirErr == nil {1615			c.Cleanup(func() {1616				if err := removeAll(c.tempDir); err != nil {1617					c.Errorf("TempDir RemoveAll cleanup: %v", err)1618				}1619			})1620		}1621	}16221623	if c.tempDirErr == nil {1624		c.tempDirSeq++1625	}1626	seq := c.tempDirSeq1627	c.tempDirMu.Unlock()16281629	if c.tempDirErr != nil {1630		return "", c.tempDirErr1631	}16321633	dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)1634	if err := os.Mkdir(dir, 0o777); err != nil {1635		return "", err1636	}1637	return dir, nil1638}16391640// removeAll is like os.RemoveAll, but retries Windows "Access is denied."1641// errors up to an arbitrary timeout.1642//1643// Those errors have been known to occur spuriously on at least the1644// windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur1645// legitimately if the test leaves behind a temp file that either is still open1646// or the test otherwise lacks permission to delete. In the case of legitimate1647// failures, a failing test may take a bit longer to fail, but once the test is1648// fixed the extra latency will go away.1649func removeAll(path string) error {1650	const arbitraryTimeout = 2 * time.Second1651	var (1652		start     time.Time1653		nextSleep = 1 * time.Millisecond1654	)1655	for {1656		err := os.RemoveAll(path)1657		if !isWindowsRetryable(err) {1658			return err1659		}1660		if start.IsZero() {1661			start = time.Now()1662		} else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {1663			return err1664		}1665		time.Sleep(nextSleep)1666		nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))1667	}1668}16691670// Setenv calls [os.Setenv] and uses Cleanup to1671// restore the environment variable to its original value1672// after the test.1673//1674// Because Setenv affects the whole process, it cannot be used1675// in parallel tests or tests with parallel ancestors.1676func (c *common) Setenv(key, value string) {1677	c.checkFuzzFn("Setenv")1678	prevValue, ok := os.LookupEnv(key)16791680	if err := os.Setenv(key, value); err != nil {1681		c.Fatalf("cannot set environment variable: %v", err)1682	}16831684	if ok {1685		c.Cleanup(func() {1686			os.Setenv(key, prevValue)1687		})1688	} else {1689		c.Cleanup(func() {1690			os.Unsetenv(key)1691		})1692	}1693}16941695// Chdir calls [os.Chdir] and uses Cleanup to restore the current1696// working directory to its original value after the test. On Unix, it1697// also sets PWD environment variable for the duration of the test.1698//1699// Because Chdir affects the whole process, it cannot be used1700// in parallel tests or tests with parallel ancestors.1701func (c *common) Chdir(dir string) {1702	c.checkFuzzFn("Chdir")1703	oldwd, err := os.Open(".")1704	if err != nil {1705		c.Fatal(err)1706	}1707	if err := os.Chdir(dir); err != nil {1708		c.Fatal(err)1709	}1710	// On POSIX platforms, PWD represents “an absolute pathname of the1711	// current working directory.” Since we are changing the working1712	// directory, we should also set or update PWD to reflect that.1713	switch runtime.GOOS {1714	case "windows", "plan9":1715		// Windows and Plan 9 do not use the PWD variable.1716	default:1717		if !filepath.IsAbs(dir) {1718			dir, err = os.Getwd()1719			if err != nil {1720				c.Fatal(err)1721			}1722		}1723		c.Setenv("PWD", dir)1724	}1725	c.Cleanup(func() {1726		err := oldwd.Chdir()1727		oldwd.Close()1728		if err != nil {1729			// It's not safe to continue with tests if we can't1730			// get back to the original working directory. Since1731			// we are holding a dirfd, this is highly unlikely.1732			panic("testing.Chdir: " + err.Error())1733		}1734	})1735}17361737// Context returns a context that is canceled just before1738// Cleanup-registered functions are called.1739//1740// Cleanup functions can wait for any resources1741// that shut down on [context.Context.Done] before the test or benchmark completes.1742func (c *common) Context() context.Context {1743	c.checkFuzzFn("Context")1744	return c.ctx1745}17461747// Attr emits a test attribute associated with this test.1748//1749// The key must not contain whitespace.1750// The value must not contain newlines or carriage returns.1751//1752// The meaning of different attribute keys is left up to1753// continuous integration systems and test frameworks.1754//1755// Test attributes are emitted immediately in the test log,1756// but they are intended to be treated as unordered.1757func (c *common) Attr(key, value string) {1758	if strings.ContainsFunc(key, unicode.IsSpace) {1759		c.Errorf("disallowed whitespace in attribute key %q", key)1760		return1761	}1762	if strings.ContainsAny(value, "\r\n") {1763		c.Errorf("disallowed newline in attribute value %q", value)1764		return1765	}1766	if c.chatty == nil {1767		return1768	}1769	c.chatty.Updatef(c.name, "=== ATTR  %s %v %v\n", c.name, key, value)1770}17711772// panicHandling controls the panic handling used by runCleanup.1773type panicHandling int17741775const (1776	normalPanic panicHandling = iota1777	recoverAndReturnPanic1778)17791780// runCleanup is called at the end of the test.1781// If ph is recoverAndReturnPanic, it will catch panics, and return the1782// recovered value if any.1783func (c *common) runCleanup(ph panicHandling) (panicVal any) {1784	c.cleanupStarted.Store(true)1785	defer c.cleanupStarted.Store(false)17861787	if ph == recoverAndReturnPanic {1788		defer func() {1789			panicVal = recover()1790		}()1791	}17921793	// Make sure that if a cleanup function panics,1794	// we still run the remaining cleanup functions.1795	defer func() {1796		c.mu.Lock()1797		recur := len(c.cleanups) > 01798		c.mu.Unlock()1799		if recur {1800			c.runCleanup(normalPanic)1801		}1802	}()18031804	if c.cancelCtx != nil {1805		c.cancelCtx()1806	}18071808	for {1809		var cleanup func()1810		c.mu.Lock()1811		if len(c.cleanups) > 0 {1812			last := len(c.cleanups) - 11813			cleanup = c.cleanups[last]1814			c.cleanups = c.cleanups[:last]1815		}1816		c.mu.Unlock()1817		if cleanup == nil {1818			return nil1819		}1820		cleanup()1821	}1822}18231824// resetRaces updates c.parent's count of data race errors (or the global count,1825// if c has no parent), and updates c.lastRaceErrors to match.1826//1827// Any races that occurred prior to this call to resetRaces will1828// not be attributed to c.1829func (c *common) resetRaces() {1830	if c.parent == nil {1831		c.lastRaceErrors.Store(int64(race.Errors()))1832	} else {1833		c.lastRaceErrors.Store(c.parent.checkRaces())1834	}1835}18361837// checkRaces checks whether the global count of data race errors has increased1838// since c's count was last reset.1839//1840// If so, it marks c as having failed due to those races (logging an error for1841// the first such race), and updates the race counts for the parents of c so1842// that if they are currently suspended (such as in a call to T.Run) they will1843// not log separate errors for the race(s).1844//1845// Note that multiple tests may be marked as failed due to the same race if they1846// are executing in parallel.1847func (c *common) checkRaces() (raceErrors int64) {1848	raceErrors = int64(race.Errors())1849	for {1850		last := c.lastRaceErrors.Load()1851		if raceErrors <= last {1852			// All races have already been reported.1853			return raceErrors1854		}1855		if c.lastRaceErrors.CompareAndSwap(last, raceErrors) {1856			break1857		}1858	}18591860	if c.raceErrorLogged.CompareAndSwap(false, true) {1861		// This is the first race we've encountered for this test.1862		// Mark the test as failed, and log the reason why only once.1863		// (Note that the race detector itself will still write a goroutine1864		// dump for any further races it detects.)1865		c.Errorf("race detected during execution of test")1866	}18671868	// Update the parent(s) of this test so that they don't re-report the race.1869	parent := c.parent1870	for parent != nil {1871		for {1872			last := parent.lastRaceErrors.Load()1873			if raceErrors <= last {1874				// This race was already reported by another (likely parallel) subtest.1875				return raceErrors1876			}1877			if parent.lastRaceErrors.CompareAndSwap(last, raceErrors) {1878				break1879			}1880		}1881		parent = parent.parent1882	}18831884	return raceErrors1885}18861887// callerName gives the function name (qualified with a package path)1888// for the caller after skip frames (where 0 means the current function).1889func callerName(skip int) string {1890	var pc [1]uintptr1891	n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName1892	if n == 0 {1893		panic("testing: zero callers found")1894	}1895	return pcToName(pc[0])1896}18971898func pcToName(pc uintptr) string {1899	pcs := []uintptr{pc}1900	frames := runtime.CallersFrames(pcs)1901	frame, _ := frames.Next()1902	return frame.Function1903}19041905const parallelConflict = `testing: test using t.Setenv, t.Chdir, or cryptotest.SetGlobalRandom can not use t.Parallel`19061907// Parallel signals that this test is to be run in parallel with (and only with)1908// other parallel tests, and pauses until all non-parallel tests have finished.1909//1910// When a test is run multiple times due to use of -test.count or -test.cpu,1911// multiple instances of a single test never run in parallel with each other.1912func (t *T) Parallel() {1913	if t.isParallel {1914		panic("testing: t.Parallel called multiple times")1915	}1916	if t.isSynctest {1917		panic("testing: t.Parallel called inside synctest bubble")1918	}1919	if t.denyParallel {1920		panic(parallelConflict)1921	}1922	if t.parent.barrier == nil {1923		// T.Parallel has no effect when fuzzing.1924		// Multiple processes may run in parallel, but only one input can run at a1925		// time per process so we can attribute crashes to specific inputs.1926		return1927	}19281929	t.isParallel = true19301931	// We don't want to include the time we spend waiting for serial tests1932	// in the test duration. Record the elapsed time thus far and reset the1933	// timer afterwards.1934	t.duration += highPrecisionTimeSince(t.start)19351936	// Add to the list of tests to be released by the parent.1937	t.parent.sub = append(t.parent.sub, t)19381939	// Report any races during execution of this test up to this point.1940	//1941	// We will assume that any races that occur between here and the point where1942	// we unblock are not caused by this subtest. That assumption usually holds,1943	// although it can be wrong if the test spawns a goroutine that races in the1944	// background while the rest of the test is blocked on the call to Parallel.1945	// If that happens, we will misattribute the background race to some other1946	// test, or to no test at all — but that false-negative is so unlikely that it1947	// is not worth adding race-report noise for the common case where the test is1948	// completely suspended during the call to Parallel.1949	t.checkRaces()19501951	if t.chatty != nil {1952		t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)1953	}1954	running.Delete(t.name)19551956	t.signal <- true   // Release calling test.1957	<-t.parent.barrier // Wait for the parent test to complete.1958	t.tstate.waitParallel()1959	parallelStart.Add(1)19601961	if t.chatty != nil {1962		t.chatty.Updatef(t.name, "=== CONT  %s\n", t.name)1963	}1964	running.Store(t.name, highPrecisionTimeNow())1965	t.start = highPrecisionTimeNow()19661967	// Reset the local race counter to ignore any races that happened while this1968	// goroutine was blocked, such as in the parent test or in other parallel1969	// subtests.1970	//1971	// (Note that we don't call parent.checkRaces here:1972	// if other parallel subtests have already introduced races, we want to1973	// let them report those races instead of attributing them to the parent.)1974	t.lastRaceErrors.Store(int64(race.Errors()))1975}19761977// checkParallel is called by [testing/cryptotest.SetGlobalRandom].1978//1979//go:linkname checkParallel testing.checkParallel1980func checkParallel(t *T) {1981	t.checkParallel()1982}19831984func (t *T) checkParallel() {1985	// Non-parallel subtests that have parallel ancestors may still1986	// run in parallel with other tests: they are only non-parallel1987	// with respect to the other subtests of the same parent.1988	// Since calls like SetEnv or Chdir affects the whole process, we need1989	// to deny those if the current test or any parent is parallel.1990	for c := &t.common; c != nil; c = c.parent {1991		if c.isParallel {1992			panic(parallelConflict)1993		}1994	}19951996	t.denyParallel = true1997}19981999// Setenv calls os.Setenv(key, value) and uses Cleanup to2000// restore the environment variable to its original value