How Snapshot Files Work

Snapshot files come in two states:

• approved snapshots
• pending candidates

Understanding that distinction is the key to using snapshot tests sanely.

Approved files

Approved files are the current contract.

For ordinary tests they live under:

.riot/snapshots/<package>/<suite>/<test>.expected

For fixture-backed tests they usually live next to the fixture input with an .expected extension.

These files are what the test suite is asserting against.

Pending files

When a snapshot assertion discovers a missing or mismatched approved file, Riot writes a pending file:

*.expected.new

That file is a candidate, not a fact.

It exists so you can:

• inspect the proposed new output
• diff it against the approved artifact
• either approve or reject it explicitly

Why .expected.new is the right shape

It solves an important review problem.

If normal test execution rewrote the approved snapshot automatically, you would not know whether:

• the code changed correctly
• the code changed incorrectly
• the snapshot merely drifted by accident

.expected.new keeps the change visible and interruptive until someone decides what it means.

Fixture-backed snapshots

When tests are driven by fixtures, the storage model changes slightly:

• the fixture file is the input
• the .expected file near it is the approved output
• the .expected.new file near it is the pending output

This is useful because reviewers can look at:

• input
• approved output
• proposed output

all in one place.

Hygiene rules

Good snapshot hygiene is simple:

• commit approved snapshots
• review pending candidates intentionally
• reject stale pending files
• avoid snapshotting noisy or unstable outputs

When snapshots are disciplined, they become one of the most review-friendly testing tools in the system.