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, if non-empty, is the operation (such as "t.Setenv") that1021	// forbids a later call to t.Parallel.1022	denyParallel string1023	tstate       *testState // For running tests and subtests.1024}10251026func (c *common) private() {}10271028// Name returns the name of the running (sub-) test or benchmark.1029//1030// The name will include the name of the test along with the names of1031// any nested sub-tests. If two sibling sub-tests have the same name,1032// Name will append a suffix to guarantee the returned name is unique.1033func (c *common) Name() string {1034	return c.name1035}10361037func (c *common) setRan() {1038	if c.parent != nil {1039		c.parent.setRan()1040	}1041	c.mu.Lock()1042	defer c.mu.Unlock()1043	c.ran = true1044}10451046// Fail marks the function as having failed but continues execution.1047func (c *common) Fail() {1048	if c.parent != nil {1049		c.parent.Fail()1050	}1051	c.mu.Lock()1052	defer c.mu.Unlock()1053	// c.done needs to be locked to synchronize checks to c.done in parent tests.1054	if c.done {1055		panic("Fail in goroutine after " + c.name + " has completed")1056	}1057	c.failed = true1058}10591060// Failed reports whether the function has failed.1061func (c *common) Failed() bool {1062	c.mu.RLock()1063	defer c.mu.RUnlock()10641065	if !c.done && int64(race.Errors()) > c.lastRaceErrors.Load() {1066		c.mu.RUnlock()1067		c.checkRaces()1068		c.mu.RLock()1069	}10701071	return c.failed1072}10731074// FailNow marks the function as having failed and stops its execution1075// by calling [runtime.Goexit] (which then runs all deferred calls in the1076// current goroutine).1077// Execution will continue at the next test or benchmark.1078// FailNow must be called from the goroutine running the1079// test or benchmark function, not from other goroutines1080// created during the test. Calling FailNow does not stop1081// those other goroutines.1082func (c *common) FailNow() {1083	c.checkFuzzFn("FailNow")1084	c.Fail()10851086	// Calling runtime.Goexit will exit the goroutine, which1087	// will run the deferred functions in this goroutine,1088	// which will eventually run the deferred lines in tRunner,1089	// which will signal to the test loop that this test is done.1090	//1091	// A previous version of this code said:1092	//1093	//	c.duration = ...1094	//	c.signal <- c.self1095	//	runtime.Goexit()1096	//1097	// This previous version duplicated code (those lines are in1098	// tRunner no matter what), but worse the goroutine teardown1099	// implicit in runtime.Goexit was not guaranteed to complete1100	// before the test exited. If a test deferred an important cleanup1101	// function (like removing temporary files), there was no guarantee1102	// it would run on a test failure. Because we send on c.signal during1103	// a top-of-stack deferred function now, we know that the send1104	// only happens after any other stacked defers have completed.1105	c.mu.Lock()1106	c.finished = true1107	c.mu.Unlock()1108	runtime.Goexit()1109}11101111// log generates the output. It is always at the same stack depth. log inserts1112// indentation and the final newline if necessary. It prefixes the string1113// with the file and line of the call site.1114func (c *common) log(s string, isErr bool) {1115	s = strings.TrimSuffix(s, "\n")11161117	// Second and subsequent lines are indented 4 spaces. This is in addition to1118	// the indentation provided by outputWriter.1119	s = strings.ReplaceAll(s, "\n", "\n"+indent)1120	s += "\n"11211122	n := c.destination()1123	if n == nil {1124		// The test and all its parents are done. The log cannot be output.1125		panic("Log in goroutine after " + c.name + " has completed: " + s)1126	}11271128	// Prefix with the call site. It is located by skipping 3 functions:1129	// callSite + log + public function1130	s = n.callSite(3) + s11311132	// Output buffered logs.1133	n.flushPartial()11341135	n.o.write([]byte(s), isErr)1136}11371138// destination selects the test to which output should be appended. It returns the1139// test if it is incomplete. Otherwise, it finds its closest incomplete parent.1140func (c *common) destination() *common {1141	c.mu.Lock()1142	defer c.mu.Unlock()11431144	if !c.done && !c.isSynctest {1145		return c1146	}1147	for parent := c.parent; parent != nil; parent = parent.parent {1148		parent.mu.Lock()1149		defer parent.mu.Unlock()1150		if !parent.done {1151			return parent1152		}1153	}1154	return nil1155}11561157// callSite retrieves and formats the file and line of the call site.1158func (c *common) callSite(skip int) string {1159	c.mu.Lock()1160	defer c.mu.Unlock()11611162	frame := c.frameSkip(skip)1163	file := frame.File1164	line := frame.Line1165	if file != "" {1166		if *fullPath {1167			// If relative path, truncate file name at last file name separator.1168		} else {1169			file = filepath.Base(file)1170		}1171	} else {1172		file = "???"1173	}1174	if line == 0 {1175		line = 11176	}11771178	return fmt.Sprintf("%s:%d: ", file, line)1179}11801181// flushPartial checks the buffer for partial logs and outputs them.1182func (c *common) flushPartial() {1183	partial := func() bool {1184		c.mu.Lock()1185		defer c.mu.Unlock()1186		return (c.o != nil) && (len(c.o.partial) > 0)1187	}11881189	if partial() {1190		c.o.Write([]byte("\n"))1191	}1192}11931194// Output returns a Writer that writes to the same test output stream as TB.Log.1195// The output is indented like TB.Log lines, but Output does not1196// add source locations or newlines. The output is internally line1197// buffered, and a call to TB.Log or the end of the test will implicitly1198// flush the buffer, followed by a newline. After a test function and all its1199// parents return, neither Output nor the Write method may be called.1200func (c *common) Output() io.Writer {1201	c.checkFuzzFn("Output")1202	n := c.destination()1203	if n == nil {1204		panic("Output called after " + c.name + " has completed")1205	}1206	return n.o1207}12081209// setOutputWriter initializes an outputWriter and sets it as a common field.1210func (c *common) setOutputWriter() {1211	c.o = &outputWriter{c: c}1212}12131214// outputWriter buffers, formats and writes log messages.1215type outputWriter struct {1216	c       *common1217	partial []byte // incomplete ('\n'-free) suffix of last Write1218}12191220// Write writes a log message to the test's output stream, properly formatted and1221// indented. It may not be called after a test function and all its parents return.1222func (o *outputWriter) Write(p []byte) (int, error) {1223	return o.write(p, false)1224}12251226func (o *outputWriter) write(p []byte, isErr bool) (int, error) {1227	// o can be nil if this is called from a top-level *TB that is no longer active.1228	// Just ignore the message in that case.1229	if o == nil || o.c == nil {1230		return 0, nil1231	}1232	if o.c.destination() == nil {1233		panic("Write called after " + o.c.name + " has completed")1234	}12351236	o.c.mu.Lock()1237	defer o.c.mu.Unlock()12381239	// The last element is a partial line.1240	lines := bytes.SplitAfter(p, []byte("\n"))1241	last := len(lines) - 1 // Inv: 0 <= last1242	for i, line := range lines[:last] {1243		// Emit partial line from previous call.1244		if i == 0 && len(o.partial) > 0 {1245			line = slices.Concat(o.partial, line)1246			o.partial = o.partial[:0]1247		}1248		o.writeLine(line, isErr && i == 0, isErr && i == last-1)1249	}1250	// Save partial line for next call.1251	o.partial = append(o.partial, lines[last]...)12521253	return len(p), nil1254}12551256// writeLine generates the output for a given line.1257func (o *outputWriter) writeLine(b []byte, errBegin, errEnd bool) {1258	if o.c.done || (o.c.chatty == nil) {1259		o.c.output = append(o.c.output, indent...)1260		o.c.output = append(o.c.output, b...)1261		return1262	}12631264	// Escape the framing marker.1265	b = escapeMarkers(b)12661267	// If this is the start of an error, add ^O to the start of the output.1268	var strErrBegin, strErrEnd string1269	if errBegin && o.c.chatty.json {1270		strErrBegin = string(markErrBegin)1271	}12721273	// If this is the end of an error, add ^N to the end of the output. If the1274	// last character of the output is \n, add ^N before the \n, otherwise1275	// test2json will not handle it correctly.1276	var c []byte1277	if errEnd && o.c.chatty.json {1278		i := len(b)1279		if len(b) > 0 && b[i-1] == '\n' {1280			b, c = b[:i-1], b[i-1:]1281		}1282		strErrEnd = string(markErrEnd)1283	}12841285	if o.c.bench {1286		// Benchmarks don't print === CONT, so we should skip the test1287		// printer and just print straight to stdout.1288		fmt.Printf("%s%s%s%s%s", strErrBegin, indent, b, strErrEnd, c)1289	} else {1290		o.c.chatty.Printf(o.c.name, "%s%s%s%s%s", strErrBegin, indent, b, strErrEnd, c)1291	}1292}12931294func escapeMarkers(b []byte) []byte {1295	j := nextMark(b)1296	if j < 0 {1297		// Allocation-free fast path.1298		return b1299	}13001301	c := make([]byte, 0, len(b)+10)1302	i := 01303	for i < len(b) && j >= i {1304		if j > i {1305			c = append(c, b[i:j]...)1306		}1307		c = append(c, markEscape, b[j])1308		i = j + 11309		j = i + nextMark(b[i:])1310	}1311	if i < len(b) {1312		c = append(c, b[i:]...)1313	}1314	return c1315}13161317func nextMark(b []byte) int {1318	for i, b := range b {1319		switch b {1320		case markFraming, markEscape, markErrBegin, markErrEnd:1321			return i1322		}1323	}1324	return -11325}13261327// Log formats its arguments using default formatting, analogous to [fmt.Println],1328// and records the text in the error log. For tests, the text will be printed only if1329// the test fails or the -test.v flag is set. For benchmarks, the text is always1330// printed to avoid having performance depend on the value of the -test.v flag.1331// It is an error to call Log after a test or benchmark returns.1332func (c *common) Log(args ...any) {1333	c.checkFuzzFn("Log")1334	c.log(fmt.Sprintln(args...), false)1335}13361337// Logf formats its arguments according to the format, analogous to [fmt.Printf], and1338// records the text in the error log. A final newline is added if not provided. For1339// tests, the text will be printed only if the test fails or the -test.v flag is1340// set. For benchmarks, the text is always printed to avoid having performance1341// depend on the value of the -test.v flag.1342// It is an error to call Logf after a test or benchmark returns.1343func (c *common) Logf(format string, args ...any) {1344	c.checkFuzzFn("Logf")1345	c.log(fmt.Sprintf(format, args...), false)1346}13471348// Error is equivalent to Log followed by Fail.1349func (c *common) Error(args ...any) {1350	c.checkFuzzFn("Error")1351	c.log(fmt.Sprintln(args...), true)1352	c.Fail()1353}13541355// Errorf is equivalent to Logf followed by Fail.1356func (c *common) Errorf(format string, args ...any) {1357	c.checkFuzzFn("Errorf")1358	c.log(fmt.Sprintf(format, args...), true)1359	c.Fail()1360}13611362// Fatal is equivalent to Log followed by FailNow.1363func (c *common) Fatal(args ...any) {1364	c.checkFuzzFn("Fatal")1365	c.log(fmt.Sprintln(args...), true)1366	c.FailNow()1367}13681369// Fatalf is equivalent to Logf followed by FailNow.1370func (c *common) Fatalf(format string, args ...any) {1371	c.checkFuzzFn("Fatalf")1372	c.log(fmt.Sprintf(format, args...), true)1373	c.FailNow()1374}13751376// Skip is equivalent to Log followed by SkipNow.1377func (c *common) Skip(args ...any) {1378	c.checkFuzzFn("Skip")1379	c.log(fmt.Sprintln(args...), false)1380	c.SkipNow()1381}13821383// Skipf is equivalent to Logf followed by SkipNow.1384func (c *common) Skipf(format string, args ...any) {1385	c.checkFuzzFn("Skipf")1386	c.log(fmt.Sprintf(format, args...), false)1387	c.SkipNow()1388}13891390// SkipNow marks the test as having been skipped and stops its execution1391// by calling [runtime.Goexit].1392// If a test fails (see Error, Errorf, Fail) and is then skipped,1393// it is still considered to have failed.1394// Execution will continue at the next test or benchmark. See also FailNow.1395// SkipNow must be called from the goroutine running the test, not from1396// other goroutines created during the test. Calling SkipNow does not stop1397// those other goroutines.1398func (c *common) SkipNow() {1399	c.checkFuzzFn("SkipNow")1400	c.mu.Lock()1401	c.skipped = true1402	c.finished = true1403	c.mu.Unlock()1404	runtime.Goexit()1405}14061407// Skipped reports whether the test was skipped.1408func (c *common) Skipped() bool {1409	c.mu.RLock()1410	defer c.mu.RUnlock()1411	return c.skipped1412}14131414// Helper marks the calling function as a test helper function.1415// When printing file and line information, that function will be skipped.1416// Helper may be called simultaneously from multiple goroutines.1417func (c *common) Helper() {1418	if c.isSynctest {1419		c = c.parent1420	}1421	c.mu.Lock()1422	defer c.mu.Unlock()1423	if c.helperPCs == nil {1424		c.helperPCs = make(map[uintptr]struct{})1425	}1426	// repeating code from callerName here to save walking a stack frame1427	var pc [1]uintptr1428	n := runtime.Callers(2, pc[:]) // skip runtime.Callers + Helper1429	if n == 0 {1430		panic("testing: zero callers found")1431	}1432	if _, found := c.helperPCs[pc[0]]; !found {1433		c.helperPCs[pc[0]] = struct{}{}1434		c.helperNames = nil // map will be recreated next time it is needed1435	}1436}14371438// Cleanup registers a function to be called when the test (or subtest) and all its1439// subtests complete. Cleanup functions will be called in last added,1440// first called order.1441func (c *common) Cleanup(f func()) {1442	c.checkFuzzFn("Cleanup")1443	var pc [maxStackLen]uintptr1444	// Skip two extra frames to account for this function and runtime.Callers itself.1445	n := runtime.Callers(2, pc[:])1446	cleanupPc := pc[:n]14471448	fn := func() {1449		defer func() {1450			c.mu.Lock()1451			defer c.mu.Unlock()1452			c.cleanupName = ""1453			c.cleanupPc = nil1454		}()14551456		name := callerName(0)1457		c.mu.Lock()1458		c.cleanupName = name1459		c.cleanupPc = cleanupPc1460		c.mu.Unlock()14611462		f()1463	}14641465	c.mu.Lock()1466	defer c.mu.Unlock()1467	c.cleanups = append(c.cleanups, fn)1468}14691470// ArtifactDir returns a directory in which the test should store output files.1471// When the -artifacts flag is provided, this directory is located1472// under the output directory. Otherwise, ArtifactDir returns a temporary directory1473// that is removed after the test completes.1474//1475// Each test or subtest within each test package has a unique artifact directory.1476// Repeated calls to ArtifactDir in the same test or subtest return the same directory.1477// Subtest outputs are not located under the parent test's output directory.1478func (c *common) ArtifactDir() string {1479	c.checkFuzzFn("ArtifactDir")1480	c.artifactDirOnce.Do(func() {1481		c.artifactDir, c.artifactDirErr = c.makeArtifactDir()1482	})1483	if c.artifactDirErr != nil {1484		c.Fatalf("ArtifactDir: %v", c.artifactDirErr)1485	}1486	return c.artifactDir1487}14881489func hashString(s string) (h uint64) {1490	// FNV, used here to avoid a dependency on maphash.1491	for i := 0; i < len(s); i++ {1492		h ^= uint64(s[i])1493		h *= 10995116282111494	}1495	return1496}14971498// makeArtifactDir creates the artifact directory for a test.1499// The artifact directory is:1500//1501//	<output dir>/_artifacts/<test package>/<test name>/<random>1502//1503// The test package is the package import path with the module name prefix removed.1504// The test name is truncated if too long.1505// Special characters are removed from the path.1506func (c *common) makeArtifactDir() (string, error) {1507	if !*artifacts {1508		return c.makeTempDir()1509	}15101511	artifactBase := filepath.Join(artifactDir, c.relativeArtifactBase())1512	if err := os.MkdirAll(artifactBase, 0o777); err != nil {1513		return "", err1514	}1515	dir, err := os.MkdirTemp(artifactBase, "")1516	if err != nil {1517		return "", err1518	}1519	if c.chatty != nil {1520		c.chatty.Updatef(c.name, "=== ARTIFACTS %s %v\n", c.name, dir)1521	}1522	return dir, nil1523}15241525func (c *common) relativeArtifactBase() string {1526	// If the test name is longer than maxNameSize, truncate it and replace the last1527	// hashSize bytes with a hash of the full name.1528	const maxNameSize = 641529	name := strings.ReplaceAll(c.name, "/", "__")1530	if len(name) > maxNameSize {1531		h := fmt.Sprintf("%0x", hashString(name))1532		name = name[:maxNameSize-len(h)] + h1533	}15341535	// Remove the module path prefix from the import path.1536	// If this is the root package, pkg will be empty.1537	pkg := strings.TrimPrefix(c.importPath, c.modulePath)1538	// Remove the leading slash.1539	pkg = strings.TrimPrefix(pkg, "/")15401541	base := name1542	if pkg != "" {1543		// Join with /, not filepath.Join: the import path is /-separated,1544		// and we don't want removeSymbolsExcept to strip \ separators on Windows.1545		base = pkg + "/" + name1546	}1547	base = removeSymbolsExcept(base, "!#$%&()+,-.=@^_{}~ /")1548	base, err := filepath.Localize(base)1549	if err != nil {1550		// This name can't be safely converted into a local filepath.1551		// Drop it and just use _artifacts/<random>.1552		base = ""1553	}15541555	return base1556}15571558func removeSymbolsExcept(s, allowed string) string {1559	mapper := func(r rune) rune {1560		if unicode.IsLetter(r) ||1561			unicode.IsNumber(r) ||1562			strings.ContainsRune(allowed, r) {1563			return r1564		}1565		return -1 // disallowed symbol1566	}1567	return strings.Map(mapper, s)1568}15691570// TempDir returns a temporary directory for the test to use.1571// The directory is automatically removed when the test and1572// all its subtests complete.1573// Each subsequent call to TempDir returns a unique directory;1574// if the directory creation fails, TempDir terminates the test by calling Fatal.1575// If the environment variable GOTMPDIR is set, the temporary directory will1576// be created somewhere beneath it.1577func (c *common) TempDir() string {1578	c.checkFuzzFn("TempDir")1579	dir, err := c.makeTempDir()1580	if err != nil {1581		c.Fatalf("TempDir: %v", err)1582	}1583	return dir1584}15851586func (c *common) makeTempDir() (string, error) {1587	// Use a single parent directory for all the temporary directories1588	// created by a test, each numbered sequentially.1589	c.tempDirMu.Lock()1590	var nonExistent bool1591	if c.tempDir == "" { // Usually the case with js/wasm1592		nonExistent = true1593	} else {1594		_, err := os.Stat(c.tempDir)1595		nonExistent = os.IsNotExist(err)1596		if err != nil && !nonExistent {1597			return "", err1598		}1599	}16001601	if nonExistent {1602		c.Helper()16031604		pattern := c.Name()1605		// Limit length of file names on disk.1606		// Invalid runes from slicing are dropped by strings.Map below.1607		pattern = pattern[:min(len(pattern), 64)]16081609		// Drop unusual characters (such as path separators or1610		// characters interacting with globs) from the directory name to1611		// avoid surprising os.MkdirTemp behavior.1612		const allowed = "!#$%&()+,-.=@^_{}~ "1613		pattern = removeSymbolsExcept(pattern, allowed)16141615		c.tempDir, c.tempDirErr = os.MkdirTemp(os.Getenv("GOTMPDIR"), pattern)1616		if c.tempDirErr == nil {1617			c.Cleanup(func() {1618				if err := removeAll(c.tempDir); err != nil {1619					c.Errorf("TempDir RemoveAll cleanup: %v", err)1620				}1621			})1622		}1623	}16241625	if c.tempDirErr == nil {1626		c.tempDirSeq++1627	}1628	seq := c.tempDirSeq1629	c.tempDirMu.Unlock()16301631	if c.tempDirErr != nil {1632		return "", c.tempDirErr1633	}16341635	dir := fmt.Sprintf("%s%c%03d", c.tempDir, os.PathSeparator, seq)1636	if err := os.Mkdir(dir, 0o777); err != nil {1637		return "", err1638	}1639	return dir, nil1640}16411642// removeAll is like os.RemoveAll, but retries Windows "Access is denied."1643// errors up to an arbitrary timeout.1644//1645// Those errors have been known to occur spuriously on at least the1646// windows-amd64-2012 builder (https://go.dev/issue/50051), and can only occur1647// legitimately if the test leaves behind a temp file that either is still open1648// or the test otherwise lacks permission to delete. In the case of legitimate1649// failures, a failing test may take a bit longer to fail, but once the test is1650// fixed the extra latency will go away.1651func removeAll(path string) error {1652	const arbitraryTimeout = 2 * time.Second1653	var (1654		start     time.Time1655		nextSleep = 1 * time.Millisecond1656	)1657	for {1658		err := os.RemoveAll(path)1659		if !isWindowsRetryable(err) {1660			return err1661		}1662		if start.IsZero() {1663			start = time.Now()1664		} else if d := time.Since(start) + nextSleep; d >= arbitraryTimeout {1665			return err1666		}1667		time.Sleep(nextSleep)1668		nextSleep += time.Duration(rand.Int63n(int64(nextSleep)))1669	}1670}16711672// Setenv calls [os.Setenv] and uses Cleanup to1673// restore the environment variable to its original value1674// after the test.1675//1676// Because Setenv affects the whole process, it cannot be used1677// in parallel tests or tests with parallel ancestors.1678func (c *common) Setenv(key, value string) {1679	c.checkFuzzFn("Setenv")1680	prevValue, ok := os.LookupEnv(key)16811682	if err := os.Setenv(key, value); err != nil {1683		c.Fatalf("cannot set environment variable: %v", err)1684	}16851686	if ok {1687		c.Cleanup(func() {1688			os.Setenv(key, prevValue)1689		})1690	} else {1691		c.Cleanup(func() {1692			os.Unsetenv(key)1693		})1694	}1695}16961697// Chdir calls [os.Chdir] and uses Cleanup to restore the current1698// working directory to its original value after the test. On Unix, it1699// also sets PWD environment variable for the duration of the test.1700//1701// Because Chdir affects the whole process, it cannot be used1702// in parallel tests or tests with parallel ancestors.1703func (c *common) Chdir(dir string) {1704	c.checkFuzzFn("Chdir")1705	oldwd, err := os.Open(".")1706	if err != nil {1707		c.Fatal(err)1708	}1709	if err := os.Chdir(dir); err != nil {1710		c.Fatal(err)1711	}1712	// On POSIX platforms, PWD represents “an absolute pathname of the1713	// current working directory.” Since we are changing the working1714	// directory, we should also set or update PWD to reflect that.1715	switch runtime.GOOS {1716	case "windows", "plan9":1717		// Windows and Plan 9 do not use the PWD variable.1718	default:1719		if !filepath.IsAbs(dir) {1720			dir, err = os.Getwd()1721			if err != nil {1722				c.Fatal(err)1723			}1724		}1725		c.Setenv("PWD", dir)1726	}1727	c.Cleanup(func() {1728		err := oldwd.Chdir()1729		oldwd.Close()1730		if err != nil {1731			// It's not safe to continue with tests if we can't1732			// get back to the original working directory. Since1733			// we are holding a dirfd, this is highly unlikely.1734			panic("testing.Chdir: " + err.Error())1735		}1736	})1737}17381739// Context returns a context that is canceled just before1740// Cleanup-registered functions are called.1741//1742// Cleanup functions can wait for any resources1743// that shut down on [context.Context.Done] before the test or benchmark completes.1744func (c *common) Context() context.Context {1745	c.checkFuzzFn("Context")1746	return c.ctx1747}17481749// Attr emits a test attribute associated with this test.1750//1751// The key must not contain whitespace.1752// The value must not contain newlines or carriage returns.1753//1754// The meaning of different attribute keys is left up to1755// continuous integration systems and test frameworks.1756//1757// Test attributes are emitted immediately in the test log,1758// but they are intended to be treated as unordered.1759func (c *common) Attr(key, value string) {1760	if strings.ContainsFunc(key, unicode.IsSpace) {1761		c.Errorf("disallowed whitespace in attribute key %q", key)1762		return1763	}1764	if strings.ContainsAny(value, "\r\n") {1765		c.Errorf("disallowed newline in attribute value %q", value)1766		return1767	}1768	if c.chatty == nil {1769		return1770	}1771	c.chatty.Updatef(c.name, "=== ATTR  %s %v %v\n", c.name, key, value)1772}17731774// panicHandling controls the panic handling used by runCleanup.1775type panicHandling int17761777const (1778	normalPanic panicHandling = iota1779	recoverAndReturnPanic1780)17811782// runCleanup is called at the end of the test.1783// If ph is recoverAndReturnPanic, it will catch panics, and return the1784// recovered value if any.1785func (c *common) runCleanup(ph panicHandling) (panicVal any) {1786	c.cleanupStarted.Store(true)1787	defer c.cleanupStarted.Store(false)17881789	if ph == recoverAndReturnPanic {1790		defer func() {1791			panicVal = recover()1792		}()1793	}17941795	// Make sure that if a cleanup function panics,1796	// we still run the remaining cleanup functions.1797	defer func() {1798		c.mu.Lock()1799		recur := len(c.cleanups) > 01800		c.mu.Unlock()1801		if recur {1802			c.runCleanup(normalPanic)1803		}1804	}()18051806	if c.cancelCtx != nil {1807		c.cancelCtx()1808	}18091810	for {1811		var cleanup func()1812		c.mu.Lock()1813		if len(c.cleanups) > 0 {1814			last := len(c.cleanups) - 11815			cleanup = c.cleanups[last]1816			c.cleanups = c.cleanups[:last]1817		}1818		c.mu.Unlock()1819		if cleanup == nil {1820			return nil1821		}1822		cleanup()1823	}1824}18251826// resetRaces updates c.parent's count of data race errors (or the global count,1827// if c has no parent), and updates c.lastRaceErrors to match.1828//1829// Any races that occurred prior to this call to resetRaces will1830// not be attributed to c.1831func (c *common) resetRaces() {1832	if c.parent == nil {1833		c.lastRaceErrors.Store(int64(race.Errors()))1834	} else {1835		c.lastRaceErrors.Store(c.parent.checkRaces())1836	}1837}18381839// checkRaces checks whether the global count of data race errors has increased1840// since c's count was last reset.1841//1842// If so, it marks c as having failed due to those races (logging an error for1843// the first such race), and updates the race counts for the parents of c so1844// that if they are currently suspended (such as in a call to T.Run) they will1845// not log separate errors for the race(s).1846//1847// Note that multiple tests may be marked as failed due to the same race if they1848// are executing in parallel.1849func (c *common) checkRaces() (raceErrors int64) {1850	raceErrors = int64(race.Errors())1851	for {1852		last := c.lastRaceErrors.Load()1853		if raceErrors <= last {1854			// All races have already been reported.1855			return raceErrors1856		}1857		if c.lastRaceErrors.CompareAndSwap(last, raceErrors) {1858			break1859		}1860	}18611862	if c.raceErrorLogged.CompareAndSwap(false, true) {1863		// This is the first race we've encountered for this test.1864		// Mark the test as failed, and log the reason why only once.1865		// (Note that the race detector itself will still write a goroutine1866		// dump for any further races it detects.)1867		c.Errorf("race detected during execution of test")1868	}18691870	// Update the parent(s) of this test so that they don't re-report the race.1871	parent := c.parent1872	for parent != nil {1873		for {1874			last := parent.lastRaceErrors.Load()1875			if raceErrors <= last {1876				// This race was already reported by another (likely parallel) subtest.1877				return raceErrors1878			}1879			if parent.lastRaceErrors.CompareAndSwap(last, raceErrors) {1880				break1881			}1882		}1883		parent = parent.parent1884	}18851886	return raceErrors1887}18881889// callerName gives the function name (qualified with a package path)1890// for the caller after skip frames (where 0 means the current function).1891func callerName(skip int) string {1892	var pc [1]uintptr1893	n := runtime.Callers(skip+2, pc[:]) // skip + runtime.Callers + callerName1894	if n == 0 {1895		panic("testing: zero callers found")1896	}1897	return pcToName(pc[0])1898}18991900func pcToName(pc uintptr) string {1901	pcs := []uintptr{pc}1902	frames := runtime.CallersFrames(pcs)1903	frame, _ := frames.Next()1904	return frame.Function1905}19061907// parallelConflict returns the panic message for a conflict between t.Parallel1908// and op, the operation that cannot be combined with a parallel test: one of1909// "t.Setenv", "t.Chdir", or "cryptotest.SetGlobalRandom".1910func parallelConflict(op string) string {1911	return "testing: test using " + op + " can not use t.Parallel"1912}19131914// Parallel signals that this test is to be run in parallel with (and only with)1915// other parallel tests, and pauses until all non-parallel tests have finished.1916//1917// When a test is run multiple times due to use of -test.count or -test.cpu,1918// multiple instances of a single test never run in parallel with each other.1919func (t *T) Parallel() {1920	if t.isParallel {1921		panic("testing: t.Parallel called multiple times")1922	}1923	if t.isSynctest {1924		panic("testing: t.Parallel called inside synctest bubble")1925	}1926	if t.denyParallel != "" {1927		panic(parallelConflict(t.denyParallel))1928	}1929	if t.parent.barrier == nil {1930		// T.Parallel has no effect when fuzzing.1931		// Multiple processes may run in parallel, but only one input can run at a1932		// time per process so we can attribute crashes to specific inputs.1933		return1934	}19351936	t.isParallel = true19371938	// We don't want to include the time we spend waiting for serial tests1939	// in the test duration. Record the elapsed time thus far and reset the1940	// timer afterwards.1941	t.duration += highPrecisionTimeSince(t.start)19421943	// Add to the list of tests to be released by the parent.1944	t.parent.sub = append(t.parent.sub, t)19451946	// Report any races during execution of this test up to this point.1947	//1948	// We will assume that any races that occur between here and the point where1949	// we unblock are not caused by this subtest. That assumption usually holds,1950	// although it can be wrong if the test spawns a goroutine that races in the1951	// background while the rest of the test is blocked on the call to Parallel.1952	// If that happens, we will misattribute the background race to some other1953	// test, or to no test at all — but that false-negative is so unlikely that it1954	// is not worth adding race-report noise for the common case where the test is1955	// completely suspended during the call to Parallel.1956	t.checkRaces()19571958	if t.chatty != nil {1959		t.chatty.Updatef(t.name, "=== PAUSE %s\n", t.name)1960	}1961	running.Delete(t.name)19621963	t.signal <- true   // Release calling test.1964	<-t.parent.barrier // Wait for the parent test to complete.1965	t.tstate.waitParallel()1966	parallelStart.Add(1)19671968	if t.chatty != nil {1969		t.chatty.Updatef(t.name, "=== CONT  %s\n", t.name)1970	}1971	running.Store(t.name, highPrecisionTimeNow())1972	t.start = highPrecisionTimeNow()19731974	// Reset the local race counter to ignore any races that happened while this1975	// goroutine was blocked, such as in the parent test or in other parallel1976	// subtests.1977	//1978	// (Note that we don't call parent.checkRaces here:1979	// if other parallel subtests have already introduced races, we want to1980	// let them report those races instead of attributing them to the parent.)1981	t.lastRaceErrors.Store(int64(race.Errors()))1982}19831984// checkParallel is called by [testing/cryptotest.SetGlobalRandom].1985//1986//go:linkname checkParallel testing.checkParallel1987func checkParallel(t *T) {1988	t.checkParallel("cryptotest.SetGlobalRandom")1989}19901991func (t *T) checkParallel(op string) {1992	// Non-parallel subtests that have parallel ancestors may still1993	// run in parallel with other tests: they are only non-parallel1994	// with respect to the other subtests of the same parent.1995	// Since calls like SetEnv or Chdir affects the whole process, we need1996	// to deny those if the current test or any parent is parallel.1997	for c := &t.common; c != nil; c = c.parent {1998		if c.isParallel {1999			panic(parallelConflict(op))2000		}