vitest-snap documentation

Overview

Redactions replace node values (rather than removing them) after filters have been applied. They are useful for masking volatile or sensitive data — dates, tokens, IDs — with stable placeholder strings.

import { ReplacedRedaction, SortedRedaction } from "vitest-snap";

await expect(data).toJsonSnapshot({
  redactions: [
    new ReplacedRedaction(".apiKey", "[REDACTED]"),
    new SortedRedaction(".tags"),
  ],
});

ValueRedaction

Replaces any node where a predicate function returns true.

Applied by default for Date instances: every Date is replaced with [Date_1], [Date_2], … Pass a custom redactions array to override.

Constructor

new ValueRedaction(
  predicate: (path: string, value: unknown) => boolean,
  replaced:  string | ((prevValue: any) => any),
  counting?: boolean,
)

Parameter	Type	Default	Description
`predicate`	`(path, value) => boolean`	—	Returns `true` for nodes to redact
`replaced`	`string \| ((prevValue) => any)`	—	Replacement string (e.g. `"[Secret]"`), or a function computing the replacement from the matched value
`counting`	`boolean`	`true`	Appends `_1`, `_2`, … per string occurrence. Ignored when `replaced` is a function — its return value is used as-is.

Example — redact all strings longer than 100 characters

import { ValueRedaction } from "vitest-snap";

new ValueRedaction(
  (_, v) => typeof v === "string" && v.length > 100,
  "[LONG_STRING]",
);

Example — redact specific primitive value

new ValueRedaction((_, v) => v === "supersecret", "[REDACTED]", false);

Example — function replacement

Pass a function instead of a string to derive the replacement from the matched value. Function replacements ignore counting entirely — the returned value (any type) is used as-is.

new ValueRedaction(
  (_, v) => v instanceof Date,
  (prevValue: Date) => prevValue.getFullYear(),
);
// each Date is replaced by its year, e.g. 2024 (not counted/suffixed)

Default Date redaction

The built-in default is equivalent to:

new ValueRedaction((_, v) => v instanceof Date, "[Date]");
// produces [Date_1], [Date_2], … for each Date encountered

ReplacedRedaction

Replaces all nodes matched by a selector with a fixed placeholder string.

Constructor

new ReplacedRedaction(
  selector: Selector<T>,
  replaced: string | ((prevValue: any) => any),
  counting?: boolean,
)

Parameter	Type	Default	Description
`selector`	`Selector<T>`	—	Path expression targeting nodes to redact
`replaced`	`string \| ((prevValue) => any)`	—	Replacement string, or a function computing the replacement from the matched value
`counting`	`boolean`	`true`	Appends `_1`, `_2`, … per string occurrence. Ignored when `replaced` is a function.

Example — mask a top-level field

import { ReplacedRedaction } from "vitest-snap";

new ReplacedRedaction(".password", "[REDACTED]");

Example — mask every token in an array

new ReplacedRedaction(".sessions[].token", "[TOKEN]");

Example — fixed placeholder without counter

new ReplacedRedaction(".id", "[ID]", false);
// all .id values become "[ID]" (no _1, _2 suffix)

Example — function replacement

new ReplacedRedaction(".createdAt", (prevValue: string) =>
  prevValue.slice(0, 10),
);
// truncates the matched value to a date-only string, no counting suffix

SortedRedaction

Sorts the array at the matched path in-place (ascending, using default JS comparison). Useful for stabilizing snapshot output when the order of array elements is non-deterministic.

Constructor

new SortedRedaction(selector: Selector<T>)

Parameter	Type	Description
`selector`	`Selector<T>`	Path expression targeting an array to sort

Example — sort a top-level array of strings

import { SortedRedaction } from "vitest-snap";

const redaction = new SortedRedaction(".tags");

redaction.apply({ tags: ["banana", "apple", "cherry"] });
// → { tags: ["apple", "banana", "cherry"] }

Example — sort nested arrays

new SortedRedaction(".users[].roles");

Usage in snapshot

await expect(result).toJsonSnapshot({
  redactions: [new SortedRedaction(".items")],
});

Last updated on

Redactions

On this page