Odonno/vitest-snap-filter-data

vitest-snap/filter-data

Setup

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

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

Core Patterns

1. Filter classes and their behaviour

// UndefinedFilter — removes undefined props at any depth (default)
new UndefinedFilter();
// { a: 1, b: undefined } → { a: 1 }

// NullFilter — removes null props at any depth
new NullFilter();
// { a: 1, b: null } → { a: 1 }

// ExcludeFilter — removes nodes matched by selector
new ExcludeFilter(".password");
// ExcludeFilter with nested path
new ExcludeFilter(".metadata.internalId");
// ExcludeFilter — exclude field from every array element
new ExcludeFilter(".users[].token");

// IncludeFilter — keeps ONLY matched nodes (allowlist)
new IncludeFilter(".name"); // single selector
new IncludeFilter([".id", ".name", ".email"]); // multiple selectors

2. Bare selector string shorthand (IncludeFilter)

Adjacent bare Selector<T> strings in the filters array are auto-merged into a single IncludeFilter:

await expect(user).toJsonSnapshot({
  filters: [".id", ".name", ".email"],
  // equivalent to: [new IncludeFilter([".id", ".name", ".email"])]
});

3. Typed selectors with Selector<T>

type User = { name: string; address: { city: string; zip: string } };

new ExcludeFilter<User>(".address.city"); // ✓ type-checked
new ExcludeFilter<User>(".missing"); // ✗ compile-time type error

Selector syntax reference:

| Selector | Matches | | ------------- | ------------------------- | | .key | Property key | | .a.b.c | Nested path | | [n] | Array index n | | [] | All array items | | [start:end] | Array slice | | .* | All object keys | | .** | All descendants | | .**.key | All key fields anywhere |

4. Preserve defaults when adding custom filters

Always re-add UndefinedFilter when providing a custom filters array:

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

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

Common Mistakes

HIGH: Custom filters array silently removes default UndefinedFilter

Wrong:

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

Correct:

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

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

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

Source: src/options/index.ts — DEFAULT_OPTIONS; maintainer interview

HIGH: Using IncludeFilter when ExcludeFilter is needed

Wrong:

// removes ALL fields except .name — likely unintended
filters: [new IncludeFilter(".name")];

Correct:

// removes only .password, keeps everything else
filters: [new ExcludeFilter(".password")];

IncludeFilter is an allowlist — it removes everything not listed. For removing one field while keeping all others, use ExcludeFilter.

Source: docs/content/docs/filters.mdx

HIGH: Non-adjacent IncludeFilters not merged — unexpected sequential filtering

Wrong:

filters: [
  new IncludeFilter(".a"),
  new ExcludeFilter(".a"), // breaks adjacency
  new IncludeFilter(".b"), // runs on nearly empty object
];

Correct:

// reorder so IncludeFilters are adjacent
filters: [new IncludeFilter([".a", ".b"]), new ExcludeFilter(".a")];

regroupFilters only merges adjacent IncludeFilter instances. A non-IncludeFilter between them breaks adjacency; the second IncludeFilter receives an already-stripped object.

Source: src/options/index.ts — regroupFilters

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

Wrong:

// ".passwrod" is a silent no-op at runtime
new ExcludeFilter(".passwrod");

Correct:

type User = { name: string; password: string };
// ".passwrod" would be a compile-time type error
new ExcludeFilter<User>(".password");

Selector<T> computes all valid paths at compile time. Without the generic argument, a typo becomes a silent runtime no-op instead of a type error.

Source: src/selectors/index.ts; maintainer interview

MEDIUM: Expecting NullFilter/UndefinedFilter to remove array slots

Wrong:

// expecting [1, 3] — gets [1, null, 3]
new NullFilter().apply({ items: [1, null, 3] });

Correct:

// null inside arrays stays; use ExcludeFilter with index if needed
new ExcludeFilter(".items[1]").apply({ items: [1, null, 3] });

unsetAtPath is called with allowArrayUnset=false for value-based filters; null/undefined inside arrays are kept as-is. Only object properties are deleted.

Source: src/functions/object.ts — unsetAtPath