Snapshot and golden-file tests and how to keep them honest

What it is

A snapshot (or golden-file) test serialises an output, such as a rendered component, an API response, a command's stdout or a generated file, and compares it with a stored reference. On the first run the reference is written; afterwards any difference fails the test. Jest's documentation describes toMatchSnapshot() writing to a .snap file in a __snapshots__ directory next to the test, inline snapshots written back into the test source, --updateSnapshot to regenerate references after an intentional change, and the rule that new snapshots are not written automatically on CI without that flag. Rust's insta follows the same pattern with .snap.new files that are accepted through cargo insta review, and offers redactions for volatile fields.

Why it matters

For outputs with many details, hand-written assertions check a few fields and miss the rest; a snapshot checks all of it at the cost of stating no intent. It turns "did anything change?" into a diff a reviewer can read, which is exactly what is needed for output formats, error messages and generated artefacts. Used well, snapshots are characterisation tests for formats; used badly, they are a pile of accepted diffs nobody reads.

How to apply

• Snapshot outputs that are contracts: response shapes, generated configuration, help text, error messages. Keep each snapshot short and focused; Jest's docs recommend small snapshots and descriptive names so that a reviewer can judge from the name whether the stored content is right.
• Normalise volatile data before serialising: timestamps, generated ids, order of unordered collections, absolute paths. Jest offers property matchers such as expect.any(Date); insta offers redactions.
• Review snapshot diffs in the pull request as code. Jest's docs warn against the habit of regenerating snapshots when suites fail instead of examining the cause.
• Update selectively, by test name pattern or interactively, rather than with a blanket update after an unrelated failure.
• Commit snapshot files and make CI fail on missing or obsolete ones.

Pitfalls

A snapshot that changes in every pull request has stopped testing anything and trains people to accept blindly. Snapshots of whole pages couple a test to unrelated components. A snapshot records the current output, not the correct one: a bug captured on the first run is approved until someone reads the file. Locale, line endings and floating-point formatting make snapshots differ between machines. A snapshot is no substitute for one assertion that states the requirement.