#从 Jest 迁移

Rstest 提供兼容 Jest 的 API，这使得从 Jest 项目迁移变得简单。以下是如何将你的 Jest 项目迁移到 Rstest：

#使用 Agent Skills

如果你在使用支持 Skills 的 Coding Agent，可以安装 migrate-to-rstest 技能来辅助完成从 Jest 到 Rstest 的迁移。

npx skills add rstackjs/agent-skills --skill migrate-to-rstest

安装后，让 Coding Agent 协助完成升级即可。

#安装依赖

首先，你需要安装 Rstest 依赖。

npm add @rstest/core -D

yarn add @rstest/core -D

pnpm add @rstest/core -D

bun add @rstest/core -D

deno add npm:@rstest/core -D

接下来，更新 package.json 中的测试脚本，使用 rstest 替代 jest。例如：

"scripts": {
-  "test": "jest"
+  "test": "rstest"
}

#CLI 参数映射

Jest 的一部分 CLI 参数可以直接映射到 Rstest，另一部分则需要迁移到配置文件中。迁移时，最常遇到的差异可以参考下表：

#配置迁移

将你的 Jest 配置文件（例如 jest.config.js 或 jest.config.ts）更新为 rstest.config.ts 文件：

import { defineConfig } from '@rstest/core';

export default defineConfig({
  // 根据下方映射表，从 jest.config.js 中逐字段迁移到这里。
});

#Jest 配置映射

迁移时，请遍历 jest.config.js 中的每一个字段，对照下表进行映射、重组或删除。表中未列出的字段未必能 1:1 映射，直接删除前请先对照 Rstest 配置参考 确认。

更多详情，请参考 配置文档。

#注入全局 API

与 Jest 不同，Rstest 默认不会将测试 API（如 describe、expect、it、test）挂载到全局对象上。

如果你希望继续使用全局测试 API，可以在 rstest.config.ts 文件中启用 globals 选项：

import { defineConfig } from '@rstest/core';

export default defineConfig({
  globals: true,
});

为了让 TypeScript 正确识别这些全局 API，请在 tsconfig.json 中添加 @rstest/core/globals 类型声明：

{
  "compilerOptions": {
    "types": ["@rstest/core/globals"]
  }
}

#代码转换

Rstest 默认使用 swc 进行代码转换，这与 Jest 的 babel-jest 不同。大多数情况下，你不需要做任何更改。你可以通过 tools.swc 配置你的 swc 选项。

export default {
-  transform: {
-    '^.+\\.(t|j)sx?$': ['@swc/jest', {}],
-  },
+  tools: {
+    swc: {}
+  }
}

如果你有自定义的 Babel 配置或使用特定的 Babel 插件/预设，你可以添加 Rsbuild Babel 插件：

import { pluginBabel } from '@rsbuild/plugin-babel';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  plugins: [pluginBabel()],
});

#更新测试 API

#测试 API

Rstest 提供了与 Jest 兼容的 API。因此，你只需将导入从 Jest 更改为 Rstest：

- import { describe, expect, it, test } from '@jest/globals';
+ import { describe, expect, it, test } from '@rstest/core';

Rstest 提供了 rstest API，你可以使用它来访问 Rstest 的工具函数，如 rstest.fn() 和 rstest.mock()。就像 Jest 的 jest.fn() 和 jest.mock() 一样。更多工具函数可以在 Rstest APIs 中找到。

- const fn = jest.fn();
+ const fn = rstest.fn();

fn.mockResolvedValue('foo');

#Done 回调

Rstest 不支持 done 回调。作为替代，你可以返回一个 Promise 或使用 async/await 进行异步测试。

- test('async test with done', (done) => {
+ test('async test with done', () => new Promise(done => {
  // ...
  done();
- });
+ }));

如果你需要处理错误，你可以按照以下方式修改：

- test('async test with done', (done) => {
+ test('async test with done', () => new Promise((resolve, reject) => {
+   const done = err => (err ? reject(err) : resolve());
  // ...
  done(error);
- });
+ }));

#Hooks

Rstest 中 beforeEach 和 beforeAll 钩子的返回函数用于执行测试后的清理工作。

- beforeEach(() => doSomething());
+ beforeEach(() => { doSomething() });

#超时设置

如果你使用 jest.setTimeout() 来设置测试的超时时间，你可以改用 rstest.setConfig()。

- jest.setTimeout(5_000)
+ rstest.setConfig({ testTimeout: 5_000 })

#Snapshot 格式

Rstest 的 snapshot key 格式与 Jest 不同。原有的 Jest snapshot 文件在 Rstest 首次运行时不会匹配，snapshot body 本身不变，仅 key 的书写形式不同。

#Key 分隔符变化

Jest 用 : 把 suite 名、测试名、snapshot label 拼成一行，Rstest 用 >：

- overlay should not show a warning when "client.overlay.warnings" is "false": page html 1
+ overlay > should not show a warning when "client.overlay.warnings" is "false" > page html 1

上例中各部分含义：

1. overlay —— suite 名（describe(...)）。
2. should not show a warning when "client.overlay.warnings" is "false" —— 测试名（it(...) / test(...)）。
3. page html —— .toMatchSnapshot('page html') 中的 label。
4. 1 —— 该 label 在该测试中的 snapshot 序号。

#更新 snapshot

rstest -u 会按 Rstest 的 key 格式重录 snapshot：

rstest -u                # 全量更新
rstest overlay -u        # 只更新过滤范围

#Diff 审查

迁移之后，snapshot 文件里的大多数变化都是非功能性的：

• 仅分隔符变化的 key rename 属于格式变化，不是行为变化。
• key 顺序变动、但 body 无 diff 同样属于纯格式变化。
• 只有 key 不变、body 内容变了，才是真实的行为变化。

#ESM 和 CJS

Rstest 默认支持 ESM。如果你的项目使用 ESM，你不需要进行任何额外配置（例如设置 NODE_OPTIONS=--experimental-vm-modules）。

如果你的项目仍在使用 CommonJS，Rstest 仍然可以正常工作，但我们建议迁移到 ESM，以获得更好的性能和未来的兼容性。

#ESM vs CJS mocking

在 Rstest 中，rstest.mock() 针对 import 使用的 ESM 入口，而 rstest.mockRequire() 针对 require() 使用的 CJS 入口。

代码中使用 require() 时，rstest.mockRequire() 对应 CJS 入口的 mock：

// Mock 一个 CJS 模块
rstest.mockRequire('./math.cjs', () => ({
  sum: (a, b) => a + b + 100,
}));