Storybook test-runner "A snapshot ... does not match" in CI

By Kaveh Alemi·Latchkey

A test-runner snapshot hook compared a story's current output against a stored snapshot and they differ. Either the change is intended and the snapshot must be updated, or the render is nondeterministic across environments.

What this error means

The runner fails a story with "A snapshot ... does not match its stored snapshot" and prints a diff of the stored versus received output.

● Received value does not match stored snapshot "Button > Primary"
- Snapshot
+ Received
-   <button class="btn btn-primary">
+   <button class="btn btn-primary btn-lg">

Common causes

An intended UI change without updated snapshots

The component changed on purpose, but the committed snapshot still reflects the old output.

Environment-dependent rendering

Dates, random IDs, or font metrics differ between the local machine and the Linux runner, producing spurious diffs.

How to fix it

Update snapshots when the change is intended

1. Review the diff to confirm the change is expected.
2. Regenerate snapshots locally and commit them.
3. Re-run CI so the stored snapshots match.

npx test-storybook -u

Make the render deterministic

Freeze time, seed randomness, and pin fonts in stories so snapshots are stable across machines.

// preview.ts
export const parameters = { chromatic: { pauseAnimationAtEnd: true } };

How to prevent it

• Commit updated snapshots in the same change as the UI update.
• Remove nondeterminism (dates, random IDs) from stories.
• Run the test-runner locally on Linux (or a container) to match CI.

Frequently asked questions

Related guides

References

• GitHub Actions documentation