Odonno/vitest-snap-setup

vitest-snap/setup

Install

npm i vitest-snap -D
# bun: bun add -D vitest-snap
# pnpm: pnpm add -D vitest-snap
# yarn: yarn add -D vitest-snap

Register Matchers

Side-effect import in a setup file — mandatory before any matcher call.

import "vitest-snap";

import { defineConfig } from "vitest/config";

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

expect.extend() is called at import time. Missing this causes all matcher calls to throw at runtime.

Global Defaults

Call configureGlobalSnapOptions in the setup file only — never inside test bodies.

import {
  configureGlobalSnapOptions,
  NullFilter,
  UndefinedFilter,
} from "vitest-snap";

configureGlobalSnapOptions({
  dir: "./__snapshots__",
  filters: [new UndefinedFilter(), new NullFilter()],
});

Option Merge Order

built-in defaults → global (configureGlobalSnapOptions) → per-call options

Per-call always wins. Each layer fully replaces array options (no merging of arrays).

// built-in defaults apply
// global sets dir
configureGlobalSnapOptions({ dir: "./__snapshots__" });

// per-call overrides dir and filters for this one call only
await expect(data).toJsonSnapshot({ dir: "./other", indent: 4 });

Built-in Defaults

| Option | Default | | ------------ | ---------------------------------------- | | dir | "./snapshots" | | filters | [new UndefinedFilter()] | | redactions | [new ValueRedaction(isDate, "[Date]")] | | indent | 2 |

name, fileExtension, args have no default — derived from test name or left empty.

yaml Peer Dependency

toYamlSnapshot does a dynamic import("yaml") at runtime. Install separately:

npm i -D yaml

Common Mistakes

CRITICAL: Missing await on snapshot matcher

All four matchers return Promise<void>. Omitting await makes the test pass without writing or diffing the snapshot.

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

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

Source: src/index.ts — expect.extend async implementations

---

CRITICAL: Matchers not registered

// WRONG — 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"] },
});

Source: docs/content/docs/index.mdx

---

HIGH: configureGlobalSnapOptions called inside test body

globalOptions is a module-level variable. Setting it inside a test is order-dependent and unpredictable.

// WRONG
test("my test", async () => {
  configureGlobalSnapOptions({ dir: "./__snapshots__" });
  await expect(data).toJsonSnapshot();
});

// CORRECT — vitest.setup.ts
import { configureGlobalSnapOptions } from "vitest-snap";
configureGlobalSnapOptions({ dir: "./__snapshots__" });

Source: src/options/global.ts; docs/content/docs/matchers/configuration.mdx

---

HIGH: yaml package not installed when using toYamlSnapshot

// WRONG — "yaml" not in package.json
await expect(data).toYamlSnapshot(); // throws module-not-found

// CORRECT — install first
// npm i -D yaml
await expect(data).toYamlSnapshot();

Source: src/functions/yaml.ts

---

HIGH: Custom filters array silently removes default UndefinedFilter

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

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

// CORRECT
import { NullFilter, UndefinedFilter } from "vitest-snap";

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

Source: src/options/index.ts — DEFAULT_OPTIONS

---

MEDIUM: Changing global dir without moving existing snapshot files

toMatchFileSnapshot looks in the new location. Existing files in the old location are not moved automatically.

// WRONG — orphans existing ./snapshots/* files
configureGlobalSnapOptions({ dir: "./__snapshots__" });

// CORRECT
// 1. update config
configureGlobalSnapOptions({ dir: "./__snapshots__" });
// 2. move files
// mv ./snapshots/* ./__snapshots__/

Source: src/options/file.ts