#Rspack

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

#快速开始

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

#复用 Rspack 配置

@rstest/adapter-rspack 是一个官方适配器，它允许 Rstest 自动从你现有的 Rspack 配置文件中继承配置。这可以确保你的测试环境与构建配置相匹配，而无需重复配置。

#安装适配器

npm add @rstest/adapter-rspack -D

yarn add @rstest/adapter-rspack -D

pnpm add @rstest/adapter-rspack -D

bun add @rstest/adapter-rspack -D

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

#继承你的配置

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

import { defineConfig } from '@rstest/core';
import { withRspackConfig } from '@rstest/adapter-rspack';

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

这将自动：

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

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

#示例项目

你可以参考 Rspack adapter 示例，了解如何在完整的 React 项目中让 Rstest 继承 Rspack 配置。

#API

#withRspackConfig(options)

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

#cwd

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

用于解析 Rspack 配置文件的工作目录。

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

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

#configPath

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

Rspack 配置文件的路径。

#configName

• 类型： string
• 默认值： undefined

当 Rspack 配置文件使用多配置时，选择指定名称的配置。设置为字符串以使用具有匹配 name 字段的配置。

如果你的 Rspack 配置导出了一个配置数组：

// rspack.config.ts
export default [
  {
    name: 'client',
    target: 'web',
    entry: './src/client.ts',
    // ...
  },
  {
    name: 'server',
    target: 'node',
    entry: './src/server.ts',
    // ...
  },
];

你可以在 Rstest 配置中选择特定的配置：

export default defineConfig({
  extends: withRspackConfig({
    configName: 'client',
  }),
});

当你需要使用不同的配置独立测试应用程序的多个部分时，你可以定义多个 Rstest 项目：

export default defineConfig({
  projects: [
    {
      extends: withRspackConfig({ configName: 'server' }),
      include: ['tests/server/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRspackConfig({ configName: 'client' }),
      include: ['tests/client/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});

#env

• 类型： Record<string, unknown> | string[]
• 默认值： undefined

传递给 Rspack 配置函数的环境变量。当 rspack.config.ts 导出一个函数时，对应其 env 参数：

// rspack.config.ts
export default (env) => {
  console.log(env); // 接收来自适配器的值
  return {/* ... */};
};

#nodeEnv

• 类型： string
• 默认值： undefined

加载 Rspack 配置时使用的 NODE_ENV 值。

#modifyRspackConfig

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

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

export default defineConfig({
  extends: withRspackConfig({
    modifyRspackConfig: (rspackConfig) => {
      delete rspackConfig.resolve?.alias;
      return rspackConfig;
    },
  }),
});

#配置映射

withRspackConfig 不会将整份 Rspack 配置原样复制到 test compiler。它会根据行为所属的层级处理每个选项：有直接对应关系的概念会转换为 Rstest 配置，兼容的 compiler 选项会传给 Rspack，而与生成的 test build 冲突的设置仍由 Rstest 控制。

以下表格覆盖 Rspack 2.1 的全部 top-level 选项。部分选项会出现在不止一个表格中，因为其不同子项由不同层负责。例如，Rstest 需要理解 resolve.alias，而 resolve.fallback 必须交给 Rspack；类似地，Rstest 会根据 cache 派生自己的缓存，但不会复用其中每一个 persistent cache 调优选项。

部分 Rspack 选项在 Rstest 中有直接对应项。adapter 会在创建 compiler 前转换这些值，因为 Rstest 需要使用它们选择 test environment、解析 test module 或准备 build output。只有下表列出的 resolve 字段与 Rsbuild 共用；其他 Rspack resolver 选项由下一个表格中的流程处理。

其他选项仍会影响最终的 Rspack compilation，但不能安全地替换生成的 test 配置。adapter 会根据各选项的语义进行组合，例如追加 rules 和 plugins、合并 Rspack-only resolver 选项，并保留生成的 output path。Rstest 后续的 compiler hooks 仍可能恢复 test runtime 必需的值。

下一组选项不会与 Rstest 控制的 build 结构重叠，因此 adapter 会通过 Rsbuild 的 mergeConfig 将它们传给 compiler。该过程使用 Rspack 的标准 merge 语义，并以生成的配置为合并基础。数组和嵌套对象会遵循 Rspack 的常规 merge 行为，而不是由 adapter 另行定义赋值规则。

其余选项描述 application build、multi-compiler 或 dev server 工作流，或者控制由 Rstest 自己展示的输出。应用这些选项可能替换生成的 test 结构，或产生没有可观察效果的配置，因此 adapter 会继续让 Rstest 控制对应行为。extends 是一个例外：Rspack CLI 会在加载配置时消费它，所以 adapter 收到的是已经完成 merge 的结果，而不是继续向 compiler 传递 extends 字段。

Rspack 2.1 将原有的顶层 snapshot 选项移到了 cache.snapshot，因此它不再是顶层配置选项。Rspack persistent cache 会转换为 Rstest 生成的 build cache；cache.snapshot、maxAge、portable 和 readonly 等 Rspack-specific 调优字段不会复制到该生成缓存中。

#调试配置

设置 DEBUG=rstest 后，Rstest 会写入解析后的 Rstest、Rsbuild 和 Rspack 配置，并在命令输出中打印对应位置。检查生成的 Rspack 配置，可以确认哪些选项最终传给了 compiler：

DEBUG=rstest rstest

#相关文档

• Rspack 配置概览
• Rstest 配置概览