快照测试 - Bun 中文文档

快照测试保存一个值的输出，并与未来的测试运行进行比较。这对于 UI 组件、复杂对象或任何需要保持一致的输出特别有用。

基本快照

快照测试使用 .toMatchSnapshot() 匹配器编写：

https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217

test.ts

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

test("snap", () => {
  expect("foo").toMatchSnapshot();
});

首次运行此测试时，传递给 expect 的参数会被序列化并写入与测试文件同级的 __snapshots__ 目录下的特殊快照文件中。

快照文件

运行上述测试后，Bun 会创建：

目录结构

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

快照文件内容如下：

__snapshots__/snap.test.ts.snap

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

exports[`snap 1`] = `"foo"`;

后续运行时，传入的值会与磁盘上的快照进行对比。

更新快照

可以使用以下命令重新生成快照：

terminal

bun test --update-snapshots

这在以下情况有用：

你有意更改了输出
你添加了新的快照测试
预期输出确实发生了变化

内联快照

对于较小的值，可以使用 .toMatchInlineSnapshot() 进行内联快照。这些快照直接存储在测试文件中：

test.ts

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

test("inline snapshot", () => {
  // 首次运行：快照将自动插入
  expect({ hello: "world" }).toMatchInlineSnapshot();
});

首次运行后，Bun 会自动更新你的测试文件：

test.ts

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

test("inline snapshot", () => {
  expect({ hello: "world" }).toMatchInlineSnapshot(`
{
  "hello": "world",
}
`);
});

使用内联快照步骤

编写包含 .toMatchInlineSnapshot() 的测试
运行测试一次
Bun 会自动更新测试文件，插入快照
后续运行时，值会与内联快照比较

内联快照特别适合用于小而简单的值，方便在测试文件中直接查看预期输出。

错误快照

你也可以使用 .toThrowErrorMatchingSnapshot() 和 .toThrowErrorMatchingInlineSnapshot() 来快照错误消息：

test.ts

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

test("error snapshot", () => {
  expect(() => {
    throw new Error("Something went wrong");
  }).toThrowErrorMatchingSnapshot();

  expect(() => {
    throw new Error("Another error");
  }).toThrowErrorMatchingInlineSnapshot();
});

运行后，内联版本变为：

test.ts

test("error snapshot", () => {
  expect(() => {
    throw new Error("Something went wrong");
  }).toThrowErrorMatchingSnapshot();

  expect(() => {
    throw new Error("Another error");
  }).toThrowErrorMatchingInlineSnapshot(`"Another error"`);
});

高级快照用法

复杂对象

快照适用于复杂的嵌套对象：

test.ts

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

test("complex object snapshot", () => {
  const user = {
    id: 1,
    name: "John Doe",
    email: "[email protected]",
    profile: {
      age: 30,
      preferences: {
        theme: "dark",
        notifications: true,
      },
    },
    tags: ["developer", "javascript", "bun"],
  };

  expect(user).toMatchSnapshot();
});

数组快照

数组同样适合快照测试：

test.ts

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

test("array snapshot", () => {
  const numbers = [1, 2, 3, 4, 5].map(n => n * 2);
  expect(numbers).toMatchSnapshot();
});

函数输出快照

快照函数的返回值：

test.ts

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

function generateReport(data: any[]) {
  return {
    total: data.length,
    summary: data.map(item => ({ id: item.id, name: item.name })),
    timestamp: "2024-01-01", // 测试时固定值
  };
}

test("report generation", () => {
  const data = [
    { id: 1, name: "Alice", age: 30 },
    { id: 2, name: "Bob", age: 25 },
  ];

  expect(generateReport(data)).toMatchSnapshot();
});

React 组件快照

快照对 React 组件特别有用：

test.ts

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

function Button({ children, variant = "primary" }) {
  return <button className={`btn btn-${variant}`}>{children}</button>;
}

test("Button component snapshots", () => {
  const { container: primary } = render(<Button>Click me</Button>);
  const { container: secondary } = render(<Button variant="secondary">Cancel</Button>);

  expect(primary.innerHTML).toMatchSnapshot();
  expect(secondary.innerHTML).toMatchSnapshot();
});

属性匹配器

对于在测试运行间会变化的值（比如时间戳或 ID），使用属性匹配器：

test.ts

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

test("snapshot with dynamic values", () => {
  const user = {
    id: Math.random(), // 每次运行都会变
    name: "John",
    createdAt: new Date().toISOString(), // 也会变化
  };

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

快照将保存为：

快照文件

exports[`snapshot with dynamic values 1`] = `
{
  "createdAt": Any<String>,
  "id": Any<Number>,
  "name": "John",
}
`;

自定义序列化器

你可以自定义对象在快照中的序列化方式：

test.ts

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

// Date 对象的自定义序列化器
expect.addSnapshotSerializer({
  test: val => val instanceof Date,
  serialize: val => `"${val.toISOString()}"`,
});

test("custom serializer", () => {
  const event = {
    name: "Meeting",
    date: new Date("2024-01-01T10:00:00Z"),
  };

  expect(event).toMatchSnapshot();
});

最佳实践

保持快照文件简洁

test.ts

// 推荐：聚焦的快照
test("user name formatting", () => {
  const formatted = formatUserName("john", "doe");
  expect(formatted).toMatchInlineSnapshot(`"John Doe"`);
});

// 避免：冗长难以审查的快照
test("entire page render", () => {
  const page = renderEntirePage();
  expect(page).toMatchSnapshot(); // 可能有数千行
});

使用描述性测试名称

test.ts

// 推荐：清晰说明快照代表的内容
test("formats currency with USD symbol", () => {
  expect(formatCurrency(99.99)).toMatchInlineSnapshot(`"$99.99"`);
});

// 避免：测试意图不明确
test("format test", () => {
  expect(format(99.99)).toMatchInlineSnapshot(`"$99.99"`);
});

分组相关快照

test.ts

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

describe("Button component", () => {
  test("primary variant", () => {
    expect(render(<Button variant="primary">Click</Button>))
      .toMatchSnapshot();
  });

  test("secondary variant", () => {
    expect(render(<Button variant="secondary">Cancel</Button>))
      .toMatchSnapshot();
  });

  test("disabled state", () => {
    expect(render(<Button disabled>Disabled</Button>))
      .toMatchSnapshot();
  });
});

处理动态数据

test.ts

// 推荐：标准化动态数据
test("API response format", () => {
  const response = {
    data: { id: 1, name: "Test" },
    timestamp: Date.now(),
    requestId: generateId(),
  };

  expect({
    ...response,
    timestamp: "TIMESTAMP",
    requestId: "REQUEST_ID",
  }).toMatchSnapshot();
});

// 或使用属性匹配器
test("API response with matchers", () => {
  const response = getApiResponse();

  expect(response).toMatchSnapshot({
    timestamp: expect.any(Number),
    requestId: expect.any(String),
  });
});

管理快照

复查快照变更

当快照发生变化时，需仔细检查：

terminal

# 查看变更内容
git diff __snapshots__/

# 若变更是预期，则更新快照
bun test --update-snapshots

# 提交更新后的快照
git add __snapshots__/
git commit -m "Update snapshots after UI changes"

清理未使用的快照

Bun 会提示未使用的快照：

警告

Warning: 1 unused snapshot found:
  my-test.test.ts.snap: "old test that no longer exists 1"

通过删除快照文件中的对应快照或使用可用的清理标志运行测试来移除未使用的快照。

组织大型快照文件

对于大型项目，建议合理组织测试以保持快照文件可管理：

目录结构

tests/
├── components/
│   ├── Button.test.tsx
│   └── __snapshots__/
│       └── Button.test.tsx.snap
├── utils/
│   ├── formatters.test.ts
│   └── __snapshots__/
│       └── formatters.test.ts.snap

故障排除

快照失败

当快照不匹配时，会看到差异视图：

diff

- Expected
+ Received

  Object {
-   "name": "John",
+   "name": "Jane",
  }

常见原因：

有意更改（使用 --update-snapshots 更新）
无意更改（修正代码）
动态数据（使用属性匹配器）
环境差异（标准化数据）

平台差异

注意平台间的差异：

test.ts

// Windows 与 Unix 路径可能不同
test("file operations", () => {
  const result = processFile("./test.txt");

  expect({
    ...result,
    path: result.path.replace(/\\/g, "/"), // 统一路径格式
  }).toMatchSnapshot();
});

Documentation Index

​基本快照

​快照文件

​更新快照

​内联快照

​使用内联快照步骤

​错误快照

​高级快照用法

​复杂对象

​数组快照

​函数输出快照

​React 组件快照

​属性匹配器

​自定义序列化器

​最佳实践

​保持快照文件简洁

​使用描述性测试名称

​分组相关快照

​处理动态数据

​管理快照

​复查快照变更

​清理未使用的快照

​组织大型快照文件

​故障排除

​快照失败

​平台差异

基本快照

快照文件

更新快照

内联快照

使用内联快照步骤

错误快照

高级快照用法

复杂对象

数组快照

函数输出快照

React 组件快照

属性匹配器

自定义序列化器

最佳实践

保持快照文件简洁

使用描述性测试名称

分组相关快照

处理动态数据

管理快照

复查快照变更

清理未使用的快照

组织大型快照文件

故障排除

快照失败

平台差异