Some outputs are awkward to assert on. A generated report, a serialised API response, a rendered template, a formatted document — writing individual assertions for every field is tedious, and you will miss the fields you did not think about.
Golden file testing stores a reference output and compares against it. Any difference fails the test. You get complete coverage of the output for almost no assertion-writing effort.
What changed in 2026
- The regeneration problem became the recognised weakness. Awareness that easy approval undermines the technique became widespread.
- Normalisation tooling improved. Libraries handling timestamp and identifier scrubbing reduced false failures.
- Review-diff practices tightened. Requiring golden file changes to be reviewed like code became standard.
- Characterisation testing gained ground. Using golden files to capture legacy behaviour before refactoring became a common technique.
What they are good at
Complete coverage of a complex output. Every field, including ones you would not have thought to assert on. A change to a field nobody remembered exists still fails the test.
Characterising legacy behaviour. Before refactoring code nobody fully understands, capture its current output as golden files. Then refactor, and any behavioural change shows up immediately. This is one of the most valuable uses, because it lets you refactor safely without first understanding everything.
Catching formatting and serialisation changes. A library upgrade that changes JSON key ordering or number formatting is invisible to field-level assertions and obvious in a golden file diff.
| Suits |
Does not suit |
| Generated documents and reports |
Simple return values |
| Serialised API responses |
Logic with two meaningful assertions |
| Rendered templates |
Highly non-deterministic output |
| Compiler or formatter output |
Anything with a genuinely variable shape |
| Legacy behaviour capture |
Behaviour you are deliberately changing often |
The regeneration trap
Every golden file framework provides a way to regenerate references when output changes legitimately. That is necessary, and it is where the technique fails.
The workflow becomes: test fails, run the regenerate command, commit, move on. The failure that was supposed to make you examine a change instead prompts a reflexive approval.
Done consistently, golden file tests stop catching anything — they record whatever the code produces, which is not a test.
Three practices keep them honest.
Review the diff, always. Treat a golden file change like a code change, because it is one — it is the observable behaviour of your system changing.
Require the diff in review. A pull request changing golden files should show them, and a reviewer should look. Large unexplained golden file changes are a signal.
Keep files small. A five-thousand-line reference produces a diff nobody reads. Several focused files, each covering one scenario, produce diffs that are actually reviewable — this is the single most effective structural fix.
Normalising non-determinism
Golden files fail constantly if the output contains anything that varies: timestamps, generated identifiers, durations, random values, or ordering that is not guaranteed.
The answer is normalising before comparison — replace timestamps with a placeholder, replace identifiers with stable substitutes, sort collections whose order is not meaningful.
Two cautions. Normalise only what genuinely varies; over-normalising hides real changes. And be careful with ordering: sorting a collection whose order is meaningful means an ordering bug will never be caught.
Where output contains a mix, structured comparison — parsing the output and comparing with rules per field — is more work and more precise than text diffing.
Common mistakes
- Regenerating without reading the diff. Defeats the mechanism entirely.
- Enormous golden files. Unreviewable diffs.
- No normalisation. Constant false failures, then the tests get ignored.
- Over-normalisation. Hides real changes.
- Sorting meaningfully-ordered output. Ordering bugs become invisible.
- Golden files for simple logic. Write the two assertions instead.
- Not committing golden files. Then there is no reference.
FAQ
Are these the same as snapshot tests?
Essentially yes — the terminology varies by ecosystem. The mechanism and the regeneration weakness are identical.
How do I stop reflexive regeneration?
Structurally: small files producing readable diffs, and a review process that surfaces them. Discipline alone does not survive a busy week.
Should golden files be in version control?
Yes — they are the reference, and their history is the record of how output changed over time, which is genuinely useful during investigation.
What about very large outputs?
Split into focused scenarios rather than one big file, or compare structurally with field-level rules rather than as text.
Where to go next
For test data construction, read fixture management. For testing against a real database, testcontainers, and for finding inputs you did not think of, API fuzzing.