> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # plugins [![plugins](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)plugins](https://rsbuild.rs/zh/config/plugins) `plugins` 选项用于注册 Rsbuild 插件。 Rstest 与 Rsbuild 共享同一套插件系统，因此你可以在 Rstest 中使用 Rsbuild 插件。 ## 使用插件 你可以在 `rstest.config.*` 中通过 `plugins` 选项来注册 Rsbuild 插件，详见 [Rsbuild - plugins](https://rsbuild.rs/zh/config/plugins)。 ```ts title="rstest.config.ts" import { defineConfig } from '@rstest/core'; import { pluginReact } from '@rsbuild/plugin-react'; export default defineConfig({ plugins: [pluginReact()], }); ``` ## 发现插件 查看 Rsbuild 的 [插件列表](https://rsbuild.rs/zh/plugins/list/#%E5%AE%98%E6%96%B9%E6%8F%92%E4%BB%B6) 来发现可用的插件，这些插件也适用于 Rstest。 ## 判断插件是否运行在 Rstest 中 \{#detect-rstest-environment} Rsbuild 插件可以在不同的工具中运行。使用 [`api.context.callerName`](https://rsbuild.rs/zh/api/javascript-api/instance#contextcallername) 判断当前插件是否运行在 Rstest 中，再执行 Rstest 特有的逻辑。 ```ts title="rstest-plugin.ts" import type { RsbuildPlugin } from '@rsbuild/core'; export const myPlugin = (): RsbuildPlugin => ({ name: 'my-plugin', setup(api) { if (api.context.callerName !== 'rstest') { return; } // Rstest 特有的插件逻辑 }, }); ``` Rstest 通过 [`api.useExposed('rstest')`](https://rsbuild.rs/zh/plugins/dev/core) 暴露集成 API。`RstestExposeAPI` 从 `@rstest/core` 导出，用于描述这些 API 的类型。 ## 在 Rsbuild 插件中读取 Rstest 配置 \{#get-rstest-config} [Added in v0.11.2](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.2) 使用 `getRstestConfig` 读取当前 Rsbuild environment 最终生效的 Rstest 配置。返回值由当前 project 的规范化配置与 `pool`、`reporters`、`shard`、`update`、`output.distPath` 等全局配置和运行级配置合并而成。 ```ts title="rstest-plugin.ts" import type { RsbuildPlugin } from '@rsbuild/core'; import type { RstestExposeAPI } from '@rstest/core'; export const myPlugin = (): RsbuildPlugin => ({ name: 'read-rstest-config', setup(api) { const rstestConfig = api .useExposed('rstest') ?.getRstestConfig(); if (!rstestConfig) { return; } api.modifyRsbuildConfig((config) => ({ ...config, source: { ...config.source, define: { ...config.source?.define, __RSTEST_PROJECT_NAME__: JSON.stringify(rstestConfig.name), }, }, })); }, }); ``` 在多 project 模式下，`getRstestConfig` 返回最终生效的全局配置与当前 Rsbuild environment 所属 project 配置合并后的结果。函数、provider 特有的类实例等 opaque value 会保留原始引用及行为。 **类型：** `() => Readonly` ## 在 Rsbuild 插件中修改 Rstest 配置 \{#modify-rstest-config} [Added in v0.11.1](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.1) 使用 `modifyRstestConfig` 调整当前 project 的 Rstest 配置。这个 API 适合框架集成或工具链插件使用：当插件已经了解当前 framework、Rsbuild environment 或项目约定时，可以集中补充测试入口、排除规则、setup files、alias、define 或 `testEnvironment` 等 project 配置，避免用户在 Rstest 配置中重复声明同一套信息。 ```ts title="rstest-plugin.ts" import type { RsbuildPlugin } from '@rsbuild/core'; import type { RstestExposeAPI } from '@rstest/core'; export const myPlugin = (): RsbuildPlugin => ({ name: 'modify-rstest-config', setup(api) { const rstestApi = api.useExposed('rstest'); rstestApi?.modifyRstestConfig((config) => { config.include = ['**/*.plugin.test.ts']; }); }, }); ``` 在多 project 模式下，注册在某个 project 中的插件只会修改该 project 的 Rstest 配置，不会影响其他 project。 ```ts title="rstest.config.ts" import { defineConfig } from '@rstest/core'; import { myPlugin } from './rstest-plugin'; export default defineConfig({ projects: [ { name: 'node', plugins: [myPlugin()], }, { name: 'browser', plugins: [], }, ], }); ``` ### 类型说明 ```ts import type { RstestConfig } from '@rstest/core'; export type ModifyRstestConfigCallback = ( config: RstestConfig, ) => RstestConfig | void | Promise; ``` **类型：** `(callback: ModifyRstestConfigCallback) => void` `RstestConfig` 与 `defineConfig` 接收的配置类型一致。使用 `modifyRstestConfig` 时，你可以直接修改回调收到的 `config` 对象，也可以返回一个符合 `RstestConfig` 结构的配置片段。Rstest 会在回调完成后重新合并、规范化并校验这些改动。该回调也可以是异步函数。 请在 Rsbuild 插件的 `setup` 阶段注册 `modifyRstestConfig`。不要在 `api.modifyRsbuildConfig` 等更晚的 Rsbuild config hook 中注册它，因为 Rstest 会在解析 Rsbuild config 时应用已经收集到的回调；在这些 hook 内注册的回调对于当前解析流程来说已经太晚。 Rstest 会在 Rsbuild 初始化测试 environments 前解析文件级环境注释，如 `@rstest-environment jsdom`。`modifyRstestConfig` 不应新增或暴露需要形成新环境注释分组的文件；请改为在 Rsbuild 初始化前通过 `testEnvironment` 或拆分 `projects` 配置。 ### 可修改的配置范围 `modifyRstestConfig` 只用于调整当前 project 的配置。回调修改不支持的字段时，Rstest 会抛出错误并提示应改为在 `rstest.config.*` 中声明。 | 配置范围 | 是否支持 | 说明 | | --------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------- | | `include`、`exclude`、`includeSource` | 支持 | 影响当前 project 的测试发现；Rstest 会在回调后重新收集测试入口。 | | `setupFiles`、`globalSetup` | 支持 | 影响当前 project 的 setup 文件；Rstest 会在回调后重新解析。 | | `testEnvironment` | 支持 | 只影响当前 project 的测试环境。 | | `resolve`、`source`、`performance.buildCache` | 支持 | 作为当前 project 的构建配置重新应用到 Rsbuild。 | | `root`、`output.module` | 支持 | 作为当前 project 的路径或输出模块配置重新规范化。 | | `name`、`browser.enabled` | 不支持 | 会改变 project 身份或运行模式，必须在 `rstest.config.*` 中声明。 | | `browser.provider`、`browser.browser`、`browser.headless`、`browser.port`、`browser.strictPort`、`browser.providerOptions` | 不支持 | 会影响 Browser Mode 启动或 dev server 选择，必须在 Rsbuild 插件运行前声明。 | | `projects`、`plugins`、`extends` | 不支持 | 会改变 project 拓扑或插件初始化顺序，必须在 Rstest 配置或 adapter 中声明。 | | `coverage`、`reporters`、`pool`、`isolate`、`update`、`shard`、`forceRerunTriggers` | 不支持 | 属于全局执行策略，或在 Rsbuild 插件运行前已经参与调度。 | | `output.distPath` | 不支持 | 会改变 Rstest/Rsbuild 输出目录拓扑，必须在 Rstest 配置中声明。 | 如果你需要动态添加 Rsbuild 插件，请通过 Rstest 的 `extends` Adapter 方案集成。Adapter 可以在 Rsbuild 插件初始化开始之前准备好 Rstest 配置。