Bun 2.0 实战：原生 TypeScript 测试框架与快照测试最佳实践

安装 Bun 2.0

使用官方安装脚本快速安装 Bun：

# macOS/Linux 一键安装
curl -fsSL https://bun.com/install | bash

# 验证安装版本（确保≥2.0）
bun --version

# Windows 用户使用 PowerShell
powershell -c "irm bun.com/install.ps1 | iex"

安装完成后，Bun 会自动添加到 PATH。如需手动配置，将 ~/.bun/bin 加入环境变量。

初始化项目与类型配置

创建新项目并配置 TypeScript 类型支持：

# 初始化项目
mkdir bun-test-demo && cd bun-test-demo
bun init -y

# 安装 Bun 类型定义（开发依赖）
bun add -d bun-types

创建或更新 tsconfig.json，启用严格模式并配置路径别名：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["bun-types"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@test/*": ["test/*"]
    }
  },
  "include": ["src/**/*", "test/**/*"],
  "exclude": ["node_modules"]
}

编写第一个测试

创建测试目录结构：

mkdir -p src test
# 创建示例被测试函数
echo 'export const add = (a: number, b: number): number => a + b;' > src/math.ts

编写测试文件 test/math.test.ts：

import { test, expect, describe } from "bun:test";
import { add } from "../src/math";

// 基础测试
test("add 函数计算 2+2 等于 4", () => {
  expect(add(2, 2)).toBe(4);
});

test("add 函数处理负数", () => {
  expect(add(-1, -1)).toBe(-2);
  expect(add(-5, 10)).toBe(5);
});

// 使用 describe 组织测试组
describe("add 函数边界测试", () => {
  test("处理极大数值", () => {
    const max = Number.MAX_SAFE_INTEGER;
    expect(() => add(max, 1)).toThrow();
  });

  test("处理小数", () => {
    expect(add(1.5, 2.5)).toBe(4);
  });
});

运行测试：

# 运行所有测试
bun test

# 运行特定文件
bun test test/math.test.ts

# 详细输出模式
bun test --reporter=verbose

快照测试实战

快照测试适用于 UI 组件、复杂对象、API 响应等场景。Bun 的快照测试与 Jest API 兼容：

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

// 测试用户对象结构
test("用户对象快照", () => {
  const user = {
    id: "usr_123",
    name: "张三",
    email: "zhangsan@example.com",
    role: "admin",
    permissions: ["read", "write", "delete"],
    metadata: {
      createdAt: "2026-03-02",
      lastLogin: null,
      settings: { theme: "dark", lang: "zh-CN" }
    }
  };

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

// 测试格式化输出
test("日志格式化快照", () => {
  const logEntry = {
    level: "INFO",
    timestamp: "2026-03-02T10:30:00Z",
    message: "用户登录成功",
    context: { userId: "usr_123", ip: "192.168.1.1" }
  };

  const formatted = JSON.stringify(logEntry, null, 2);
  expect(formatted).toMatchSnapshot();
});

首次运行会生成快照文件 test/__snapshots__/math.test.ts.snap：

# 运行测试生成快照
bun test

# 查看生成的快照
cat test/__snapshots__/math.test.ts.snap

后续运行会自动比对快照，发现差异时失败：

# 更新快照（谨慎使用）
bun test --update-snapshot

# 或交互模式审查差异
bun test --update-snapshot=interactive

Mock 与生命周期钩子

Bun 提供完整的 Mock 支持和生命周期钩子：

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

describe("API 服务测试", () => {
  // Mock 外部 API
  const fetchMock = mock.fn(() =>
    Promise.resolve({
      ok: true,
      json: () => Promise.resolve({ data: "mocked" })
    })
  );

  // 全局 Mock
  mock.module("undici", () => ({
    fetch: fetchMock
  }));

  // 每个测试前执行
  beforeEach(() => {
    fetchMock.mock.calls = []; // 清空调用记录
    console.log("准备测试环境");
  });

  // 每个测试后执行
  afterEach(() => {
    console.log("清理测试环境");
  });

  test("调用外部 API", async () => {
    const response = await fetchMock("https://api.example.com/data");
    expect(response.ok).toBe(true);
    expect(fetchMock.mock.calls.length).toBe(1);
  });

  // Mock 定时器
  test("定时任务", () => {
    mock.timers.enable();

    const callback = mock.fn();
    setTimeout(callback, 1000);

    mock.timers.tick(1000);
    expect(callback.mock.calls.length).toBe(1);

    mock.timers.disable();
  });
});

并发测试与性能优化

Bun 测试支持并发执行，大幅提升大型测试套件速度：

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

// 标记测试可并发执行
describe("并发测试组", { concurrent: true }, () => {
  test("独立测试 A", async () => {
    await new Promise(r => setTimeout(r, 100));
    expect(1).toBe(1);
  });

  test("独立测试 B", async () => {
    await new Promise(r => setTimeout(r, 100));
    expect(2).toBe(2);
  });

  test("独立测试 C", async () => {
    await new Promise(r => setTimeout(r, 100));
    expect(3).toBe(3);
  });
});

// 跳过特定测试
test.skip("待实现的测试", () => {
  // 暂时跳过
});

// 仅运行此测试（调试用）
test.only("焦点测试", () => {
  // 其他测试会被跳过
});

性能对比命令：

# 串行执行
bun test --no-concurrent

# 并发执行（默认）
bun test --concurrent

# 查看测试耗时
bun test --reporter=verbose --timing

CI/CD 集成实战

在 GitHub Actions 中配置 Bun 测试流水线：

# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install

      - name: Run tests with coverage
        run: bun test --coverage --reporter=junit

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: junit.xml

在 bunfig.toml 中配置测试选项：

[test]
# 测试文件匹配模式
root = "test"
pattern = "**/*.test.ts"

# 覆盖率配置
coverage = true
coverage-dir = "./coverage"
coverage-reporters = ["lcov", "text"]

# 超时设置（毫秒）
timeout = 5000

# 并发控制
concurrent = true