Skip to content

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

  • Code Diff

    Review snapshot diffs before accepting an update.

  • JSON Diff

    Compare JSON snapshots field by field when they change.

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

Practice Snapshot Testing

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors