The Mirror That Never Forgot
Rachna the creator made intricate tapestries. Each tapestry had hundreds of threads, each in a precise position. The first time a tapestry was finished, Darpan the mirror was held up to it and captured its exact image — every thread, every colour, every knot. The image was stored in the guild archive. The next time the tapestry was woven, Tulana the comparator held the new tapestry beside the stored image. If every thread matched, the tapestry was approved without inspection. If any thread was different, Tulana flagged it. Rachna did not need to specify every thread in advance — the first completed tapestry became the specification. Correctness was defined as "the same as before."
“A snapshot test records the output of the first correct run. Every subsequent run is verified against that record.”
The Difference That Was a Mistake
One morning, Tulana reported that thread forty-seven had moved three knots to the right. Rachna had not noticed. She reviewed her recent changes: she had adjusted the loom's tension the previous day, and the adjustment had shifted thread forty-seven as an unintended side effect. Without the mirror, this shift would have been invisible — thread forty-seven was in the interior of the tapestry, rarely examined. With the mirror, it was immediately obvious. Rachna corrected the loom tension. Thread forty-seven returned to its original position. The stored image remained unchanged. The tapestry was approved. A regression had been caught and corrected before the tapestry was ever delivered.
“Snapshot tests catch unintended changes in complex output — including changes in parts that would not be manually inspected.”
The Difference That Was an Improvement
A season later, Rachna redesigned the tapestry's border. The new border was intentionally different — a deliberate improvement. Tulana reported the difference. Nayaka the approver examined the difference: the old border and the new border, side by side. The new border was indeed an improvement. Nayaka approved the change and instructed Darpan to replace the stored image with the new one. This was the critical act: the approver decided whether a difference was a mistake or an intention. Darpan could not make this decision. Tulana could not make this decision. Only Nayaka, who understood the purpose of the tapestry, could decide that the difference was correct. After the approval, the new border became the standard.
“When a snapshot diff is intentional, update the snapshot. The update is an explicit approval, not an automatic bypass.”
The Mirror That Captured Too Much
Trouble arose when Darpan began capturing every detail of the workshop, not just the tapestry — the tools on the wall, the dust on the floor, the shadows from the window. Every morning the shadows were different. Tulana reported differences every single day. Nayaka approved them every single day. After two weeks, Nayaka stopped looking carefully before approving. She approved every change reflexively. On the day that thread forty-seven moved again — a genuine regression — she approved it without noticing. The mirror had captured too much. Too many irrelevant differences had trained the approver to stop scrutinising. Darpan was instructed to capture only the tapestry itself, in a normalised form that removed shadows and dust.
“Snapshots that are too large or too detailed create noise. Noise trains approvers to stop looking. Normalise snapshots to contain only what matters.”
The Thread That Changed Every Day
One tapestry was made with a thread that changed colour with the temperature. Each day it was woven, thread ninety-nine was a slightly different shade. Darpan could not store a stable image of this tapestry — the stored image was outdated by morning. The comparator reported a difference every day. The difference was meaningless but unavoidable. Rachna's solution was to replace the temperature-sensitive thread with a fixed-colour stand-in during the mirror's examination. The stand-in was always the same colour. Darpan captured a stable image. The real tapestry, when delivered, contained the real thread. The mirror tested the structure of the tapestry, not its transient values.
“Replace dynamic values (timestamps, generated IDs, random colours) with stable stand-ins before snapshotting. Test structure, not transient state.”
The Archive That Travelled with the Tapestry
The guild kept strict rules about Darpan's stored images: they lived in the same archive as the tapestry designs, not in a separate storage room. When a tapestry design was moved to a new workshop, the stored image came with it. When an apprentice received the design from the archive, they received the stored image too. If an apprentice changed the tapestry without updating the stored image, the image and the design would disagree — and the next comparator's check would fail. The archive's integrity depended on this pairing. The stored images were version-controlled, reviewed in design handoffs, and deleted when their tapestry was retired.
“Snapshot files belong in version control alongside the tests. They are not generated artifacts — they are the specification.”
🪔 Deepak — the lamp of meaning · what this fable means in code
Snapshot testing records the serialised output of a component or function and compares it on every subsequent run. In Vitest and Jest, `toMatchSnapshot()` serialises the argument to a `.snap` file on the first run; on subsequent runs it compares the current output to the stored snapshot. `toMatchInlineSnapshot()` stores the snapshot as a string literal inside the test file — useful for small, reviewable snapshots. `toMatchFileSnapshot()` (Vitest) writes to an arbitrary file path, useful for larger outputs like HTML or JSON. Snapshot tests are most valuable for: component rendering output (React Testing Library + `toMatchSnapshot()`), serialisation formats (JSON API responses), and complex data transformations. Anti-patterns: snapshotting entire large components (creates noise), approving snapshot updates without reviewing the diff (bypasses the protection), and snapshotting dynamic values like dates or IDs (use `expect.any(String)` matchers to mask them). Run `vitest --update-snapshots` (or `jest --updateSnapshot`) to regenerate; always review the diff before committing.