Skip to content

Commit 1fd1fbc

Browse files
chenjiahanchenjiahan
authored
docs: improve testing configuration inheritance (#448)
1 parent 05b662f commit 1fd1fbc

2 files changed

Lines changed: 130 additions & 52 deletions

File tree

‎website/docs/en/guide/testing.mdx‎

Lines changed: 65 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
description: 'Run tests with Rstack CLI, inherit application or library settings through Rstest adapters, and configure multiple test projects.'
3+
---
4+
15
# Testing
26

37
Rstack CLI uses [Rstest](https://rstest.rs/) to run tests.
@@ -28,23 +32,80 @@ Import test APIs and configuration helpers from [`rstack/test`](./api-reference#
2832
import { defineInlineProject, expect, test } from 'rstack/test';
2933
```
3034

31-
## Single project
35+
## Configuration inheritance
36+
37+
When `define.test()` does not set Rstest's [`extends`](https://rstest.rs/config/test/extends), Rstack CLI automatically converts the configuration registered by `define.app()` or `define.lib()` into an Rstest configuration. The inherited configuration is merged with the options passed directly to `define.test()`.
38+
39+
### Inherit the application configuration
3240

33-
For a single test project, pass the Rstest options directly to `define.test()`:
41+
When `define.app()` is registered, Rstack CLI converts it with [`@rstest/adapter-rsbuild`](https://rstest.rs/guide/integration/rsbuild) and uses the result as the test configuration's `extends` value:
3442

3543
```ts title="rstack.config.ts"
3644
import { define } from 'rstack';
3745

3846
define.app({
39-
// Shared application configuration
47+
resolve: {
48+
alias: {
49+
'@': './src',
50+
},
51+
},
4052
});
4153

4254
define.test({
55+
// Inherits `resolve.alias` from `define.app()`.
4356
testEnvironment: 'happy-dom',
4457
});
4558
```
4659

47-
When `extends` is omitted, Rstack CLI uses the Rsbuild adapter to extend the test configuration from `define.app()`. If no application configuration is defined, it uses the Rslib adapter with `define.lib()` instead. `define.app()` takes precedence when both are defined.
60+
### Inherit the library configuration
61+
62+
When `define.lib()` is registered, Rstack CLI converts it with [`@rstest/adapter-rslib`](https://rstest.rs/guide/integration/rslib):
63+
64+
```ts title="rstack.config.ts"
65+
import { define } from 'rstack';
66+
67+
define.lib({
68+
resolve: {
69+
alias: {
70+
'@': './src',
71+
},
72+
},
73+
});
74+
75+
define.test({
76+
// Inherits `resolve.alias` from `define.lib()`.
77+
testEnvironment: 'node',
78+
});
79+
```
80+
81+
:::tip
82+
83+
When both configurations are registered, Rstack CLI gives `define.app()` precedence.
84+
85+
:::
86+
87+
### Disable automatic inheritance
88+
89+
To keep the test configuration independent, set `extends` explicitly. An empty object disables automatic inheritance without extending another configuration:
90+
91+
```ts title="rstack.config.ts"
92+
import { define } from 'rstack';
93+
94+
define.app({
95+
resolve: {
96+
alias: {
97+
'@': './src',
98+
},
99+
},
100+
});
101+
102+
define.test({
103+
extends: {},
104+
testEnvironment: 'node',
105+
});
106+
```
107+
108+
For multiple projects, setting `extends` on the root `define.test()` configuration disables automatic inheritance for every project. Setting it on an inline project disables inheritance only for that project.
48109

49110
## Multiple projects
50111

@@ -101,25 +162,3 @@ define.test({
101162
```
102163

103164
Rstack CLI passes string entries to Rstest unchanged. External projects load their own configuration and do not inherit the current `define.app()` or `define.lib()` configuration. Use external projects when each project manages its configuration independently.
104-
105-
## Customize inheritance
106-
107-
Set Rstest's [`extends`](https://rstest.rs/config/test/extends) option explicitly when a project should not inherit the current application or library configuration:
108-
109-
```ts title="rstack.config.ts"
110-
import { define } from 'rstack';
111-
import { defineInlineProject } from 'rstack/test';
112-
113-
define.test({
114-
projects: [
115-
defineInlineProject({
116-
name: 'standalone',
117-
extends: {
118-
testEnvironment: 'node',
119-
},
120-
}),
121-
],
122-
});
123-
```
124-
125-
Setting `extends` on an inline project disables automatic inheritance only for that project. Setting it on the root `define.test()` configuration disables automatic inheritance for the entire test configuration.

‎website/docs/zh/guide/testing.mdx‎

Lines changed: 65 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
description: '使用 Rstack CLI 运行测试，通过 Rstest 适配器继承应用或库配置，并配置多个测试项目。'
3+
---
4+
15
# 测试 \{#testing}
26

37
Rstack CLI 使用 [Rstest](https://rstest.rs/zh/) 运行测试。
@@ -28,23 +32,80 @@ define.test({
2832
import { defineInlineProject, expect, test } from 'rstack/test';
2933
```
3034

31-
## 单项目 \{#single-project}
35+
## 配置继承 \{#configuration-inheritance}
36+
37+
当 `define.test()` 未设置 Rstest 的 [`extends`](https://rstest.rs/zh/config/test/extends) 时，Rstack CLI 会自动将 `define.app()` 或 `define.lib()` 注册的配置转换为 Rstest 配置，再与直接传给 `define.test()` 的选项合并。
38+
39+
### 继承应用配置 \{#inherit-the-application-configuration}
3240

33-
对于单个测试项目，直接将 Rstest 选项传给 `define.test()`：
41+
注册 `define.app()` 后，Rstack CLI 会通过 [`@rstest/adapter-rsbuild`](https://rstest.rs/zh/guide/integration/rsbuild) 转换该配置，并将结果作为测试配置的 `extends`：
3442

3543
```ts title="rstack.config.ts"
3644
import { define } from 'rstack';
3745

3846
define.app({
39-
// 共享的应用配置
47+
resolve: {
48+
alias: {
49+
'@': './src',
50+
},
51+
},
4052
});
4153

4254
define.test({
55+
// 继承 `define.app()` 中的 `resolve.alias`
4356
testEnvironment: 'happy-dom',
4457
});
4558
```
4659

47-
未设置 `extends` 时，Rstack CLI 会通过 Rsbuild 适配器让测试配置继承 `define.app()`。如果没有应用配置，则通过 Rslib 适配器回退到 `define.lib()`。同时定义两者时，`define.app()` 的优先级更高。
60+
### 继承库配置 \{#inherit-the-library-configuration}
61+
62+
注册 `define.lib()` 后，Rstack CLI 会通过 [`@rstest/adapter-rslib`](https://rstest.rs/zh/guide/integration/rslib) 转换该配置：
63+
64+
```ts title="rstack.config.ts"
65+
import { define } from 'rstack';
66+
67+
define.lib({
68+
resolve: {
69+
alias: {
70+
'@': './src',
71+
},
72+
},
73+
});
74+
75+
define.test({
76+
// 继承 `define.lib()` 中的 `resolve.alias`
77+
testEnvironment: 'node',
78+
});
79+
```
80+
81+
:::tip
82+
83+
同时注册两种配置时，Rstack CLI 会优先使用 `define.app()`。
84+
85+
:::
86+
87+
### 关闭自动继承 \{#disable-automatic-inheritance}
88+
89+
如果测试配置需要保持独立，请显式设置 `extends`。将它设置为空对象可以关闭自动继承，且不会继承其他配置：
90+
91+
```ts title="rstack.config.ts"
92+
import { define } from 'rstack';
93+
94+
define.app({
95+
resolve: {
96+
alias: {
97+
'@': './src',
98+
},
99+
},
100+
});
101+
102+
define.test({
103+
extends: {},
104+
testEnvironment: 'node',
105+
});
106+
```
107+
108+
使用多项目配置时，在 `define.test()` 根配置中设置 `extends` 会关闭所有项目的自动继承；在某个内联项目中设置 `extends` 则只会关闭该项目的自动继承。
48109

49110
## 多项目 \{#multiple-projects}
50111

@@ -101,25 +162,3 @@ define.test({
101162
```
102163

103164
Rstack CLI 会将字符串形式的项目原样传给 Rstest。外部项目会加载自己的配置，不会继承当前的 `define.app()` 或 `define.lib()` 配置。每个项目需要独立管理配置时，请使用外部项目。
104-
105-
## 自定义继承 \{#customize-inheritance}
106-
107-
项目不应继承当前应用或库配置时，请显式设置 Rstest 的 [`extends`](https://rstest.rs/zh/config/test/extends) 选项：
108-
109-
```ts title="rstack.config.ts"
110-
import { define } from 'rstack';
111-
import { defineInlineProject } from 'rstack/test';
112-
113-
define.test({
114-
projects: [
115-
defineInlineProject({
116-
name: 'standalone',
117-
extends: {
118-
testEnvironment: 'node',
119-
},
120-
}),
121-
],
122-
});
123-
```
124-
125-
在内联项目中设置 `extends`，只会关闭当前项目的自动继承。在 `define.test()` 的根配置中设置该选项，则会关闭整个测试配置的自动继承。

0 commit comments

Comments
 (0)