web-infra-dev · 9aoy · Apr 2, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 2, 2026
diff --git a/e2e/adapterTransformImport/fixtures/demo-lib/foo.js b/e2e/adapterTransformImport/fixtures/demo-lib/foo.js
@@ -0,0 +1,2 @@
+export const foo = () => 'actual';
+export default foo;
diff --git a/e2e/adapterTransformImport/fixtures/demo-lib/index.js b/e2e/adapterTransformImport/fixtures/demo-lib/index.js
@@ -0,0 +1 @@
+export { foo } from './foo.js';
diff --git a/e2e/adapterTransformImport/fixtures/package.json b/e2e/adapterTransformImport/fixtures/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "@rstest/tests-transform-import",
+  "version": "1.0.0",
+  "private": true
+}
diff --git a/e2e/adapterTransformImport/fixtures/rstest.config.mts b/e2e/adapterTransformImport/fixtures/rstest.config.mts
@@ -0,0 +1,19 @@
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  include: ['tests/**/*.test.ts'],
+  resolve: {
+    alias: {
+      'demo-lib': './demo-lib',
+    },
+  },
+  source: {
+    transformImport: [
+      {
+        libraryName: 'demo-lib',
+        libraryDirectory: '.',
+        camelToDashComponentName: false,
+      },
+    ],
+  },
+});
diff --git a/e2e/adapterTransformImport/fixtures/tests/demoLib.d.ts b/e2e/adapterTransformImport/fixtures/tests/demoLib.d.ts
@@ -0,0 +1,4 @@
+declare module 'demo-lib' {
+  export function foo(): string;
+  export default foo;
+}
diff --git a/e2e/adapterTransformImport/fixtures/tests/index.test.ts b/e2e/adapterTransformImport/fixtures/tests/index.test.ts
@@ -0,0 +1,6 @@
+import { expect, it } from '@rstest/core';
+import { foo } from 'demo-lib';
+
+it('transformImport from rstest config', () => {
+  expect(foo()).toBe('actual');
+});
diff --git a/e2e/adapterTransformImport/index.test.ts b/e2e/adapterTransformImport/index.test.ts
@@ -0,0 +1,26 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from '@rstest/core';
+import { runRstestCli } from '../scripts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe('adapter transformImport', () => {
+  it('should support source.transformImport in rstest config', async () => {
+    const { cli, expectExecSuccess } = await runRstestCli({
+      command: 'rstest',
+      args: ['run'],
+      options: {
+        nodeOptions: {
+          cwd: join(__dirname, 'fixtures'),
+        },
+      },
+    });
+
+    await expectExecSuccess();
+
+    expect(cli.stdout).toContain('transformImport from rstest config');
+    expect(cli.stdout).toContain('Test Files 1 passed');
+  });
+});
diff --git a/packages/adapter-rsbuild/src/toRstestConfig.ts b/packages/adapter-rsbuild/src/toRstestConfig.ts
@@ -32,8 +32,15 @@ export function toRstestConfig({
 
   const { rspack, swc, bundlerChain } = finalBuildConfig.tools || {};
   const { cssModules, target, module } = finalBuildConfig.output || {};
-  const { assetsInclude, decorators, define, include, exclude, tsconfigPath } =
-    finalBuildConfig.source || {};
+  const {
+    assetsInclude,
+    decorators,
+    define,
+    include,
+    exclude,
+    tsconfigPath,
+    transformImport,
+  } = finalBuildConfig.source || {};
 
   return {
     root: finalBuildConfig.root,
@@ -54,6 +61,7 @@ export function toRstestConfig({
       include,
       exclude,
       tsconfigPath,
+      transformImport,
     },
     resolve: finalBuildConfig.resolve,
     output: {

diff --git a/packages/adapter-rsbuild/tests/toRstestConfig.test.ts b/packages/adapter-rsbuild/tests/toRstestConfig.test.ts
@@ -9,6 +9,13 @@ describe('toRstestConfig', () => {
       define: {
         'process.env.NODE_ENV': '"common"',
       },
+      transformImport: [
+        {
+          libraryName: 'lodash',
+          libraryDirectory: '',
+          camelToDashComponentName: false,
+        },
+      ],
     },
     resolve: {
       alias: {
@@ -38,6 +45,13 @@ describe('toRstestConfig', () => {
     expect(config.source?.define).toEqual({
       'process.env.NODE_ENV': '"common"',
     });
+    expect(config.source?.transformImport).toEqual([
+      {
+        libraryName: 'lodash',
+        libraryDirectory: '',
+        camelToDashComponentName: false,
+      },
+    ]);
     expect(config.resolve?.alias).toEqual({
       '@': './src',
     });

diff --git a/packages/adapter-rslib/src/index.ts b/packages/adapter-rslib/src/index.ts
@@ -94,6 +94,7 @@ export function withRslibConfig(
       include,
       exclude,
       tsconfigPath,
+      transformImport,
     } = finalLibConfig.source || {};
 
     // Convert rslib config to rstest config
@@ -112,6 +113,7 @@ export function withRslibConfig(
         include,
         exclude,
         tsconfigPath,
+        transformImport,
       },
       resolve: finalLibConfig.resolve,
       output: {

diff --git a/packages/adapter-rslib/tests/index.test.ts b/packages/adapter-rslib/tests/index.test.ts
@@ -14,7 +14,14 @@ export default defineConfig({
     assetsInclude: /\\.json5$/,
     define: {
       'process.env.NODE_ENV': '"test"'
-    }
+    },
+    transformImport: [
+      {
+        libraryName: 'lodash',
+        libraryDirectory: '.',
+        camelToDashComponentName: false
+      }
+    ]
   },
   resolve: {
     alias: {
@@ -46,6 +53,13 @@ export default defineConfig({
     expect(config.source?.define).toEqual({
       'process.env.NODE_ENV': '"test"',
     });
+    expect(config.source?.transformImport).toEqual([
+      {
+        libraryName: 'lodash',
+        libraryDirectory: '.',
+        camelToDashComponentName: false,
+      },
+    ]);
     expect(config.resolve?.alias).toEqual({
       '@': './src',
     });

diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
@@ -468,6 +468,8 @@ export interface RstestConfig {
     | 'decorators'
     | 'include'
     | 'exclude'
+    | 'transformImport'
+    | 'assetsInclude'
   >;
 
   dev?: Pick<NonNullable<RsbuildConfig['dev']>, 'writeToDisk'>;

diff --git a/website/docs/en/config/build/source.mdx b/website/docs/en/config/build/source.mdx
@@ -55,6 +55,36 @@ If you want certain files not to be bundled into the outputs, you can use [outpu
 
 Specify additional JavaScript files that need to be compiled.
 
+## source.transformImport <RsbuildDocBadge path="/config/source/transform-import" text="source.transformImport" />
+
+<ApiMeta addedVersion="0.9.6" />
+
+Configure on-demand import transforms.
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  source: {
+    transformImport: [
+      {
+        libraryName: 'demo-lib',
+        libraryDirectory: '.',
+        camelToDashComponentName: false,
+      },
+    ],
+  },
+});
+```
+
+:::caution
+
+`source.transformImport` rewrites the final module request at compile time.
+
+In the current implementation, module-level mocking APIs that still use the original specifier, such as `rs.mock('pkg')`, `rs.doMock('pkg')`, `rs.importActual('pkg')`, and `rs.requireActual('pkg')`, may no longer target the transformed module request.
+
+:::
+
 ## source.tsconfigPath <RsbuildDocBadge path="/config/source/tsconfig-path" text="source.tsconfigPath" />
 
 Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path.
diff --git a/website/docs/en/config/test/extends.mdx b/website/docs/en/config/test/extends.mdx
@@ -166,7 +166,7 @@ export default defineConfig({
 
 ### Example: extend from Rslib config
 
-Use the `@rstest/adapter-rslib` adapter to extend Rstest configuration from an existing Rslib config file. The adapter automatically maps compatible options like `source.define`, `source.include`, `source.exclude`, and more.
+Use the `@rstest/adapter-rslib` adapter to extend Rstest configuration from an existing Rslib config file. The adapter automatically maps compatible options like `source.define`, `source.include`, `source.exclude`, `source.transformImport`, and more.
 
 ```ts
 import { defineConfig } from '@rstest/core';

diff --git a/website/docs/en/guide/integration/rsbuild.mdx b/website/docs/en/guide/integration/rsbuild.mdx
@@ -175,22 +175,23 @@ The adapter automatically maps these Rsbuild options to Rstest:
 
 Only the fields listed below are inherited. Rsbuild options that are not listed are ignored by default, which means test-irrelevant sections such as `dev`, `server`, and `html` are automatically pruned during conversion.
 
-| Rsbuild option          | Rstest equivalent      | Notes                                |
-| ----------------------- | ---------------------- | ------------------------------------ |
-| `name` from environment | `name`                 | Environment identifier               |
-| `plugins`               | `plugins`              | Plugin configuration                 |
-| `source.decorators`     | `source.decorators`    | Decorator support                    |
-| `source.assetsInclude`  | `source.assetsInclude` | Additional static asset patterns     |
-| `source.define`         | `source.define`        | Global constants                     |
-| `source.include`        | `source.include`       | Source inclusion patterns            |
-| `source.exclude`        | `source.exclude`       | Source exclusion patterns            |
-| `source.tsconfigPath`   | `source.tsconfigPath`  | TypeScript config path               |
-| `resolve`               | `resolve`              | Module resolution                    |
-| `output.cssModules`     | `output.cssModules`    | CSS modules configuration            |
-| `tools.rspack`          | `tools.rspack`         | Rspack configuration                 |
-| `tools.swc`             | `tools.swc`            | SWC configuration                    |
-| `tools.bundlerChain`    | `tools.bundlerChain`   | Bundler chain configuration          |
-| `output.target`         | `testEnvironment`      | 'happy-dom' for web, 'node' for node |
+| Rsbuild option           | Rstest equivalent        | Notes                                |
+| ------------------------ | ------------------------ | ------------------------------------ |
+| `name` from environment  | `name`                   | Environment identifier               |
+| `plugins`                | `plugins`                | Plugin configuration                 |
+| `source.decorators`      | `source.decorators`      | Decorator support                    |
+| `source.assetsInclude`   | `source.assetsInclude`   | Additional static asset patterns     |
+| `source.define`          | `source.define`          | Global constants                     |
+| `source.include`         | `source.include`         | Source inclusion patterns            |
+| `source.exclude`         | `source.exclude`         | Source exclusion patterns            |
+| `source.transformImport` | `source.transformImport` | On-demand import transform rules     |
+| `source.tsconfigPath`    | `source.tsconfigPath`    | TypeScript config path               |
+| `resolve`                | `resolve`                | Module resolution                    |
+| `output.cssModules`      | `output.cssModules`      | CSS modules configuration            |
+| `tools.rspack`           | `tools.rspack`           | Rspack configuration                 |
+| `tools.swc`              | `tools.swc`              | SWC configuration                    |
+| `tools.bundlerChain`     | `tools.bundlerChain`     | Bundler chain configuration          |
+| `output.target`          | `testEnvironment`        | 'happy-dom' for web, 'node' for node |
 
 The adapter also removes the `rsbuild:type-check` plugin because type checking is not part of the test runtime pipeline.
 

diff --git a/website/docs/en/guide/integration/rslib.mdx b/website/docs/en/guide/integration/rslib.mdx
@@ -178,22 +178,23 @@ The adapter automatically maps these Rslib options to Rstest:
 
 Only the fields listed below are inherited. Rslib options that are not listed are ignored by default, which means test-irrelevant sections such as `dev`, `server`, and `html` are automatically pruned during conversion.
 
-| Rslib option           | Rstest equivalent      | Notes                                                  |
-| ---------------------- | ---------------------- | ------------------------------------------------------ |
-| `lib.id`               | `name`                 | Library identifier                                     |
-| `plugins`              | `plugins`              | Plugin configuration                                   |
-| `source.decorators`    | `source.decorators`    | Decorator support                                      |
-| `source.assetsInclude` | `source.assetsInclude` | Additional static asset patterns                       |
-| `source.define`        | `source.define`        | Global constants                                       |
-| `source.include`       | `source.include`       | Source inclusion patterns                              |
-| `source.exclude`       | `source.exclude`       | Source exclusion patterns                              |
-| `source.tsconfigPath`  | `source.tsconfigPath`  | TypeScript config path                                 |
-| `resolve`              | `resolve`              | Module resolution                                      |
-| `output.cssModules`    | `output.cssModules`    | CSS modules configuration                              |
-| `tools.rspack`         | `tools.rspack`         | Rspack configuration                                   |
-| `tools.swc`            | `tools.swc`            | SWC configuration                                      |
-| `tools.bundlerChain`   | `tools.bundlerChain`   | Bundler chain configuration                            |
-| `output.target`        | `testEnvironment`      | 'happy-dom' for web, 'node' for node and other targets |
+| Rslib option             | Rstest equivalent        | Notes                                                  |
+| ------------------------ | ------------------------ | ------------------------------------------------------ |
+| `lib.id`                 | `name`                   | Library identifier                                     |
+| `plugins`                | `plugins`                | Plugin configuration                                   |
+| `source.decorators`      | `source.decorators`      | Decorator support                                      |
+| `source.assetsInclude`   | `source.assetsInclude`   | Additional static asset patterns                       |
+| `source.define`          | `source.define`          | Global constants                                       |
+| `source.include`         | `source.include`         | Source inclusion patterns                              |
+| `source.exclude`         | `source.exclude`         | Source exclusion patterns                              |
+| `source.transformImport` | `source.transformImport` | On-demand import transform rules                       |
+| `source.tsconfigPath`    | `source.tsconfigPath`    | TypeScript config path                                 |
+| `resolve`                | `resolve`                | Module resolution                                      |
+| `output.cssModules`      | `output.cssModules`      | CSS modules configuration                              |
+| `tools.rspack`           | `tools.rspack`           | Rspack configuration                                   |
+| `tools.swc`              | `tools.swc`              | SWC configuration                                      |
+| `tools.bundlerChain`     | `tools.bundlerChain`     | Bundler chain configuration                            |
+| `output.target`          | `testEnvironment`        | 'happy-dom' for web, 'node' for node and other targets |
 
 ## Debug config
 

diff --git a/website/docs/zh/config/build/source.mdx b/website/docs/zh/config/build/source.mdx
@@ -54,6 +54,36 @@ export default defineConfig({
 
 指定额外需要编译的 JavaScript 文件。
 
+## source.transformImport <RsbuildDocBadge path="/config/source/transform-import" text="source.transformImport" />
+
+<ApiMeta addedVersion="0.9.6" />
+
+配置按需导入转换规则。
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  source: {
+    transformImport: [
+      {
+        libraryName: 'demo-lib',
+        libraryDirectory: '.',
+        camelToDashComponentName: false,
+      },
+    ],
+  },
+});
+```
+
+:::caution
+
+`source.transformImport` 会在编译阶段改写最终的模块请求。
+
+当前实现下，`rs.mock('pkg')`、`rs.doMock('pkg')`、`rs.importActual('pkg')`、`rs.requireActual('pkg')` 这类仍然使用原始 specifier 的模块级 mock API，可能无法命中被改写后的模块请求。
+
+:::
+
 ## source.tsconfigPath <RsbuildDocBadge path="/config/source/tsconfig-path" text="source.tsconfigPath" />
 
 配置自定义的 `tsconfig.json` 文件路径，可以是相对路径或绝对路径。
diff --git a/website/docs/zh/config/test/extends.mdx b/website/docs/zh/config/test/extends.mdx
@@ -163,7 +163,7 @@ export default defineConfig({
 
 ### 示例：从 Rslib 配置扩展
 
-使用 `@rstest/adapter-rslib` 适配器可从现有 Rslib 配置文件扩展 Rstest 配置。该适配器会自动映射兼容选项，如 `source.define`、`source.include`、`source.exclude` 等。
+使用 `@rstest/adapter-rslib` 适配器可从现有 Rslib 配置文件扩展 Rstest 配置。该适配器会自动映射兼容选项，如 `source.define`、`source.include`、`source.exclude`、`source.transformImport` 等。
 
 ```ts
 import { defineConfig } from '@rstest/core';

diff --git a/website/docs/zh/guide/integration/rsbuild.mdx b/website/docs/zh/guide/integration/rsbuild.mdx
@@ -175,22 +175,23 @@ export default defineConfig({
 
 下表中列出的字段会被继承；没有列出的 Rsbuild 选项默认不会进入 Rstest 配置。这意味着 `dev`、`server`、`html` 等与测试运行无关的配置会被自动忽略。
 
-| Rsbuild 选项            | Rstest 等效项          | 说明                                       |
-| ----------------------- | ---------------------- | ------------------------------------------ |
-| `name` from environment | `name`                 | 环境标识符                                 |
-| `plugins`               | `plugins`              | 插件配置                                   |
-| `source.decorators`     | `source.decorators`    | 装饰器支持                                 |
-| `source.assetsInclude`  | `source.assetsInclude` | 额外的静态资源匹配规则                     |
-| `source.define`         | `source.define`        | 全局常量                                   |
-| `source.include`        | `source.include`       | 源文件包含模式                             |
-| `source.exclude`        | `source.exclude`       | 源文件排除模式                             |
-| `source.tsconfigPath`   | `source.tsconfigPath`  | TypeScript 配置文件路径                    |
-| `resolve`               | `resolve`              | 模块解析                                   |
-| `output.cssModules`     | `output.cssModules`    | CSS 模块配置                               |
-| `tools.rspack`          | `tools.rspack`         | Rspack 配置                                |
-| `tools.swc`             | `tools.swc`            | SWC 配置                                   |
-| `tools.bundlerChain`    | `tools.bundlerChain`   | Bundler 链配置                             |
-| `output.target`         | `testEnvironment`      | web 环境为 'happy-dom'，node 环境为 'node' |
+| Rsbuild 选项             | Rstest 等效项            | 说明                                       |
+| ------------------------ | ------------------------ | ------------------------------------------ |
+| `name` from environment  | `name`                   | 环境标识符                                 |
+| `plugins`                | `plugins`                | 插件配置                                   |
+| `source.decorators`      | `source.decorators`      | 装饰器支持                                 |
+| `source.assetsInclude`   | `source.assetsInclude`   | 额外的静态资源匹配规则                     |
+| `source.define`          | `source.define`          | 全局常量                                   |
+| `source.include`         | `source.include`         | 源文件包含模式                             |
+| `source.exclude`         | `source.exclude`         | 源文件排除模式                             |
+| `source.transformImport` | `source.transformImport` | 按需导入转换规则                           |
+| `source.tsconfigPath`    | `source.tsconfigPath`    | TypeScript 配置文件路径                    |
+| `resolve`                | `resolve`                | 模块解析                                   |
+| `output.cssModules`      | `output.cssModules`      | CSS 模块配置                               |
+| `tools.rspack`           | `tools.rspack`           | Rspack 配置                                |
+| `tools.swc`              | `tools.swc`              | SWC 配置                                   |
+| `tools.bundlerChain`     | `tools.bundlerChain`     | Bundler 链配置                             |
+| `output.target`          | `testEnvironment`        | web 环境为 'happy-dom'，node 环境为 'node' |
 
 另外，适配器还会移除 `rsbuild:type-check` 插件，因为类型检查不属于测试运行时所需的构建链路。
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		export const foo = () => 'actual';
		export default foo;