#Rslib

本指南介绍如何将 Rstest 集成到 Rslib 项目中，为你的 Rslib 项目提供无缝的测试体验。

#快速开始

#新项目

通过在创建时添加 --tools rstest 参数，即可创建一个 Rslib + Rstest 项目：

npx create-rslib --template react-ts --tools rstest --dir my-project

脚手架已包含 Rstest 和示例测试，运行 npm run test 即可执行测试。

#已有项目

如需为已有项目添加 Rstest，请参考快速开始安装 Rstest 并配置测试脚本。

#复用 Rslib 配置

@rstest/adapter-rslib 是 Rstest 官方提供的适配器，允许 Rstest 自动继承现有 Rslib 配置文件中的测试相关配置。这样可以确保测试环境与构建配置尽量保持一致，同时避免把只服务于构建产物的选项带进测试流程。

#安装适配器

npm add @rstest/adapter-rslib -D

yarn add @rstest/adapter-rslib -D

pnpm add @rstest/adapter-rslib -D

bun add @rstest/adapter-rslib -D

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

#扩展配置

使用适配器中的 withRslibConfig 函数，可以从 Rslib 配置文件中扩展 Rstest 配置。

import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

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

这将自动：

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

如果你在 Rslib 配置里开启了 performance.buildCache，withRslibConfig() 会把这项配置传给 Rstest，Rstest 仍会继续补充自己的缓存默认值，例如运行时摘要项和基于配置文件的失效条件。

如果你的 Rslib 配置没有开启 performance.buildCache，Rstest 默认也不会开启它。只有在你希望测试构建使用持久化缓存时，才需要在 Rstest 配置里显式设置 performance.buildCache：

import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

export default defineConfig({
  extends: withRslibConfig(),
  performance: {
    buildCache: true,
  },
});

适配器不会原样复用整份 Rslib 配置，而是只保留测试运行需要的部分，例如模块解析、代码转换、CSS Modules、装饰器相关配置、静态资源处理和 target。像 dev、server、html 等未映射字段，以及其他仅用于开发服务器、页面入口或构建产物的配置，会在转换时自动裁剪掉。

默认情况下，适配器使用 process.cwd() 来解析 Rslib 配置。如果配置文件在其他目录，可以使用 cwd 选项。更多详情请参阅 API。

#API

#withRslibConfig(options)

返回一个加载 Rslib 配置并将其转换为 Rstest 配置的函数。

#cwd

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

cwd 是用于解析 Rslib 配置文件的当前工作目录。

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

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

#configPath

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

Rslib 配置文件的路径。

#libId

• 类型： string
• 默认值： undefined

要使用的 lib 字段中的 lib 配置 ID。设置为字符串以使用具有匹配 ID 的 lib 配置。

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

// rslib.config.ts
export default defineConfig({
  lib: [
    {
      id: 'core',
      format: 'esm',
      dts: true,
      source: {
        define: {
          IS_CORE: true,
        },
      },
    },
    {
      id: 'utils',
      format: 'esm',
      source: {
        define: {
          IS_CORE: false,
        },
      },
    },
  ],
  // 共享配置
});

你可以在 Rstest 配置中引用特定的 lib 配置。Rstest 会将 Rslib 的共享配置和具有匹配 libId 的 lib 配置调整为 Rstest 格式。

这里也不是直接复用整个 lib 配置。适配器只会提取该 lib 中与测试执行相关的 source、output、tools、plugins 和 resolve 配置，再与共享配置合并后转换为 Rstest 配置。

// 用于测试 'core' 环境
export default defineConfig({
  extends: withRslibConfig({
    libId: 'core',
  }),
  // core-specific test config
});

当你需要使用不同的配置独立测试应用程序的多个部分时，可以定义多个 Rstest project。每个 project 都可以通过设置 libId 选项来扩展特定的 lib 配置。

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

#modifyLibConfig

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

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

export default defineConfig({
  extends: withRslibConfig({
    modifyLibConfig: (libConfig) => {
      delete libConfig.source?.define;
      return libConfig;
    },
  }),
});

#配置映射

适配器会自动将以下 Rslib 选项映射到 Rstest：

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

#调试配置

如需查看适配器返回的解析后配置，可以打印结果：

export default defineConfig({
  extends: async (user) => {
    const config = await withRslibConfig({ libId: 'react' })(user);
    console.log('Extended config:', JSON.stringify(config, null, 2));
    return config;
  },
});

#相关文档

• @rstest/adapter-rslib 文档
• Rslib 配置概览
• Rstest 配置概览