Authoring and Fixtures

A _test.go file declaring package foo compiles into the package itself and can use its unexported identifiers. One declaring package foo_test compiles as a separate package that must import foo and sees only its exported API.

The go command ignores directories named testdata when matching package patterns, so nothing inside is compiled or vetted. A test binary runs with its own package directory as the working directory, so a relative path like testdata/user.go.golden always resolves.

t.TempDir() returns the path of a fresh, empty directory created for that test. The testing package removes it automatically once the test and all of its subtests have completed, so the test never writes its own removal code.

t.Parallel() marks a test as safe to run alongside other tests that also call it. The call pauses the test immediately; it resumes only after its parent test function has returned, and then runs concurrently with its parallel siblings.

A table-driven test declares a slice of case structs (name, input, want) and loops over them, calling t.Run(tc.name, ...) so every row becomes a named subtest that fails and can be re-run on its own.

Both mark the test as failed. t.Error logs the message and lets the test function keep running, so one run can report several problems. t.Fatal logs and stops that test function immediately.

reflect.DeepEqual reports false for a nil slice against an empty non-nil one. Decide what the function promises, then either write want to match it, compare with slices.Equal, which treats both as length zero, or assert len(got) == 0.

A trailing // Output: comment. go test compiles every Example function in a _test.go file but only runs one that ends with an // Output: comment, comparing what the example printed to stdout against that text after trimming surrounding whitespace.

Use errors.Is against a sentinel error, or errors.As with a typed error when the test needs a field off it. Both see through wrapping. Comparing err.Error() text is brittle, and checking only that err is non-nil pins nothing.

== compares every field of the time.Time struct, including the monotonic clock reading and the location pointer, so two values for the same instant can compare unequal. The Equal method compares the instant they represent.

By the name alone. Example documents the package, ExampleF a function or type F, and ExampleT_M the method M on type T. Any of those may carry a trailing lower-case suffix, such as ExampleParse_relativePath, to give one symbol several examples.

Declare a package-level var in the test file with flag.Bool("update", false, ...). The testing package parses flags before tests run, so when it is set the test writes the fresh output with os.WriteFile, then reads it back and compares.

A subtest that calls t.Parallel() is paused until the parent test function returns, and the parent's deferred calls fire at exactly that return — before the subtests execute. Register the removal with t.Cleanup, which waits for subtests.

Environment variables belong to the whole process, so one test's t.Setenv value would leak into every test running at the same time. The testing package therefore panics when a test combines t.Setenv with t.Parallel, in either order.

Before Go 1.22 a range loop reused one tc variable across iterations, so a closure outliving its iteration read the last row's values. The tc := tc line made a per-iteration copy; Go 1.22 made it unnecessary.

A subtest's full name is the parent name, a slash, then the case name with spaces turned into underscores. go test -run splits its pattern on slashes and matches each part as an unanchored regexp.

t.Error and t.Fatal report the file and line where they were called, which is inside the helper. Calling t.Helper() at the top of the helper makes the testing package skip that frame and report the caller's line in the test instead.

Almost certainly the example is never executed. An example runs only if the last comment in its body starts with // Output:, and only if the character after Example is upper-case; otherwise it is compiled, skipped and silently passes.

You gain tests bound to the exported contract, so behaviour-preserving refactors stop breaking them, plus honest API feedback and no test-only import cycles. You lose direct access to internal state, which returns only through a narrow seam.

Imports in a package foo test file count as imports of that package, so a helper importing foo closes a cycle the go command rejects. Package foo_test is downstream of both and nothing imports it, so no cycle exists.

The generator is almost certainly emitting in the order of a range over a Go map, and Go randomises that order deliberately. Sort the keys and emit in that fixed order, then assert determinism by generating twice and comparing.

Something still holds an open file inside the temp directory. Windows refuses to delete a file with a live handle, so the automatic removal registered by t.TempDir fails and reports an error, turning an otherwise passing test red.

Subtests calling t.Parallel run concurrently after the parent returns, so a map their closures captured is shared, not copied. Confirm with go test -race, then give each subtest its own fixture or guard the shared one with a sync.Mutex.

t.Fatal stops only the goroutine that calls it, because FailNow uses runtime.Goexit. The test function itself keeps running, or blocks forever waiting for a value that goroutine will now never send. Hand the failure back to the test goroutine instead.

When the example prints one line per item and the line order is not guaranteed, such as ranging over a map. With // Unordered output: the runner sorts the printed lines and the expected lines before comparing, so order stops mattering but content and count still do.

A file declaring package foo whose name ends in _test.go, so go test compiles it but a normal build never does. It assigns unexported identifiers to exported names, giving external tests a seam absent from the shipped API.

It is cancelled just before the test's registered cleanup functions are called. Every cleanup therefore sees an already-cancelled context, so teardown work that needs a live context must build its own from context.Background().

Inside one package's test binary, the number of tests running together is capped by go test's -parallel flag, which defaults to GOMAXPROCS. Separately, go test over several packages runs their binaries at the same time, capped by -p.

Returning early leaves the test reported as a normal pass. t.Skip logs a reason, marks the test as skipped, and stops it immediately, so the run records visibly that the test did not actually check anything.