vitest-snap

The perfect matchers for Vitest snapshot testing.

---

Features

• Auto-naming — snapshot filenames are derived from the test name automatically; no boilerplate required
• Parameterised snapshots — pass args to generate distinct snapshot files per test input
• Filtering & redactions — scrub, replace, remove or sort values before snapshotting with a composable DSL
• Date redaction by default — Date instances are replaced with [Date_1], [Date_2], … out of the box
• Undefined filtered by default — undefined props are removed from objects to unclutter test snahpsots
• Rich selector syntax — target nested paths, array indices, slices, wildcards, and deep matches; with full TypeScript support
• Zero config — works with your existing Vitest setup

---

Install

npm i -D vitest-snap

Then register the matchers in your Vitest setup file:

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

// vitest.config.ts
import { defineConfig } from "vitest/config";

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

You will also need to configure .d.ts TypeScript definitions for the new matchers:

// src/vitest.d.ts
import "vitest";
import "vitest-snap";

Agent Skills

AI coding agents (Claude Code, Cursor, Copilot, etc.) can install vitest-snap skills to get accurate, pattern-aware guidance for this library:

npx @tanstack/intent@latest install vitest-snap

---

Get Started

Basic usage

import { expect, test } from "vitest";

test("snapshot a plain object", async () => {
  await expect({ name: "Alice", age: 30 }).toJsonSnapshot();
});

// snapshot written to `./snapshots/snapshot-a-plain-object`

Named snapshots

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

Custom output directory

await expect(data).toJsonSnapshot({
  dir: "./tests/snapshots/custom",
  name: "my-snapshot",
});

Parameterised snapshots

Pass args to generate a unique snapshot file per parameter combination:

test.each([
  { id: 1, label: "first" },
  { id: 2, label: "second" },
])("item $label", async ({ id, label }) => {
  const item = await fetchItem(id);
  await expect(item).toJsonSnapshot({ name: "item", args: [label] });
  // -> snapshots/item_first, snapshots/item_second
});

---

Documentation

You can find the documentation of this project here: https://vitest-snap.vercel.app/

---

Thank You

Greatly inspired by Insta and Verify.