#Rsbuild

本指南介绍了如何将 Rstest 与 Rsbuild 集成，以便在你的 Rsbuild 项目中进行无缝测试。

#快速开始

#新建项目

创建一个新的 Rsbuild + Rstest 项目。在创建时添加 --tools rstest 标志：

npm create rsbuild@latest -- --tools rstest

脚手架包含了 Rstest 和演示测试。使用 npm run test 来运行它们。

#现有项目

要将 Rstest 添加到现有项目中，请遵循快速入门来安装和设置测试脚本。

#复用 Rsbuild 配置

@rstest/adapter-rsbuild 是一个官方适配器，它允许 Rstest 自动从你现有的 Rsbuild 配置文件中继承测试相关配置。这可以确保测试环境与构建配置尽量保持一致，同时避免把仅用于开发服务器或页面构建的选项带进测试流程。

#安装适配器

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

#继承你的配置

使用适配器中的 withRsbuildConfig 函数，你可以从 Rsbuild 配置文件中继承 Rstest 配置。

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

export default defineConfig({
  extends: withRsbuildConfig(),
  // 额外的 Rstest 特定配置
});

这将自动：

• 加载你的 rsbuild.config.ts 文件
• 提取并映射测试相关的 Rsbuild 选项到 Rstest 配置
• 与你提供的任何其他 Rstest 配置合并
• 将加载到的 Rsbuild 配置文件加入 forceRerunTriggers，因此该配置变更时 --changed 会运行完整测试套件

适配器不会原样复用整份 Rsbuild 配置，而是只保留测试运行需要的部分，例如模块解析、代码转换、CSS Modules、静态资源处理和 target。像 dev、server、html 这类面向开发服务器、页面入口或产物输出的配置，会在转换时自动裁剪掉，避免把测试无关配置带入 Rstest。

默认情况下，适配器使用 process.cwd() 来解析 Rsbuild 配置。如果你的配置文件在其他地方，你可以使用 cwd 选项。更多详情请参阅 API 部分。

#API

#withRsbuildConfig(options)

返回一个配置函数，该函数加载 Rsbuild 配置并将其转换为 Rstest 配置。

#cwd

• 类型： string
• 默认值： process.cwd()

cwd 会传递给 Rsbuild 的 loadConfig 函数。它是用于解析 Rsbuild 配置文件的当前工作目录。

当你的 Rsbuild 配置文件位于不同的目录，或者你在 monorepo 中运行测试（此时 process.cwd() 不是你的配置目录）时，你可以指定 cwd 选项从不同的目录解析 Rsbuild 配置文件。

export default defineConfig({
  extends: withRsbuildConfig({
    cwd: './packages/my-app',
  }),
});

#configPath

• 类型： string
• 默认值： './rsbuild.config.ts'

Rsbuild 配置文件的路径。

#environmentName

• 类型： string
• 默认值： undefined

要使用的 environments 字段中的环境名称，它将与通用配置合并。设置为一个字符串以使用具有匹配名称的环境配置。

默认情况下，适配器使用 Rsbuild 的通用配置。如果你的 Rsbuild 配置有多个环境配置：

// rsbuild.config.ts
export default {
  source: {
    define: {
      'process.env.NODE_ENV': '"development"',
    },
  },
  environments: {
    test: {
      source: {
        define: {
          'process.env.NODE_ENV': '"test"',
        },
      },
    },
    prod: {
      source: {
        define: {
          'process.env.NODE_ENV': '"production"',
        },
      },
    },
  },
};

你可以在 Rstest 配置中引用特定的环境配置。Rstest 将会把 Rsbuild 的共享配置和具有匹配 environmentName 的环境配置适配为 Rstest 格式。

// 用于测试 'test' 环境
export default defineConfig({
  extends: withRsbuildConfig({
    environmentName: 'test',
  }),
  // 测试环境特定的配置
});

当你需要使用不同的配置独立测试应用程序的多个部分时，你可以定义多个 Rstest 项目。每个项目可以通过设置 environmentName 选项来继承特定的环境配置。

export default defineConfig({
  projects: [
    {
      extends: withRsbuildConfig({ environmentName: 'node' }),
      include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRsbuildConfig({ environmentName: 'react' }),
      include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});

#modifyRsbuildConfig

• 类型： (config: RsbuildConfig) => RsbuildConfig | void
• 默认值： undefined

在将 Rsbuild 配置转换为 Rstest 配置之前对其进行修改：

export default defineConfig({
  extends: withRsbuildConfig({
    modifyRsbuildConfig: (rsbuildConfig) => {
      delete rsbuildConfig.source?.define;
      return rsbuildConfig;
    },
  }),
});

#toRstestConfig(options)

将已有的 Rsbuild 配置对象转换为 Rstest 配置，而不会加载配置文件。

import type { RsbuildConfig } from '@rsbuild/core';
import { defineConfig } from '@rstest/core';
import { toRstestConfig } from '@rstest/adapter-rsbuild';

const rsbuildConfig: RsbuildConfig = {
  resolve: {
    alias: {
      '@': './src',
    },
  },
};

export default defineConfig({
  extends: toRstestConfig({
    rsbuildConfig,
  }),
});

#rsbuildConfig

• 类型： RsbuildConfig

要转换的 Rsbuild 配置对象。

#configPath

• 类型： string
• 默认值： undefined

传入的 rsbuildConfig 对应的来源文件路径；它不会从该路径加载配置。适配器只用它将该文件加入 forceRerunTriggers 和 performance.buildCache.buildDependencies。

#environmentName

• 类型： string
• 默认值： undefined

要从 environments 字段中合并到通用配置的环境名称。

#modifyRsbuildConfig

• 类型： (config: RsbuildConfig) => RsbuildConfig
• 默认值： undefined

在将合并后的 Rsbuild 配置对象转换为 Rstest 配置之前对其进行修改。

#配置映射

适配器会自动将这些 Rsbuild 选项映射到 Rstest：

下表中列出的字段会被继承；没有列出的 Rsbuild 选项默认不会进入 Rstest 配置。这意味着 dev、server、html 等与测试运行无关的配置会被自动忽略。

另外，适配器还会移除 rsbuild:type-check 插件，因为类型检查不属于测试运行时所需的构建链路。

#调试配置

要查看适配器返回的解析配置，可以将其包装并打印结果：

export default defineConfig({
  extends: async (user) => {
    const config = await withRsbuildConfig()(user);
    console.log('继承的配置:', JSON.stringify(config, null, 2));
    return config;
  },
});

#相关文档

• Rsbuild 配置概览
• Rstest 配置概览