Snapshot testing

Snapshot testing captures the output of your code and compares it against a stored reference version on every test run. Instead of hand-writing an assertion for each property, you let the test runner record the entire serialized output once, then fail loudly whenever that output changes. This is ideal when the value you want to verify is large or hard to express by hand (rendered HTML, CLI output, API response shapes, error objects), or when the expected output changes often enough that maintaining manual assertions becomes a chore. The Deno Standard Library ships this as the @std/testing/snapshot module.

Write your first snapshot test Jump to heading#

The assertSnapshot function serializes a value and compares it to a reference snapshot stored alongside your test file. It takes the test context t that Deno passes to your test function, which it uses to name the snapshot and locate the snapshot file.

import { assertSnapshot } from "jsr:@std/testing/snapshot";

Deno.test("isSnapshotMatch", async (t) => {
  const a = {
    hello: "world!",
    example: 123,
  };
  await assertSnapshot(t, a);
});

No snapshot exists yet, so the first run must create one. New snapshots are only written when you run the tests in update mode:

deno test --allow-read --allow-write -- --update

Two things to note about this command:

• --allow-read and --allow-write are required because assertSnapshot reads and writes snapshot files on disk. Without --allow-read, every call to assertSnapshot fails with a permission error. You can scope both permissions down to just the snapshot directory if you prefer.
• The bare -- separates flags for deno test from arguments passed to the test files themselves. The --update flag (or its short form -u) must come after the --, because it is read by the snapshot module, not by the Deno CLI.

Once the snapshot exists, run the test normally. Only read permission is needed:

deno test --allow-read

The test now passes if the serialized value matches the stored snapshot and fails with an AssertionError showing a diff if it does not.

Read the snapshot file Jump to heading#

Snapshots are written to a __snapshots__ directory next to the test file, in a .snap file named after the test module. For the example above, the file is __snapshots__/example_test.ts.snap:

export const snapshot = {};

snapshot[`isSnapshotMatch 1`] = `
{
  example: 123,
  hello: "world!",
}
`;

Each entry is keyed by the test name plus a counter, so a test that calls assertSnapshot multiple times produces isSnapshotMatch 1, isSnapshotMatch 2, and so on. The value is the result of serializing your data with Deno.inspect, with object keys sorted alphabetically. Snapshot files are plain TypeScript, so they are easy to read in code review.

Commit snapshot files to version control. That way, snapshot changes are reviewed alongside the code changes that caused them, and anyone who pulls your branch gets passing tests without regenerating snapshots locally.

Update snapshots Jump to heading#

This is the part of the workflow you will use most. When you intentionally change behavior and your snapshot tests start failing, or when you add new assertSnapshot calls, rerun the tests in update mode:

deno test --allow-read --allow-write -- --update

In update mode, any snapshot that does not match the current output is rewritten, and any missing snapshot is created. Snapshots that already match are left untouched. You can also pass -u instead of --update.

After updating, inspect the diff of the .snap files with git diff before committing. The update command happily records bugs as the new expected output, so the human review of that diff is what gives snapshot tests their value.

To try the full loop with the example above: change hello: "world!" to hello: "everyone!", run deno test --allow-read, and watch the test fail with a diff. Then run the update command and the snapshot file is rewritten to match.

Review snapshot diffs in CI Jump to heading#

In CI you want to verify snapshots, never update them, so run the tests without the --update flag and without write permission:

name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x
      - name: Run tests
        run: deno test --allow-read

If a pull request changes output, the CI run fails and the author must update the snapshots locally and commit the new .snap files. Reviewers then see the exact before-and-after output in the pull request diff and can confirm the change is intentional.

Control serialization and snapshot location Jump to heading#

assertSnapshot accepts an options object as its third argument for cases where the defaults do not fit:

import { assertSnapshot, serialize } from "jsr:@std/testing/snapshot";
import { stripAnsiCode } from "jsr:@std/fmt/colors";

function customSerializer(actual: string) {
  return serialize(stripAnsiCode(actual));
}

Deno.test("Custom Serializer", async (t) => {
  const output = "\x1b[34mHello World!\x1b[39m";
  await assertSnapshot(t, output, {
    serializer: customSerializer,
  });
});

The most useful options:

• serializer: a function that turns the value into a string. It must be deterministic. Use it to strip ANSI color codes, replace timestamps or UUIDs with placeholders, or redact sensitive data before it lands in a committed file.
• name: overrides the snapshot key, which otherwise defaults to the test name.
• dir and path: control where the snapshot file is written, resolved relative to the test file.
• mode: force "assert" or "update" behavior for a single call, regardless of the --update flag.

Classes can also customize their own serialization by implementing Symbol.for("Deno.customInspect"), since the default serializer is built on Deno.inspect. See the @std/testing/snapshot API documentation for the full options reference and the createAssertSnapshot factory.

When not to snapshot Jump to heading#

Snapshot tests assert that output has not changed, not that it is correct. They are a poor fit when:

• A precise assertion is easy to write. assertEquals(sum, 3) documents intent far better than a snapshot of 3.
• The output is non-deterministic. Timestamps, random IDs, and unordered collections cause flaky failures unless you normalize them with a custom serializer.
• The output is huge. Multi-thousand-line snapshots get rubber-stamped in review, which defeats the purpose. Snapshot the relevant fragment instead.
• The test should verify behavior rather than representation. Asserting on a rendered string couples the test to formatting details that may change for unrelated reasons.

A good rule of thumb: use snapshots where a human can meaningfully review the recorded output, and explicit assertions everywhere else.

Keep going Jump to heading#

• Testing overview: the built-in test runner, assertions, steps, and permissions.
• Mocking: spies, stubs, and faked time for the inputs your snapshots depend on.
• @std/testing/snapshot API docs: every option, plus createAssertSnapshot for shared defaults.