#适配器

适配器可以将其他工具（如构建工具或 CLI）的配置转换为 Rstest 支持的配置格式。通过官方或自定义适配器，你可以复用已有配置，避免在多个工具之间重复定义，让测试与项目现有配置保持一致。

适配器通过 extends 将转换后的配置传给 Rstest。复用构建配置时，测试入口和运行时仍由 Rstest 管理，适配器会选择并转换兼容的配置项。

#使用官方适配器

如果你的项目已经使用 Rsbuild、Rslib 或 Rspack，可以通过官方适配器复用别名、代码转换选项和兼容的插件。根据项目的构建工具选择适配器：

#安装和使用适配器

以复用 Rsbuild 配置为例，先配置好 Rstest，再安装适配器：

npm add @rstest/adapter-rsbuild -D

yarn add @rstest/adapter-rsbuild -D

pnpm add @rstest/adapter-rsbuild -D

bun add @rstest/adapter-rsbuild -D

deno add npm:@rstest/adapter-rsbuild -D

@rstest/core 负责运行测试，@rstest/adapter-rsbuild 负责加载并转换已有的 Rsbuild 配置。

import { withRsbuildConfig } from '@rstest/adapter-rsbuild';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  extends: withRsbuildConfig(),
  testEnvironment: 'node',
  testTimeout: 10_000,
});

适配器会加载 Rsbuild 配置，复用其中兼容的编译选项。例如，已经在 rsbuild.config.ts 中定义的别名，可以直接用于测试，无需在 rstest.config.ts 中再定义一次。

这个示例在 Node.js 中运行测试。如果测试需要 DOM，请安装并配置 jsdom 或 happy-dom。超时时间、覆盖率等测试专属选项继续放在 Rstest 配置中。

#选择构建配置

如果构建配置不在默认位置，可以通过 configPath 指定路径。对于配置了多个 environment 的 Rsbuild 项目，可以用 environmentName 选择要与公共配置合并的 environment：

import { withRsbuildConfig } from '@rstest/adapter-rsbuild';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  extends: withRsbuildConfig({
    configPath: './config/rsbuild.config.ts',
    environmentName: 'web',
  }),
  testEnvironment: 'node',
});

名称应对应构建配置中实际定义的 environment。Rslib 和 Rspack 中对应的选择选项分别是 libId 和 configName。如果需要独立测试多套配置，可以为每个 Rstest project 分别设置 extends。

完整的选项、配置映射和插件处理方式见对应的参考页：

• Rsbuild 适配器参考
• Rslib 适配器参考
• Rspack 适配器参考

#配置合并

本地 Rstest 配置的优先级高于适配器返回的配置。例如，上面示例中的 testEnvironment: 'node' 会覆盖适配器推断出的测试环境。

resolve、source 等对象字段会深度合并。数组则遵循各选项的规则：plugins 和 setupFiles 会拼接，include 和 reporters 会被替换。完整规则及组合多个预设的用法见配置合并。

#创建自定义适配器

如果你的工具链使用自己的配置格式，可以编写适配器，将它映射到 Rstest 选项。如果共享预设已经使用 Rstest 配置格式，直接将配置对象传给 extends 即可。

适配器实现 ExtendConfigFn：接收用户的 Rstest 配置，返回 ExtendConfig 对象或解析为该对象的 Promise。它可以读取用户配置来决定返回值，但不应修改传入的配置。返回的配置不能定义 projects。

例如，某个工具使用以下格式保存别名和编译时常量：

export default {
  aliases: {
    '@': './src',
  },
  globals: {
    __VERSION__: '"1.0.0"',
  },
};

将这些字段映射到 Rstest 的 resolve.alias 和 source.define：

import type { ExtendConfigFn } from '@rstest/core';
import myConfig from './my.config';

export const withMyConfig: ExtendConfigFn = () => ({
  resolve: {
    alias: myConfig.aliases,
  },
  source: {
    define: myConfig.globals,
  },
});

#使用自定义适配器

将适配器传给 extends，测试专属选项保留在本地配置中：

import { defineConfig } from '@rstest/core';
import { withMyConfig } from './my-adapter';

export default defineConfig({
  extends: withMyConfig,
  testTimeout: 8000,
});

#高级用法：带选项的适配器

如果需要让调用方定制适配器，可以导出一个接收选项、返回 ExtendConfigFn 的函数。例如，下面的版本允许调用方选择测试环境，同时复用相同的别名和常量：

import type { ExtendConfigFn } from '@rstest/core';
import myConfig from './my.config';

interface MyAdapterOptions {
  testEnvironment?: 'node' | 'happy-dom';
}

export function withMyConfig(options: MyAdapterOptions = {}): ExtendConfigFn {
  return () => ({
    resolve: {
      alias: myConfig.aliases,
    },
    source: {
      define: myConfig.globals,
    },
    testEnvironment: options.testEnvironment ?? 'node',
  });
}

安装 happy-dom 后，使用 extends: withMyConfig({ testEnvironment: 'happy-dom' }) 即可选择该环境。本地 Rstest 配置仍然优先于适配器提供的默认值。