From 05972a65754cbc4d3a83bf9a747963923e5630a0 Mon Sep 17 00:00:00 2001 From: 9aoy <9aoyuao@gmail.com> Date: Thu, 8 Jan 2026 12:09:19 +0800 Subject: [PATCH 1/4] docs: update rslib integration guide --- packages/adapter-rslib/README.md | 131 +------------------- website/docs/en/guide/integration/rslib.mdx | 112 ++++++++++++++++- website/docs/zh/guide/integration/rslib.mdx | 118 ++++++++++++++++-- 3 files changed, 220 insertions(+), 141 deletions(-) diff --git a/packages/adapter-rslib/README.md b/packages/adapter-rslib/README.md index df54ca0ca..49c967ad0 100644 --- a/packages/adapter-rslib/README.md +++ b/packages/adapter-rslib/README.md @@ -20,133 +20,4 @@ export default defineConfig({ }); ``` -## API - -### withRslibConfig(options) - -Returns a promise that loads Rslib config and converts it to Rstest configuration. - -#### Options - -- `cwd` (string): Working directory to resolve Rslib config file. Default: `process.cwd()` -- `configPath` (string): Path to Rslib config file. Default: `'./rslib.config.ts'` -- `libId` (string): The lib config id in `lib` field to use. Set to a string to use the lib config with matching id. Default: `undefined` -- `modifyLibConfig` (function): Function to modify Rslib config before conversion. Default: `undefined` - -The adapter automatically copies and maps compatible configuration options from Rslib to Rstest: - -**From Rslib → to Rstest:** - -The adapter automatically maps these Rslib options to Rstest: - -| Rslib option | Rstest equivalent | Notes | -| --------------------- | --------------------- | ------------------------------------ | -| `lib.id` | `name` | Library identifier | -| `plugins` | `plugins` | Plugin configuration | -| `source.decorators` | `source.decorators` | Decorator support | -| `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 | - -## Advanced usage - -### Specifying working directory - -By default, the adapter uses `process.cwd()` as the working directory to resolve the Rslib config file. - -When your Rslib config is in a different directory or you are running tests in a monorepo (which your `process.cwd()` is not your config directory), you can specify the `cwd` option to resolve the Rslib config file from a different directory. - -```ts -export default defineConfig({ - extends: withRslibConfig({ - cwd: './packages/my-lib', - }), -}); -``` - -### Using specific lib configuration - -By default, the adapter does not use any lib configuration from Rslib. - -If your Rslib config has multiple lib configurations with different `id` values: - -```ts -// 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, - }, - }, - }, - ], - // shared config -}); -``` - -You can then reference specific lib configurations in your Rstest config, Rstest will adapt the Rslib shared configuration and lib configuration with matching `id` value to Rstest format. - -```ts -// For testing the core library -export default defineConfig({ - extends: withRslibConfig({ - libId: 'core', - }), - // core-specific test config -}); -``` - -### Multiple lib configurations - -When you need to test multiple libraries with different configurations independently, you can define multiple Rstest projects. Each project can extend a specific library configuration by setting the `libId` option. - -```ts -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)'], - }, - ], -}); -``` - -### Modifying Rslib config - -You can modify the Rslib config before it gets converted to Rstest config: - -```ts -export default defineConfig({ - extends: withRslibConfig({ - modifyLibConfig: (libConfig) => { - delete libConfig.source?.define; - return libConfig; - }, - }), -}); -``` +More advanced usage examples can be found in the [Rslib integration guide](https://rstest.rs/guide/integration/rslib). diff --git a/website/docs/en/guide/integration/rslib.mdx b/website/docs/en/guide/integration/rslib.mdx index 76bc50253..fc96b55ef 100644 --- a/website/docs/en/guide/integration/rslib.mdx +++ b/website/docs/en/guide/integration/rslib.mdx @@ -48,7 +48,22 @@ This will automatically: - Map compatible Rslib options to Rstest configuration - Merge with any additional Rstest config you provide -By default, the adapter uses `process.cwd()` to resolve the Rslib config. If your config lives elsewhere, set `cwd`: +By default, the adapter uses `process.cwd()` to resolve the Rslib config. If your config lives elsewhere, you can use the `cwd` option. See [API](#api) for more details. + +## API + +### `withRslibConfig(options)` + +Returns a configuration function that loads Rslib config and converts it to Rstest configuration. + +#### `cwd` + +- **Type:** `string` +- **Default:** `process.cwd()` + +The `cwd` is the working directory to resolve the Rslib config file. + +When your Rslib config is in a different directory or you are running tests in a monorepo (where your `process.cwd()` is not your config directory), you can specify the `cwd` option to resolve the Rslib config file from a different directory. ```ts export default defineConfig({ @@ -58,9 +73,98 @@ export default defineConfig({ }); ``` -See the [`@rstest/adapter-rslib` documentation](https://www.npmjs.com/package/@rstest/adapter-rslib) for advanced options. +#### `configPath` + +- **Type:** `string` +- **Default:** `'./rslib.config.ts'` + +Path to rslib config file. + +#### `libId` + +- **Type:** `string` +- **Default:** `undefined` + +The lib config id in `lib` field to use. Set to a string to use the lib config with matching id. + +By default, the adapter uses the common configuration from Rslib. If your Rslib config has multiple lib configurations: + +```ts +// 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, + }, + }, + }, + ], + // shared config +}); +``` + +You can then reference specific lib configurations in your Rstest config. Rstest will adapt the Rslib shared configuration and the lib configuration with a matching `libId` to Rstest format. + +```ts +// For testing the 'core' environment +export default defineConfig({ + extends: withRslibConfig({ + libId: 'core', + }), + // core-specific test config +}); +``` + +When you need to test multiple parts of your application with different configurations independently, you can define multiple Rstest projects. Each project can extend a specific lib configuration by setting the `libId` option. + +```ts +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` + +- **Type:** `(config: RslibConfig) => RslibConfig | void` +- **Default:** `undefined` + +Modify the Rslib config before it gets converted to Rstest config: + +```ts +export default defineConfig({ + extends: withRslibConfig({ + modifyLibConfig: (libConfig) => { + delete libConfig.source?.define; + return libConfig; + }, + }), +}); +``` -### Configuration mapping +## Configuration mapping The adapter automatically maps these Rslib options to Rstest: @@ -80,7 +184,7 @@ The adapter automatically maps these Rslib options to Rstest: | `tools.bundlerChain` | `tools.bundlerChain` | Bundler chain configuration | | `output.target` | `testEnvironment` | 'happy-dom' for web, 'node' for node and other targets | -### Debug config +## Debug config To see the resolved configuration returned by the adapter, wrap it and log the result: diff --git a/website/docs/zh/guide/integration/rslib.mdx b/website/docs/zh/guide/integration/rslib.mdx index 4c8586317..2b0d951c9 100644 --- a/website/docs/zh/guide/integration/rslib.mdx +++ b/website/docs/zh/guide/integration/rslib.mdx @@ -48,19 +48,123 @@ export default defineConfig({ - 将兼容的 Rslib 选项映射到 Rstest 配置 - 与你提供的其他 Rstest 配置合并 -默认情况下，适配器使用 `process.cwd()` 来解析 Rslib 配置。如果配置文件在其他目录，可以设置 `cwd`： +默认情况下，适配器使用 `process.cwd()` 来解析 Rslib 配置。如果配置文件在其他目录，可以使用 `cwd` 选项。更多详情请参阅 [API](#api)。 + +## API + +### `withRslibConfig(options)` + +返回一个加载 Rslib 配置并将其转换为 Rstest 配置的函数。 + +#### `cwd` + +- **类型:** `string` +- **默认值:** `process.cwd()` + +`cwd` 是用于解析 Rslib 配置文件的当前工作目录。 + +当你的 Rslib 配置文件位于不同目录，或者你在 monorepo 中运行测试（此时 `process.cwd()` 可能不是你的配置目录）时，可以指定 `cwd` 选项从不同的目录解析 Rslib 配置文件。 + +```ts +export default defineConfig({ + extends: withRslibConfig({ + cwd: './packages/my-app', + }), +}); +``` + +#### `configPath` + +- **类型:** `string` +- **默认值:** `'./rslib.config.ts'` + +Rslib 配置文件的路径。 + +#### `libId` + +- **类型:** `string` +- **默认值:** `undefined` + +要使用的 `lib` 字段中的 lib 配置 ID。设置为字符串以使用具有匹配 ID 的 lib 配置。 + +默认情况下，适配器使用 Rslib 的通用配置。如果你的 Rslib 配置有多个 lib 配置： ```ts +// 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 格式。 + +```ts +// 用于测试 'core' 环境 export default defineConfig({ extends: withRslibConfig({ - cwd: './packages/my-lib', + libId: 'core', }), + // core-specific test config }); ``` -更多高级选项请参考 [`@rstest/adapter-rslib` 文档](https://www.npmjs.com/package/@rstest/adapter-rslib)。 +当你需要使用不同的配置独立测试应用程序的多个部分时，可以定义多个 Rstest project。每个 project 都可以通过设置 `libId` 选项来扩展特定的 lib 配置。 + +```ts +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 配置之前对其进行修改： + +```ts +export default defineConfig({ + extends: withRslibConfig({ + modifyLibConfig: (libConfig) => { + delete libConfig.source?.define; + return libConfig; + }, + }), +}); +``` -### 配置映射 +## 配置映射 适配器会自动将以下 Rslib 选项映射到 Rstest： @@ -80,14 +184,14 @@ export default defineConfig({ | `tools.bundlerChain` | `tools.bundlerChain` | Bundler chain 配置 | | `output.target` | `testEnvironment` | `web` 映射为 'happy-dom'，`node` 及其他映射为 'node' | -### 调试配置 +## 调试配置 如需查看适配器返回的解析后配置，可以打印结果： ```typescript export default defineConfig({ - extends: async (user) => { - const config = await withRslibConfig({ libId: 'react' })(user); + extends: async (user) => {. + const config = await withRslibConfig()(user); console.log('Extended config:', JSON.stringify(config, null, 2)); return config; }, From 90683b45f07f0ed26010dc36eae1e75b5eb13b34 Mon Sep 17 00:00:00 2001 From: 9aoy <9aoyuao@gmail.com> Date: Thu, 8 Jan 2026 13:26:40 +0800 Subject: [PATCH 2/4] Update website/docs/zh/guide/integration/rslib.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- website/docs/zh/guide/integration/rslib.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/zh/guide/integration/rslib.mdx b/website/docs/zh/guide/integration/rslib.mdx index 2b0d951c9..a93977a17 100644 --- a/website/docs/zh/guide/integration/rslib.mdx +++ b/website/docs/zh/guide/integration/rslib.mdx @@ -190,7 +190,7 @@ export default defineConfig({ ```typescript export default defineConfig({ - extends: async (user) => {. + extends: async (user) => { const config = await withRslibConfig()(user); console.log('Extended config:', JSON.stringify(config, null, 2)); return config; From c820ecc3ef3fcf5a168f5c92554c6cc35df951d7 Mon Sep 17 00:00:00 2001 From: 9aoy <9aoyuao@gmail.com> Date: Thu, 8 Jan 2026 13:27:12 +0800 Subject: [PATCH 3/4] Update website/docs/zh/guide/integration/rslib.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- website/docs/zh/guide/integration/rslib.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/zh/guide/integration/rslib.mdx b/website/docs/zh/guide/integration/rslib.mdx index a93977a17..6cfc58351 100644 --- a/website/docs/zh/guide/integration/rslib.mdx +++ b/website/docs/zh/guide/integration/rslib.mdx @@ -191,7 +191,7 @@ export default defineConfig({ ```typescript export default defineConfig({ extends: async (user) => { - const config = await withRslibConfig()(user); + const config = await withRslibConfig({ libId: 'react' })(user); console.log('Extended config:', JSON.stringify(config, null, 2)); return config; }, From 04feb6300e3bcbd24677e2aab5dd9cf96a22934c Mon Sep 17 00:00:00 2001 From: 9aoy <9aoyuao@gmail.com> Date: Thu, 8 Jan 2026 13:27:33 +0800 Subject: [PATCH 4/4] Update website/docs/zh/guide/integration/rslib.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- website/docs/zh/guide/integration/rslib.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/zh/guide/integration/rslib.mdx b/website/docs/zh/guide/integration/rslib.mdx index 6cfc58351..7a975bee9 100644 --- a/website/docs/zh/guide/integration/rslib.mdx +++ b/website/docs/zh/guide/integration/rslib.mdx @@ -68,7 +68,7 @@ export default defineConfig({ ```ts export default defineConfig({ extends: withRslibConfig({ - cwd: './packages/my-app', + cwd: './packages/my-lib', }), }); ```