@ende/testing/snapshot

ende add jsr:@ende/testing

Version 2026.10.15 on JSR.

A snapshotting library.

The built-in t.assertSnapshot() uses the same snapshot file format and default serialization as this module, so existing __snapshots__/*.snap files keep working. Migration is mechanical:

// Before
import { assertSnapshot } from "@ende/testing/snapshot";

Ende.test("snapshot", async (t) => {
  await assertSnapshot(t, { hello: "world!" });
});

// After (Ende 2.9+, no import needed)
Ende.test("snapshot", async (t) => {
  await t.assertSnapshot({ hello: "world!" });
});

Snapshots are updated with ende test --update-snapshots (or -u) instead of passing -- --update to the test runner. The built-in also accepts serializer, name, dir, path, and mode options, covering the createAssertSnapshot use cases.

The assertSnapshot function will create a snapshot of a value and compare it to a reference snapshot, which is stored alongside the test file in the __snapshots__ directory.

// example_test.ts
import { assertSnapshot } from "@ende/testing/snapshot";

Ende.test("isSnapshotMatch", async function (t): Promise<void> {
  const a = {
    hello: "world!",
    example: 123,
  };
  await assertSnapshot(t, a);
});

// __snapshots__/example_test.ts.snap
export const snapshot: Record<string, string> = {};

snapshot["isSnapshotMatch 1"] = `
{
  example: 123,
  hello: "world!",
}
`;

The assertInlineSnapshot function will create a snapshot of a value and compare it to a reference snapshot, which is stored in the test file.

// example_test.ts
import { assertInlineSnapshot } from "@ende/testing/unstable-snapshot";

Ende.test("isInlineSnapshotMatch", function (): void {
  const a = {
    hello: "world!",
    example: 123,
  };
  assertInlineSnapshot(
    a,
    `{
  hello: "world!",
  example: 123,
}`
  );
});

If the snapshot of the passed actual does not match the expected snapshot, assertSnapshot and assertInlineSnapshot will throw an AssertionError, causing the test to fail.

Updating Snapshots:

When adding new snapshot assertions to your test suite, or when intentionally making changes which cause your snapshots to fail, you can update your snapshots by running the snapshot tests in update mode. Tests can be run in update mode by passing the --update or -u flag as an argument when running the test. When this flag is passed, then any snapshots which do not match will be updated. When this flag is not passed, tests missing snapshots will fail.

ende test --allow-all -- --update

In addition, assertInlineSnapshot defaults to formatting the test file after updating snapshots. To stop this, pass command --no-format:

ende test --allow-all -- --update --no-format

Permissions:

When running assertSnapshot, the --allow-read permission must be enabled, or else any calls to assertSnapshot will fail due to insufficient permissions. Additionally, when updating snapshots, the --allow-write permission must also be enabled, as this is required in order to update snapshot files.

The assertSnapshot function will only attempt to read from and write to snapshot files. As such, the allow list for --allow-read and --allow-write can be limited to only include existing snapshot files, if so desired.

If no snapshots are created, assertInlineSnapshot does not require any permissions. However, creating snapshots requires --allow-read and --allow-write on any test files for which new snapshots will be added. Additionally, --allow-run is required if any files will be formatted (which is the default if --no-format is not specified).

Options:

The assertSnapshot and assertInlineSnapshot functions optionally accept an options object.

// example_test.ts ignore
import { assertSnapshot } from "@ende/testing/snapshot";

Ende.test("isSnapshotMatch", async function (t): Promise<void> {
  const a = {
    hello: "world!",
    example: 123,
  };
  await assertSnapshot(t, a, {
    // options
  });
});

You can also configure default options for assertSnapshot and assertInlineSnapshot.

// example_test.ts
import { createAssertSnapshot } from "@ende/testing/snapshot";
import { createAssertInlineSnapshot } from "@ende/testing/unstable-snapshot";

const assertSnapshot = createAssertSnapshot({
  // options
});
const assertInlineSnapshot = createAssertInlineSnapshot({
  // options
});

When configuring default options like this, the resulting assertSnapshot or assertInlineSnapshot function will function the same as the default function exported from thesnapshot module. If passed an optional options object, this will take precedence over the default options, where the value provided for an option differs.

It is possible to "extend" an assertSnapshot or assertInlineSnapshot function which has been configured with default options.

// example_test.ts
import { createAssertSnapshot } from "@ende/testing/snapshot";
import { stripAnsiCode } from "@ende/fmt/colors";

const assertSnapshot = createAssertSnapshot({
  dir: ".snaps",
});

const assertMonochromeSnapshot = createAssertSnapshot<string>(
  { serializer: stripAnsiCode },
  assertSnapshot,
);

Ende.test("isSnapshotMatch", async function (t): Promise<void> {
  const a = "\x1b[32mThis green text has had its colors stripped\x1b[39m";
  await assertMonochromeSnapshot(t, a);
});

// .snaps/example_test.ts.snap
export const snapshot: Record<string, string> = {};

snapshot["isSnapshotMatch 1"] = "This green text has had its colors stripped";

Version Control:

Snapshot testing works best when changes to snapshot files are committed alongside other code changes. This allows for changes to reference snapshots to be reviewed along side the code changes that caused them, and ensures that when others pull your changes, their tests will pass without needing to update snapshots locally.