tailscale/cmd/testwrapper/testdata/README.md

Race-output test corpus

This directory is a corpus of captured Go test binary outputs that exercise the various ways the -race detector's WARNING: DATA RACE text can land relative to === RUN / --- PASS: / --- FAIL: / === NAME lines, and how cmd/internal/test2json attributes that output to tests.

Each scenario subdirectory contains:

• src.go — the Go source code that was compiled and run to produce the captured output. Reproduce via go test -race -c -o /tmp/scenario.test ./<dir>/.
• raw.txt (or scenario-specific name) — the raw stdout+stderr of the resulting test binary when run as ./scenario.test -test.v. This is the byte stream that go test -json feeds to go tool test2json in production.

go test -json adds two things on top of what test2json sees, which are NOT in these captures: a FAIL\t<pkg>\t<time> output line and a corresponding fail action event when the binary exits with a non-zero status (e.g. the race detector's exit code 66). Consumers that simulate the go test -json view from these files need to append those.

To turn a raw.txt into the JSON testwrapper would consume:

go tool test2json -p <pkgname> < raw.txt

Scenarios

A_baseline — no race

Two trivial passing tests, no -race involvement at all. Useful as a sanity-check for parsers; demonstrates the standard mapping from === RUN/--- PASS:/bare PASS lines to JSON events.

B_inbody — race during a test's own body

A single test spawns racing goroutines and wg.Wait()s for them. The race fires while the test is still running, so testing.checkRaces sees race.Errors() increment between the test's start and end and the test is marked --- FAIL: with a testing.go:1712: race detected during execution of test line.

This is the well-behaved case: the race output and the failure marker are both attributed to a single, clearly-failed test.

C_spawnwait — race in goroutines that outlive a test

TestSpawn spawns racing goroutines and returns immediately; TestWait blocks until they finish. Where the race report lands is timing-dependent. Two captured variants:

• pass.raw.txt — both TestSpawn and TestWait end up marked --- PASS:, with the entire WARNING: DATA RACE report attributed to TestWait (the test whose === RUN line was the most recent thing emitted when TSan printed). Neither test's checkRaces saw race.Errors() increment within its window. The binary still exits non-zero, producing only a bare trailing FAIL. This is the case where testwrapper currently drops the race report on the floor.

• caught.raw.txt — TestSpawn's checkRaces happened to fire after the goroutines raced, so it emits the standard testing.go:1712: + --- FAIL: TestSpawn markers. Race report is attributed to TestSpawn, and the failure is attributed to TestSpawn too. Well-behaved.

D_delayed — race delayed into the next test's body

Like C_spawnwait but the spawned goroutines block on a channel that the second test closes, then sleeps. This forces the race counter delta to land between the second test's resetRaces and checkRaces, so the framework reliably attributes a failure to the sleeping test. Compare with B_inbody: same end shape, but the failure is attributed to a test that doesn't contain the racing code.

E_testmain — race in TestMain after m.Run()

The race-producing goroutines are spawned by TestMain after m.Run() returns. By that point the framework has already printed its top-level PASS summary, so test2json's c.testName is reset to "" and the entire race report shows up at package level — all of its output events have an empty Test field. The bare PASS line earlier in the output also causes test2json to set c.result = "pass", which means go tool test2json in isolation ends up emitting {"Action":"pass","Package":"..."} for the package; only go test's own exit-code post-processing turns it into the visible package-level failure.

F_parallel — racing parallel tests

Two t.Parallel() tests both increment the same global. The captured split.raw.txt shows the report split across two tests via a === NAME TestParB redirect line emitted by the framework:

--- PASS: TestParA (0.00s)
==================
WARNING: DATA RACE
   ... full race report ...
==================
=== NAME  TestParB
    testing.go:1712: race detected during execution of test
--- FAIL: TestParB (0.00s)

test2json attributes the WARNING: DATA RACE block plus the full stack trace to TestParA (which passes), then sees the === NAME TestParB directive and switches attribution, so the trailing race detected line and --- FAIL end up under TestParB (which fails). A consumer that only flushes failed tests' logs sees the race detected line but loses the stack trace.

How these were captured

# For each scenario directory <name>/ (e.g. C_spawnwait):
go test -race -c -o /tmp/<name>.test ./testdata/<name>/
/tmp/<name>.test -test.v >./testdata/<name>/raw.txt 2>&1

For scenarios where the race detector's attribution is timing-dependent (C, F), the binary was run repeatedly and the interesting variants saved with distinct names.

The captured outputs contain absolute file paths from the machine they were recorded on (e.g. /tmp/racesurvey/...). Tests that match against these files should not depend on those paths.