Odonno/vitest-snap-getting-started

This skill builds on setup and write-snapshot. Read them for full option references.

Setup (complete sequence)

Step 1 — Install

npm i vitest-snap -D
# or: bun add -D vitest-snap

Step 2 — Register matchers

import "vitest-snap";

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    setupFiles: ["./vitest.setup.ts"],
  },
});

Step 3 — Write first snapshot

import { expect, test } from "vitest";

test("user object", async () => {
  const user = { id: 1, name: "Alice", createdAt: new Date() };
  await expect(user).toJsonSnapshot();
  // first run: writes ./snapshots/user-object
  // subsequent runs: diffs against that file
});

Step 4 — What the defaults do

• undefined props are removed by UndefinedFilter
• Date instances are replaced with [Date_1], [Date_2], … by ValueRedaction
• Snapshot dir: ./snapshots relative to the test file
• Filename: slugified test name ("user object" → user-object)

Step 5 — Add a filter or redaction

import { expect, test } from "vitest";
import { UndefinedFilter, NullFilter, ReplacedRedaction } from "vitest-snap";

test("user object", async () => {
  const user = {
    id: 1,
    name: "Alice",
    password: "s3cr3t",
    createdAt: new Date(),
  };
  await expect(user).toJsonSnapshot({
    filters: [new UndefinedFilter(), new NullFilter()],
    redactions: [
      new ValueRedaction((_, v) => v instanceof Date, "[Date]"),
      new ReplacedRedaction(".password", "[REDACTED]"),
    ],
  });
});

Note: providing a custom filters or redactions array replaces the defaults — always re-add UndefinedFilter and the Date ValueRedaction when extending.

Core Patterns

Snapshot file location

<test-file-dir>/
└── snapshots/
    └── <slugified-test-name>[_<arg1>][_<arg2>][.<ext>]

Examples:

• "user object" → snapshots/user-object
• "pagination page-size %i" with args: [50] → snapshots/pagination-page-size-50
• args: [50], fileExtension: "json" → snapshots/pagination-page-size-50.json

Update snapshots

Run with --update-snapshots flag (Vitest native):

bunx vitest run --update-snapshots

Common Mistakes

CRITICAL: Missing await on snapshot matcher call

Wrong:

test("user", () => {
  expect(user).toJsonSnapshot(); // no await
});

Correct:

test("user", async () => {
  await expect(user).toJsonSnapshot();
});

All four matchers return Promise<void>; omitting await makes the test pass without writing or diffing the snapshot file — silent false positive.

Source: src/index.ts

CRITICAL: Matchers not registered — missing import in setup file

Wrong:

// vitest.config.ts — no setupFiles configured
export default defineConfig({ test: {} });

Correct:

// vitest.setup.ts
import "vitest-snap";

// vitest.config.ts
export default defineConfig({
  test: { setupFiles: ["./vitest.setup.ts"] },
});

vitest-snap registers matchers via side-effect import calling expect.extend(). Missing the import causes all matcher calls to throw at runtime.

Source: docs/content/docs/index.mdx

HIGH: Custom filters array silently removes default UndefinedFilter

Wrong:

await expect(data).toJsonSnapshot({
  filters: [new NullFilter()], // UndefinedFilter no longer applied
});

Correct:

await expect(data).toJsonSnapshot({
  filters: [new UndefinedFilter(), new NullFilter()],
});

filters: [...] completely replaces the default [new UndefinedFilter()]. Undefined props reappear in the snapshot.

Source: src/options/index.ts

HIGH: Custom redactions array silently removes default Date redaction

Wrong:

await expect(data).toJsonSnapshot({
  redactions: [new ReplacedRedaction(".password", "[REDACTED]")],
  // Dates no longer redacted → flaky tests
});

Correct:

await expect(data).toJsonSnapshot({
  redactions: [
    new ValueRedaction((_, v) => v instanceof Date, "[Date]"),
    new ReplacedRedaction(".password", "[REDACTED]"),
  ],
});

redactions: [...] completely replaces the default Date redaction. Dates appear as serialized strings → flaky tests.

Source: src/options/index.ts