Skip to content

docs: update jest api alternative #603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 29, 2025
Merged

docs: update jest api alternative #603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 56 additions & 17 deletions website/docs/en/guide/migration/jest.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,24 +31,28 @@ export default defineConfig({
});
```

### Jest configuration mappings

Here are some common Jest configurations and their Rstest equivalents:

| Jest Configuration | Rstest Equivalent |
| ---------------------------- | --------------------------------------------------------------------- |
| `testRegex` | [`include`](/config/test/include) |
| `testMatch` | [`include`](/config/test/include) |
| `testPathIgnorePatterns` | [`exclude`](/config/test/exclude) |
| `transformIgnorePatterns` | [`source.exclude`](/config/build/source#sourceexclude) |
| `displayName` | [`name`](/config/test/name) |
| `rootDir` | [`root`](/config/test/root) |
| `verbose` | [`verbose-reporter`](/config/test/reporters#verbose-reporter) |
| `injectGlobals` | [`globals`](/config/test/globals) |
| `moduleNameMapper` | [`resolve.alias`](/config/build/resolve#resolvealias) |
| `collectCoverage` | [`coverage.enabled`](/config/test/coverage#enabled) |
| `coverageDirectory` | [`coverage.reportsDirectory`](/config/test/coverage#reportsdirectory) |
| `coverageProvider` | [`coverage.provider`](/config/test/coverage#provider) |
| `coveragePathIgnorePatterns` | [`coverage.exclude`](/config/test/coverage#exclude) |
| `coverageThreshold` | [`coverage.thresholds`](/config/test/coverage#thresholds) |
| Jest Configuration | Rstest Equivalent |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `testRegex` | [`include`](/config/test/include) |
| `testMatch` | [`include`](/config/test/include) |
| `testPathIgnorePatterns` | [`exclude`](/config/test/exclude) |
| `transformIgnorePatterns` | [`output.externals`](/config/build/output#outputexternals)、[`source.exclude`](/config/build/source#sourceexclude) |
Copy link

Copilot AI Sep 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using Chinese punctuation '、' in English documentation. Should use comma ',' or 'and' to separate the two configuration options.

Suggested change
| `transformIgnorePatterns` | [`output.externals`](/config/build/output#outputexternals)、[`source.exclude`](/config/build/source#sourceexclude) |
| `transformIgnorePatterns` | [`output.externals`](/config/build/output#outputexternals), [`source.exclude`](/config/build/source#sourceexclude) |

Copilot uses AI. Check for mistakes.
| `displayName` | [`name`](/config/test/name) |
| `rootDir` | [`root`](/config/test/root) |
| `setupFilesAfterEnv` | [`setupFiles`](/config/test/setupFiles) |
| `verbose` | [`verbose-reporter`](/config/test/reporters#verbose-reporter) |
| `injectGlobals` | [`globals`](/config/test/globals) |
| `moduleNameMapper` | [`resolve.alias`](/config/build/resolve#resolvealias) |
| `maxWorkers` | [`pool.maxWorkers`](/config/test/pool) |
| `collectCoverage` | [`coverage.enabled`](/config/test/coverage#enabled) |
| `coverageDirectory` | [`coverage.reportsDirectory`](/config/test/coverage#reportsdirectory) |
| `coverageProvider` | [`coverage.provider`](/config/test/coverage#provider) |
| `coveragePathIgnorePatterns` | [`coverage.exclude`](/config/test/coverage#exclude) |
| `coverageThreshold` | [`coverage.thresholds`](/config/test/coverage#thresholds) |

For more details, please refer to the [Configuration](/config) section.

Expand All @@ -68,7 +72,18 @@ export default defineConfig({

### Code transformation

Rstest uses `swc` for code transformation by default, which is different from Jest's `babel-jest`. Most of the time, you don't need to change anything.
Rstest uses `swc` for code transformation by default, which is different from Jest's `babel-jest`. Most of the time, you don't need to change anything. And you can configure your swc options through [tools.swc](/config/build/tools#toolsswc).

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

However, if you have custom Babel configurations or use specific Babel plugins/presets, you can add [Rsbuild's Babel Plugin](https://rsbuild.rs/plugins/list/plugin-babel):

Expand All @@ -83,6 +98,8 @@ export default defineConfig({

## Update test API

### Test API

Your existing Jest test files should work with minimal changes since Rstest provides Jest-compatible APIs. Simply update your imports from Jest to Rstest:

```diff
Expand All @@ -98,3 +115,25 @@ Rstest provides a `rstest` API that you can use to access Rstest's utilities, su

fn.mockResolvedValue('foo');
```

### Done callback

The `done` callback is not supported in Rstest. Instead, you can return a Promise or use `async/await` for asynchronous tests.

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

### Timeout

If you used `jest.setTimeout()` to set the timeout for a test, you can use `rstest.setConfig()` instead.

```diff
- jest.setTimeout(5_000)
+ rstest.setConfig({ testTimeout: 5_000 })
```
73 changes: 56 additions & 17 deletions website/docs/zh/guide/migration/jest.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,24 +31,28 @@ export default defineConfig({
});
```

### Jest 配置映射

以下是一些常见的 Jest 配置及其对应的 Rstest 配置：

| Jest 配置 | Rstest 对等配置 |
| ---------------------------- | --------------------------------------------------------------------- |
| `testRegex` | [`include`](/config/test/include) |
| `testMatch` | [`include`](/config/test/include) |
| `testPathIgnorePatterns` | [`exclude`](/config/test/exclude) |
| `transformIgnorePatterns` | [`source.exclude`](/config/build/source#sourceexclude) |
| `displayName` | [`name`](/config/test/name) |
| `rootDir` | [`root`](/config/test/root) |
| `verbose` | [`verbose-reporter`](/config/test/reporters#verbose-reporter) |
| `injectGlobals` | [`globals`](/config/test/globals) |
| `moduleNameMapper` | [`resolve.alias`](/config/build/resolve#resolvealias) |
| `collectCoverage` | [`coverage.enabled`](/config/test/coverage#enabled) |
| `coverageDirectory` | [`coverage.reportsDirectory`](/config/test/coverage#reportsdirectory) |
| `coverageProvider` | [`coverage.provider`](/config/test/coverage#provider) |
| `coveragePathIgnorePatterns` | [`coverage.exclude`](/config/test/coverage#exclude) |
| `coverageThreshold` | [`coverage.thresholds`](/config/test/coverage#thresholds) |
| Jest 配置 | Rstest 对等配置 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `testRegex` | [`include`](/config/test/include) |
| `testMatch` | [`include`](/config/test/include) |
| `testPathIgnorePatterns` | [`exclude`](/config/test/exclude) |
| `transformIgnorePatterns` | [`output.externals`](/config/build/output#outputexternals)、[`source.exclude`](/config/build/source#sourceexclude) |
Copy link

Copilot AI Sep 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mixed language punctuation: using Chinese punctuation '、' in English-style table. Consider using comma ',' for consistency with the table format.

Suggested change
| `transformIgnorePatterns` | [`output.externals`](/config/build/output#outputexternals)、[`source.exclude`](/config/build/source#sourceexclude) |
| `transformIgnorePatterns` | [`output.externals`](/config/build/output#outputexternals), [`source.exclude`](/config/build/source#sourceexclude) |

Copilot uses AI. Check for mistakes.
| `displayName` | [`name`](/config/test/name) |
| `rootDir` | [`root`](/config/test/root) |
| `setupFilesAfterEnv` | [`setupFiles`](/config/test/setupFiles) |
| `verbose` | [`verbose-reporter`](/config/test/reporters#verbose-reporter) |
| `injectGlobals` | [`globals`](/config/test/globals) |
| `moduleNameMapper` | [`resolve.alias`](/config/build/resolve#resolvealias) |
| `maxWorkers` | [`pool.maxWorkers`](/config/test/pool) |
| `collectCoverage` | [`coverage.enabled`](/config/test/coverage#enabled) |
| `coverageDirectory` | [`coverage.reportsDirectory`](/config/test/coverage#reportsdirectory) |
| `coverageProvider` | [`coverage.provider`](/config/test/coverage#provider) |
| `coveragePathIgnorePatterns` | [`coverage.exclude`](/config/test/coverage#exclude) |
| `coverageThreshold` | [`coverage.thresholds`](/config/test/coverage#thresholds) |

更多详情，请参考 [配置文档](/config)。

Expand All @@ -68,7 +72,18 @@ export default defineConfig({

### 代码转换

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

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

如果你有自定义的 Babel 配置或使用特定的 Babel 插件/预设，你可以添加 [Rsbuild Babel 插件](https://rsbuild.rs/zh/plugins/list/plugin-babel)：

Expand All @@ -83,6 +98,8 @@ export default defineConfig({

## 更新测试 API

### 测试 API

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

```diff
Expand All @@ -98,3 +115,25 @@ Rstest 提供了 `rstest` API，你可以使用它来访问 Rstest 的工具函

fn.mockResolvedValue('foo');
```

### Done 回调

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

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

### 超时设置

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

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