Odonno/vitest-snap-write-snapshot

vitest-snap/write-snapshot

Setup

Install and register matchers via side-effect import in vitest setup file:

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

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

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

For toYamlSnapshot, install the yaml peer dependency:

bun add yaml

Minimum working test:

import { describe, expect, test } from "vitest";
// matchers registered via side-effect import in vitest.setup.ts

test("user object", async () => {
  const user = { id: 1, name: "Alice", createdAt: new Date() };
  await expect(user).toJsonSnapshot();
  // writes: ./snapshots/user-object
  // { "id": 1, "name": "Alice", "createdAt": "[Date_1]" }
});

Core Patterns

1. All four matcher signatures

toJsonSnapshot(options?: SnapJsonOptions<T>): Promise<void>
toYamlSnapshot(options?: SnapYamlOptions<T>): Promise<void>
toMarkdownSnapshot(options?: SnapMarkdownOptions<T>): Promise<void>
toTextSnapshot(options?: SnapTextOptions): Promise<void>

Options available per matcher:

| Option | JSON | YAML | Markdown | Text | | --------------- | ---- | ---- | -------- | ---- | | dir | ✓ | ✓ | ✓ | ✓ | | name | ✓ | ✓ | ✓ | ✓ | | fileExtension | ✓ | ✓ | ✓ | ✓ | | args | ✓ | ✓ | ✓ | ✓ | | filters | ✓ | ✓ | ✓ | ✗ | | redactions | ✓ | ✓ | ✓ | ✗ | | indent | ✓ | ✓ | ✗ | ✗ |

2. Auto-naming from test name

When no name is provided, the snapshot filename is derived from the slugified current test name:

test("user profile data", async () => {
  await expect(user).toJsonSnapshot();
  // writes: ./snapshots/user-profile-data
});

describe("users", () => {
  test("admin role", async () => {
    await expect(admin).toJsonSnapshot();
    // writes: ./snapshots/admin-role
  });
});

The slug is computed from the leaf test name only (not the describe block name).

3. Parametric snapshots with test.each

test.each([10, 50, 100])("pagination page-size %i", async (pageSize) => {
  const result = await fetchUsers({ pageSize });
  await expect(result).toJsonSnapshot({ name: "page-size", args: [pageSize] });
  // writes: ./snapshots/page-size_10
  // writes: ./snapshots/page-size_50
  // writes: ./snapshots/page-size_100
});

args values are appended to the filename with _ separator. Always provide name + args together in test.each to decouple snapshot filenames from test description strings.

4. File extension and custom name

test("config", async () => {
  await expect(config).toJsonSnapshot({
    name: "app-config",
    fileExtension: "json",
    dir: "./__snapshots__",
  });
  // writes: ./__snapshots__/app-config.json
});

Default file extension is empty (no extension). The dir option is relative to the test file location.

5. Indentation

await expect(data).toJsonSnapshot({ indent: 4 });
// uses 4-space indent instead of default 2

await expect(data).toYamlSnapshot({ indent: 2 });

6. Markdown table rendering rules

// array of objects → one row per element, columns = union of all keys
await expect(users).toMarkdownSnapshot();
// | id | name  | role   |
// | -- | ----- | ------ |
// | 1  | Alice | admin  |
// | 2  | Bob   | viewer |

| Input | Output | | ----------------------- | ------------------------------------------------ | | Array of objects | One row per element; columns = union of all keys | | Single object | One row; columns = object keys | | Primitive | Single-column table with header value | | null/undefined cell | Empty string | | Nested object cell | JSON.stringify(value) | | Date cell | .toISOString() |

7. YAML snapshot

test("server config", async () => {
  await expect(serverConfig).toYamlSnapshot();
  // writes: ./snapshots/server-config
  // host: localhost
  // port: 8080
});

Requires yaml peer dependency installed. Serialization uses the yaml package internally.

8. Text snapshot

test("csv export", async () => {
  const csv = generateCsv(data);
  await expect(csv).toTextSnapshot();
  // writes: ./snapshots/csv-export
});

toTextSnapshot expects a string value. No serialization is applied — the string is written as-is.

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.

Source: src/index.ts

HIGH: toTextSnapshot does not support filters or redactions

Wrong:

await expect(user).toTextSnapshot({
  filters: [new ExcludeFilter(".password")], // silently ignored
});

Correct:

await expect(user).toJsonSnapshot({
  filters: [new ExcludeFilter(".password")],
});

SnapTextOptions omits filters and redactions — passing them has no effect. Use toJsonSnapshot for transformation pipelines.

Source: src/options/types.ts — SnapTextOptions

MEDIUM: Omitting args in test.each — snapshot filename coupled to test name

Wrong:

test.each([10, 50])("page size %i", async (pageSize) => {
  // slug changes if test name changes
  await expect(result).toJsonSnapshot();
});

Correct:

test.each([10, 50])("page size %i", async (pageSize) => {
  await expect(result).toJsonSnapshot({ name: "page-size", args: [pageSize] });
});

Without args, the slug is derived from the full interpolated test name. Renaming the test renames all snapshot files.

Source: src/options/file.ts; docs/content/docs/matchers/to-json-snapshot.mdx

LOW: fileExtension with double dot

Wrong:

await expect(data).toJsonSnapshot({ fileExtension: "..json" }); // → file..json

Correct:

await expect(data).toJsonSnapshot({ fileExtension: "json" });
// or
await expect(data).toJsonSnapshot({ fileExtension: ".json" });

detectGeneratedFilePath prepends . only when the extension does not already start with .. ..json produces filename..json.

Source: src/options/file.ts

Snapshot File Location

Default: ./snapshots/<slug> relative to the test file.

Override with dir:

// absolute path
await expect(data).toJsonSnapshot({ dir: "/tmp/snapshots" });

// relative to test file
await expect(data).toJsonSnapshot({ dir: "./custom-snapshots" });

Updating Snapshots

Run vitest with the --update flag to regenerate snapshot files:

bunx vitest run --update
# or
bunx vitest run -u