bun-jest-migration

用途

bun-jest-migration 面向需要把现有 Jest 测试迁移到 Bun 测试运行器的场景，提供导入方式、Mock、定时器、快照与配置的迁移指引。资料说明 Bun 的测试运行器与 Jest 兼容，大多数 Jest 测试无需改动即可运行。

主要能力

快速迁移流程：移除 Jest 依赖、更新 test 脚本、运行 bun test。
导入变更说明：从 @jest/globals 改为 bun:test，或直接使用全局 API。
API 兼容性对照，区分「完全兼容」与「需要改动」两类。
Mock 迁移：Mock 函数、模块 Mock、Spy。
定时器迁移与日期模拟。
快照测试与更新命令。
配置迁移：jest.config.js 转为 bunfig.toml。
常见迁移问题与错误排查。

使用方式

快速迁移三步：

# 1. 移除 Jest 依赖
bun remove jest ts-jest @types/jest babel-jest

# 2. 更新测试脚本
# package.json: "test": "bun test"

# 3. 运行测试
bun test

导入变更：

// Before (Jest)
import { describe, it, expect, jest } from '@jest/globals';

// After (Bun) - No import needed, or explicit:
import { describe, test, expect, mock, spyOn } from "bun:test";

完整迁移步骤：

移除 Jest 包：bun remove jest ts-jest @types/jest babel-jest jest-environment-jsdom
更新 package.json：

{
  "scripts": {
    "test": "bun test",
    "test:watch": "bun test --watch",
    "test:coverage": "bun test --coverage"
  }
}

将 jest.config.js 转换为 bunfig.toml：

[test]
root = "./"
preload = ["./jest.setup.ts"]
timeout = 10000
coverage = true
coverageThreshold = 0.8

更新测试文件导入：将 @jest/globals 替换为 bun:test，将 jest.fn() 替换为 mock()，将 jest.mock() 替换为 mock.module()。
运行并修复：bun test 2>&1 | head -50。

API 兼容性

完全兼容：describe()、it() / test()（推荐使用 test()）、expect()（相同匹配器）、beforeAll/Each、afterAll/Each、jest.spyOn() 对应 spyOn()。

需要改动：

Jest	Bun 对应
jest.mock('module')	mock.module('module', () => {...})
jest.useFakeTimers()	import { setSystemTime } from "bun:test"
jest.setTimeout()	test() 的第三个参数
jest.clearAllMocks()	对每个 mock 调用 .mockClear()

Mock 迁移示例：

// Jest
const fn = jest.fn().mockReturnValue('value');

// Bun
const fn = mock(() => 'value');
// 或保持兼容：
import { jest } from "bun:test";
const fn = jest.fn(() => 'value');

模块 Mock：

// Jest (top-level hoisting)
jest.mock('./utils', () => ({
  helper: jest.fn(() => 'mocked')
}));

// Bun (inline, no hoisting)
import { mock } from "bun:test";
mock.module('./utils', () => ({
  helper: mock(() => 'mocked')
}));

Spy 迁移：

// Jest
jest.spyOn(console, 'log').mockImplementation(() => {});

// Bun (identical)
spyOn(console, 'log').mockImplementation(() => {});

定时器迁移：

// Jest
jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01'));
jest.advanceTimersByTime(1000);

// Bun - supports Jest-compatible timer APIs
import { setSystemTime } from "bun:test";
import { jest } from "bun:test";

jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01'));
jest.advanceTimersByTime(1000);  // Now supported

快照测试：Bun 与 Jest 写法一致，使用 bun test --update-snapshots 更新快照。

自定义匹配器：Bun 使用与 Jest 相同的 expect.extend API。

适用场景

项目从 Jest 切换到 Bun 测试运行器时的迁移。
需要对照 Jest 与 Bun 的 API 差异进行改造。
需要将 jest.config.js 转为 bunfig.toml，或排查迁移中的常见错误（如 Cannot find module '@jest/globals'、jest is not defined、mock.module is not a function、快照不匹配等）。

限制

Bun 不存在 Jest 的 mock 顶层提升（hoisting），jest.mock 需改为 mock.module 并调整书写位置或使用动态 import。
部分定时器功能支持有限，可使用 setSystemTime 进行日期模拟。
快照序列化方式不同可能导致不匹配，需要 --update-snapshots 更新。
资料来源提到可加载 references/compatibility-matrix.md 获取完整 Jest API 兼容细节、不支持特性列表与替代方案，但该参考文件的具体内容在当前资料中暂未提供。

技能介绍

用途

主要能力

使用方式

API 兼容性

适用场景

限制