Snapshots

Use snapshot testing in Bun to capture and compare output across test runs, with support for inline snapshots, error snapshots, and property matchers.

Snapshot testing saves the serialized output of a value and compares it on future runs. This is useful for complex objects, component output, or any value that should remain stable over time.

Basic snapshots

Use .toMatchSnapshot() to capture a value:

import { test, expect } from "bun:test";

test("formats user object", () => {
  const user = { id: 1, name: "Alice", role: "admin" };
  expect(user).toMatchSnapshot();
});

On the first run, the value is serialized and written to a snapshot file. On subsequent runs, the value is compared against the stored snapshot — the test fails if they differ.

Snapshot file location

Snapshots are stored in a __snapshots__ directory alongside the test file:

your-project/
├── user.test.ts
└── __snapshots__/
    └── user.test.ts.snap

The snapshot file contents look like:

__snapshots__/user.test.ts.snap

// Bun Snapshot v1, https://bun.com/docs/test/snapshots

exports[`formats user object 1`] = `
{
  "id": 1,
  "name": "Alice",
  "role": "admin",
}
`;

Updating snapshots

When output intentionally changes, regenerate snapshots with:

bun test --update-snapshots

After updating, commit the snapshot files alongside your code changes so they are reviewed as part of the diff.

git diff __snapshots__/
git add __snapshots__/
git commit -m "update snapshots after API response shape change"

Inline snapshots

For small values, use .toMatchInlineSnapshot() to store the snapshot directly in the test file. On the first run, Bun writes the value into your test file automatically.

import { test, expect } from "bun:test";

test("formats currency", () => {
  expect(formatCurrency(99.99)).toMatchInlineSnapshot(`"$99.99"`);
});

After the first run, your test file is updated with the snapshot value filled in. Subsequent runs compare against the inline string.

Error snapshots

Capture and compare error messages with .toThrowErrorMatchingSnapshot() and .toThrowErrorMatchingInlineSnapshot():

import { test, expect } from "bun:test";

test("throws on invalid input", () => {
  expect(() => {
    parseConfig("not valid json");
  }).toThrowErrorMatchingInlineSnapshot(`"Invalid configuration: not valid json"`);
});

Advanced usage

Complex objects

Snapshots are particularly effective for deeply nested structures:

test("generates report", () => {
  const report = generateReport([
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
  ]);

  expect(report).toMatchSnapshot();
});

Property matchers

For values that change between runs (timestamps, random IDs), use property matchers to assert the shape while ignoring volatile values:

test("creates user with dynamic fields", () => {
  const user = {
    id: crypto.randomUUID(),
    name: "Alice",
    createdAt: new Date().toISOString(),
  };

  expect(user).toMatchSnapshot({
    id: expect.any(String),
    createdAt: expect.any(String),
  });
});

The snapshot stores Any<String> for the matched fields while capturing the exact value of name.

React component snapshots

Snapshots work well for testing rendered HTML output:

import { test, expect } from "bun:test";
import { render } from "@testing-library/react";

function Badge({ label, variant = "default" }: { label: string; variant?: string }) {
  return <span className={`badge badge-${variant}`}>{label}</span>;
}

test("Badge renders correctly", () => {
  const { container } = render(<Badge label="New" variant="success" />);
  expect(container.innerHTML).toMatchInlineSnapshot(
    `"<span class=\"badge badge-success\">New</span>"`
  );
});

Custom serializers

Register a custom serializer to control how a type is printed in snapshots:

import { expect } from "bun:test";

expect.addSnapshotSerializer({
  test: (val) => val instanceof Date,
  serialize: (val) => `"${val.toISOString()}"`,
});

test("event with date", () => {
  expect({
    name: "Meeting",
    date: new Date("2024-06-01T10:00:00Z"),
  }).toMatchSnapshot();
});

Troubleshooting snapshot failures

When a snapshot test fails, Bun shows a diff:

- Expected
+ Received

  Object {
-   "name": "Alice",
+   "name": "Bob",
  }

Common causes:

Cause	Solution
Intentional change	Run bun test --update-snapshots
Unintentional regression	Fix the code that produces the output
Dynamic data in snapshot	Use property matchers for volatile fields
Platform-specific formatting	Normalize values (e.g., path separators) before snapshotting

Best practices

Keep snapshots small and focused

Snapshot only the part of the output that matters to the test. Large snapshots are hard to review when they change.

// Good: snapshot a specific field
expect(response.body).toMatchInlineSnapshot(`"success"`);

// Avoid: snapshotting an entire page render
expect(renderFullPage()).toMatchSnapshot();

Handle dynamic data with property matchers

// Good: normalize volatile fields
expect(apiResponse).toMatchSnapshot({
  timestamp: expect.any(Number),
  requestId: expect.any(String),
});

// Avoid: snapshots that break on every run
expect(apiResponse).toMatchSnapshot(); // contains Date.now()

Review snapshot changes carefully

Snapshot diffs in pull requests deserve the same scrutiny as code changes. An unexpected snapshot change is often a sign of a bug.

Group snapshots with describe

Organizing snapshots inside describe blocks makes the snapshot file easier to navigate:

describe("Button", () => {
  test("primary variant", () => {
    expect(renderButton("primary")).toMatchSnapshot();
  });

  test("secondary variant", () => {
    expect(renderButton("secondary")).toMatchSnapshot();
  });
});