Odonno/vitest-snap-redact-data

vitest-snap/redact-data

Setup

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

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

Core Patterns

1. Redaction class signatures

// ValueRedaction — replace any node where predicate returns true
new ValueRedaction(
  predicate: (path: string, value: unknown) => boolean,
  replaced:  string,
  counting?: boolean,  // default: true
)

// ReplacedRedaction — replace all nodes matched by selector
new ReplacedRedaction(
  selector: Selector<T>,
  replaced: string,
  counting?: boolean,  // default: true
)

// SortedRedaction — sort array at matched path (ascending, default JS comparison)
new SortedRedaction(selector: Selector<T>)

2. Counting behaviour

When counting=true (default), the replacement string gets _1, _2, … suffixes per occurrence:

// { createdAt: new Date(), updatedAt: new Date() }
// → { "createdAt": "[Date_1]", "updatedAt": "[Date_2]" }
new ValueRedaction((_, v) => v instanceof Date, "[Date]");

// disable counting — all occurrences get the same literal string
new ReplacedRedaction(".id", "[ID]", false);
// → all .id values become "[ID]" (no suffix)

3. Default Date redaction — preserve when adding custom redactions

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

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

4. Typed selectors with Selector<T>

type User = { name: string; sessions: { token: string }[] };

new ReplacedRedaction<User>(".sessions[].token", "[TOKEN]"); // ✓ type-checked
new ReplacedRedaction<User>(".tok", "[TOKEN]"); // ✗ compile-time error

5. Traversal order

Redactions apply deepest-first (post-order). Nested nodes are replaced before their parents. This means a parent-level selector like .** will overwrite all previously redacted children.

6. Selector syntax reference

| Pattern | Meaning | | --------------- | ---------------------------------------------- | | .prop | Named property | | .prop[] | All elements of array property | | .prop[].child | Named child of each array element | | .** | Deep wildcard — all descendants including root |

Common Mistakes

CRITICAL: Custom redactions array silently removes default Date redaction

Wrong:

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

Correct:

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

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

Providing redactions: [...] completely replaces the default [new ValueRedaction(isDate, "[Date]")]. Dates become raw serialized strings in the snapshot, causing flaky tests on every run.

Source: src/options/index.ts — DEFAULT_OPTIONS

HIGH: Expecting replacement string to be literal when counting=true

Wrong:

// expects "[Date]" in snapshot — actual value is "[Date_1]"
new ValueRedaction((_, v) => v instanceof Date, "[Date]");

Correct:

// pass counting=false to get the literal string
new ValueRedaction((_, v) => v instanceof Date, "[Date]", false);

counting=true (default) transforms "[Date]" into "[Date_1]", "[Date_2]", etc. Asserting the literal replacement string will always see mismatches on the first occurrence.

Source: src/redactions/counting.ts; src/redactions/index.ts

HIGH: ReplacedRedaction with .** selector replaces the root object

Wrong:

// intending to redact all nodes — actually replaces the root
new ReplacedRedaction(".**", "[REDACTED]");
// result: "[REDACTED_N]" — entire object gone

Correct:

// use ValueRedaction with a predicate to target specific value types
new ValueRedaction((_, v) => typeof v === "string", "[REDACTED]");

The .** deep segment matches ALL nodes including the root (path=[]). With deepest-first ordering, the root is replaced last, overwriting the entire result.

Source: src/functions/object.ts — match deep case

HIGH: Using untyped selector strings — missing Selector<T> inference

Wrong:

// ".sesions[].token" is a silent no-op at runtime
new ReplacedRedaction(".sesions[].token", "[TOKEN]");

Correct:

type User = { sessions: { token: string }[] };
new ReplacedRedaction<User>(".sessions[].token", "[TOKEN]");

Without the generic argument, a typo becomes a silent runtime no-op instead of a compile-time error.

Source: src/selectors/index.ts

MEDIUM: SortedRedaction applied to non-array path is a silent no-op

Wrong:

new SortedRedaction(".tag"); // .tag is a string, not an array

Correct:

new SortedRedaction(".tags"); // ensure selector points to an array

sortAtPath returns the value unchanged when it is not an array. No error is thrown; a typo silently produces an unsorted snapshot.

Source: src/functions/object.ts — sortAtPath

Behaviour Reference

| Class | Mutates input | Counting default | Silent on miss | | ------------------- | ------------- | ---------------- | --------------------- | | ValueRedaction | No (clones) | true | N/A (predicate-based) | | ReplacedRedaction | No (clones) | true | Yes | | SortedRedaction | No (clones) | N/A | Yes |

Execution Order

Redactions within the redactions array are applied sequentially in array order, each on the result of the previous. Within each redaction, nodes are visited deepest-first.

input → redaction[0].apply() → redaction[1].apply() → ... → serialized snapshot