Golden files and testdata

Canonical guidance

• keep external fixtures under testdata/
• make golden updates explicit
• choose fixture formats that are easy to diff and review when practical

Use when

• parser outputs
• rendered templates
• protocol fixtures
• stable serialized responses

Avoid

• scattering fixtures through package roots
• rewriting golden files during ordinary test runs
• huge opaque binary goldens when a smaller text fixture would do

Preferred pattern

want, err := os.ReadFile("testdata/want.json")
if err != nil {
	t.Fatal(err)
}

Anti-pattern

• auto-updating every golden file whenever a test fails because it is faster than deciding whether the behavior change is correct

Explanation: This anti-pattern is tempting because it keeps tests green, but it destroys the review value of fixtures.

Why

• fixtures are useful only when changes are intentional and inspectable