#配置 Rstest

#配置文件

当你使用 Rstest 的 CLI 命令时，Rstest 会自动读取当前项目根目录下的配置文件，按照以下顺序进行解析：

• rstest.config.mjs
• rstest.config.ts
• rstest.config.js
• rstest.config.cjs
• rstest.config.mts
• rstest.config.cts

我们推荐使用 .mjs 或 .ts 格式的配置文件，并从 @rstest/core 中导入 defineConfig 工具函数，它提供了友好的 TypeScript 类型推导和自动补全，可以帮助你避免配置中的错误。

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

export default defineConfig({
  testEnvironment: 'node',
});

如果你在开发一个非 TypeScript 项目，可以使用 .mjs 格式的配置文件。

#指定配置文件

Rstest CLI 通过 --config 选项来指定配置文件，可以设置为相对路径或绝对路径。

{
  "scripts": {
    "test": "rstest --config scripts/rstest.config.mjs"
  }
}

你也可以将 --config 选项缩写为 -c：

rstest -c scripts/rstest.config.mjs

#配置 Rsbuild

Rstest 的构建配置继承自 Rsbuild。因此，在 Rstest 中，你可以使用绝大部分的 Rsbuild 配置。如：

• 通过 plugins 使用 Rsbuild 插件；
• 通过 resolve 对模块解析行为进行配置；
• 通过 tools.rspack 配置 Rspack；
• 通过 tools.swc 对 builtin:swc-loader 进行配置。

更多配置可参考 构建配置。

#配置 Rspack

Rstest 底层使用 Rspack 进行构建，因此你可以直接使用 Rspack 的配置项来配置 Rstest 的构建行为。

详情可参考 配置 Rspack。

#配置 SWC

Rstest 默认通过 Rspack 的 builtin:swc-loader 来转换 JavaScript 和 TypeScript 代码，它是 swc-loader 的 Rust 版本。

Rstest 暴露了一些选项来配置 builtin:swc-loader：

• tools.swc：用于配置 builtin:swc-loader 的选项。
• source.include：用于指定需要被 SWC 编译的文件。
• source.exclude：用于排除不需要被 SWC 编译的文件。

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

export default defineConfig({
  tools: {
    swc: {
      jsc: {
        transform: {
          react: {
            runtime: 'automatic',
          },
        },
        experimental: {
          plugins: [['@swc/plugin-emotion', {}]],
        },
      },
    },
  },
});

#SWC 插件版本

请注意，SWC 的插件仍然是一个实验性功能，目前 SWC 的 Wasm 插件是不向后兼容的，SWC 插件的版本与 Rspack 依赖的 swc_core 版本存在强耦合关系。

这意味着，你需要选择和当前 swc_core 版本匹配的 SWC 插件，才能使它正常执行。如果你使用的 SWC 插件版本与 Rspack 依赖的 swc_core 版本不匹配，Rspack 在执行构建时会抛出错误，请参考 Rspack 常见问题 - SWC 插件版本不匹配 进行处理。

#检测 Rstest 环境

你可以使用 process.env.RSTEST 来检测是否是 Rstest 测试环境以应用不同的配置 / 代码在你的测试中。

if (process.env.RSTEST) {
  // 在 rstest 环境下将会返回 'true'
  // do something...
}

需要注意的是，如果你使用 process.env.RSTEST 在你的源码中，在生产环境构建时，在你的构建配置（如 rsbuild.config.ts）中将 process.env.RSTEST 定义为 false，这样将有助于打包工具消除无用代码。

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

export default defineConfig({
  source: {
    define: {
+      'process.env.RSTEST': false,
    },
  },
});

如果你正在开发 Rsbuild 插件，你可以使用 api.context.callerName 来判断当前插件被调用的环境。

export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    const { callerName } = api.context;

    if (callerName === 'rstest') {
      // ...
    } else if (callerName === 'rsbuild') {
      // ...
    }
  },
};

#配置集成

在大型项目中，你往往已经有构建/工具链的既有配置（别名、全局变量、插件等）。Rstest 通过 适配器（Adapter） 与 extends 选项，支持将这些外部配置转换并整合到测试配置中，从而避免重复维护、保持一致性。

• 使用 extends 可加载一个函数（适配器）或对象，返回的配置会与当前 Rstest 配置深度合并。
• 适用于复用 Rsbuild/Rspack 等工具的配置，或为框架模板预设测试行为（如默认测试环境、setup 脚本）。