Snapshot Testing
Capture and compare serialized output with snapshots, and know when not to use them.
What you'll learn
- What a snapshot test is and how it stores output
- Writing and updating snapshots with toMatchInlineSnapshot
- When snapshots add value and when they are a trap
- Reviewing snapshot diffs to avoid false confidence
Concept
What a Snapshot Does
A snapshot test serializes the output of your code — a rendered component, a serialized object, an error message — and stores it in a .snap file. On the next run, the test serializes the output again and compares it to the stored snapshot. If it differs, the test fails and shows a diff; you then decide whether the change is intentional (update the snapshot) or a bug (fix the code).
Writing Snapshots
In Vitest and Jest, expect(output).toMatchSnapshot() writes or compares the snapshot. toMatchInlineSnapshot() stores the snapshot as a string literal inside the test file, which keeps the expected value visible and version-controlled alongside the test — preferable for small outputs. Run with the -u flag to update snapshots after an intentional change.
When They Help
Snapshots shine for stable, serializable output that is tedious to assert field-by-field: a deeply nested configuration object, a serialized AST, a large component render. They catch unintended changes to any field at once and produce a readable diff. They are also useful for regression tests on output you cannot easily enumerate.
When They Trap
Snapshots become a trap when developers blindly run -u to make the test pass without reading the diff. A snapshot that is updated without thought asserts nothing — it will always pass. Avoid snapshots for logic (use explicit assertions), for output with non-deterministic values (dates, random ids) unless you mask them, and for anything so large no one will review the diff. Treat every snapshot update as a code review item.
In Practice
Use toMatchInlineSnapshot for small outputs so the expected value lives in the test file and is visible during code review — reviewers can see exactly what changed. For larger outputs (a full component render), use an external .snap file but keep it under 50 lines; if it grows beyond that, the component is probably doing too much and should be split. Always mask non-deterministic values before snapshotting: replace dates with a placeholder, strip random ids, and normalize whitespace. When a snapshot fails in CI, never run -u remotely — pull the branch locally, read the diff, update intentionally, and commit with a message explaining why the output changed. A snapshot you can explain is a safety net; one you blindly accept is technical debt.
Example
import { describe, it, expect } from "vitest";
import { render } from "@testing-library/react";
import { UserCard } from "./UserCard";
describe("UserCard", () => {
it("matches the stored snapshot", () => {
const { container } = render(
<UserCard user={{ id: 1, name: "Ada", role: "admin" }} />
);
expect(container.firstChild).toMatchSnapshot();
});
it("serializes config deterministically", () => {
const config = buildConfig({ theme: "dark", lang: "en" });
expect(config).toMatchInlineSnapshot();
});
});
The first test snapshots the rendered DOM; the second snapshots a config object inline in the test file. Review the diff on every update.
Try it
Common mistakes
The mistake
Running vitest -u without reading the diff
The fix
Always review the snapshot diff in code review. A blindly updated snapshot asserts nothing and hides real regressions.
The mistake
Snapshotting output with timestamps or random ids
The fix
Mask non-deterministic values before snapshotting (replace dates with a fixed string) so the snapshot is stable across runs.
Practice Snapshot Testing
5 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.