docs: add testing guide

README.md

@@ -113,54 +113,6 @@ For example, import Rstest APIs without adding `@rstest/core` as a direct depend
 import { expect, test } from 'rstack/test';
 ```
 
-## Test projects
-
-`define.test()` accepts an Rstest configuration. For a single project, Rstack automatically applies the `define.app()` configuration, or falls back to `define.lib()`:
-
-```ts
-import { define } from 'rstack';
-
-define.app({
-  // Rsbuild configuration
-});
-
-define.test({
-  testEnvironment: 'happy-dom',
-});
-```
-
-For multiple test environments in the same app or library, use inline projects:
-
-```ts
-import { define } from 'rstack';
-import { defineInlineProject } from 'rstack/test';
-
-define.app({
-  // Shared by all inline projects
-});
-
-define.test({
-  projects: [
-    defineInlineProject({
-      name: 'node',
-      include: ['./tests/node/**/*.test.ts'],
-      testEnvironment: 'node',
-    }),
-    defineInlineProject({
-      name: 'dom',
-      include: ['./tests/dom/**/*.test.tsx'],
-      testEnvironment: 'happy-dom',
-    }),
-  ],
-});
-```
-
-Rstack applies the shared app or library adapter to every inline project without an explicit `extends`. String project entries are passed to Rstest unchanged and load their own configuration.
-
-Run all projects with `rs test`, or select one with `rs test --project dom`.
-
-See [`examples/rstest-inline-projects`](./examples/rstest-inline-projects) for a complete React SSR example.
-
 ## Credits
 
 Rstack CLI is inspired by:

examples/documentation/docs/api/_meta.json

@@ -1 +1 @@
-["index", "commands", "testing"]
+["index", "commands"]

website/docs/en/guide/_meta.json

@@ -18,6 +18,15 @@
     "name": "api-reference",
     "label": "API reference"
   },
+  {
+    "type": "section-header",
+    "label": "Practices"
+  },
+  {
+    "type": "file",
+    "name": "testing",
+    "label": "Testing"
+  },
   {
     "type": "dir-section-header",
     "name": "cli",

website/docs/en/guide/api-reference.mdx

@@ -55,6 +55,8 @@ import { describe, expect, test } from 'rstack/test';
 
 See the [Rstest runtime API](https://rstest.rs/api/runtime-api/) for test APIs and the [Rstest core APIs](https://rstest.rs/api/javascript-api/rstest-core) for configuration helpers.
 
+> For more guidance on testing, see [Testing](./testing).
+
 ### `rstack/lint`
 
 `rstack/lint` re-exports all public APIs from `@rslint/core`, including JavaScript and TypeScript presets and framework plugins.

website/docs/en/guide/cli/test.mdx

@@ -2,6 +2,8 @@
 
 The `rs test` command uses [Rstest](https://rstest.rs/guide/basic/cli) to run tests.
 
+For more guidance on testing, see [Testing](../testing).
+
 ## Usage
 
 ```bash

website/docs/en/guide/configuration.mdx

@@ -144,6 +144,8 @@ When `extends` is omitted, Rstack automatically connects the test configuration
 
 If the root test configuration does not define `extends` and contains `projects`, Rstack applies automatic inheritance to each inline project that omits its own `extends`. A function-based application or library configuration is resolved once and shared by those projects. String project entries are passed to Rstest unchanged; they load their external configurations independently and do not inherit the current application or library configuration.
 
+> For more guidance on testing, see [Testing](./testing).
+
 ### `define.lint()` \{#define-lint}
 
 Defines the [Rslint configuration](https://rslint.rs/config/). Pass the configuration directly, or use an async function to load presets and plugins from `rstack/lint` on demand.

website/docs/en/guide/testing.mdx

@@ -0,0 +1,125 @@
+# Testing
+
+Rstack uses [Rstest](https://rstest.rs/) to run tests.
+
+```bash
+rs test
+```
+
+For command-line options and subcommands, see [`rs test`](./cli/test).
+
+## Configure tests
+
+Register an Rstest configuration with [`define.test()`](./configuration#define-test). It accepts the same configuration as Rstest's `defineConfig()`:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.test({
+  testEnvironment: 'node',
+});
+```
+
+## Test APIs
+
+Import test APIs and configuration helpers from [`rstack/test`](./api-reference#rstacktest):
+
+```ts
+import { defineInlineProject, expect, test } from 'rstack/test';
+```
+
+## Single project
+
+For a single test project, pass the Rstest options directly to `define.test()`:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.app({
+  // Shared application configuration
+});
+
+define.test({
+  testEnvironment: 'happy-dom',
+});
+```
+
+When `extends` is omitted, Rstack 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.
+
+## Multiple projects
+
+Set Rstest's [`projects`](https://rstest.rs/config/test/projects) option to run multiple test configurations together. Entries can be inline projects or strings that Rstest resolves as external projects.
+
+### Inline projects
+
+Use inline projects when different test environments should share the current application or library configuration:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+import { defineInlineProject } from 'rstack/test';
+
+define.app({
+  // Shared by both inline projects
+});
+
+define.test({
+  projects: [
+    defineInlineProject({
+      name: 'node',
+      include: ['./tests/node/**/*.test.ts'],
+      testEnvironment: 'node',
+    }),
+    defineInlineProject({
+      name: 'dom',
+      include: ['./tests/dom/**/*.test.tsx'],
+      testEnvironment: 'happy-dom',
+    }),
+  ],
+});
+```
+
+Rstack applies the corresponding adapter to each inline project that omits `extends`. A function-based `define.app()` or `define.lib()` configuration is resolved once, then shared by those inline projects.
+
+Run one project by name:
+
+```bash
+rs test --project dom
+```
+
+See [`examples/rstest-inline-projects`](https://github.com/rstackjs/rstack-cli/tree/main/examples/rstest-inline-projects) for a complete React SSR example using Node.js and happy-dom.
+
+### External projects
+
+Use a string entry for an externally configured project:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.test({
+  projects: ['./legacy/rstest.config.ts'],
+});
+```
+
+Rstack 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.
+
+## Customize inheritance
+
+Set Rstest's [`extends`](https://rstest.rs/config/test/extends) option explicitly when a project should not inherit the current application or library configuration:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+import { defineInlineProject } from 'rstack/test';
+
+define.test({
+  projects: [
+    defineInlineProject({
+      name: 'standalone',
+      extends: {
+        testEnvironment: 'node',
+      },
+    }),
+  ],
+});
+```
+
+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/_meta.json

@@ -18,6 +18,15 @@
     "name": "api-reference",
     "label": "API 参考"
   },
+  {
+    "type": "section-header",
+    "label": "实践"
+  },
+  {
+    "type": "file",
+    "name": "testing",
+    "label": "测试"
+  },
   {
     "type": "dir-section-header",
     "name": "cli",

website/docs/zh/guide/api-reference.mdx

@@ -55,6 +55,8 @@ import { describe, expect, test } from 'rstack/test';
 
 测试 API 请参阅 [Rstest 运行时 API](https://rstest.rs/zh/api/runtime-api/)，配置辅助 API 请参阅 [Rstest 核心 API](https://rstest.rs/zh/api/javascript-api/rstest-core)。
 
+> 如需了解更多测试相关用法，请参阅[测试](./testing)。
+
 ### `rstack/lint`
 
 `rstack/lint` 重导出 `@rslint/core` 的全部公开 API，包括 JavaScript 和 TypeScript 预设以及框架插件。

website/docs/zh/guide/cli/test.mdx

@@ -2,6 +2,8 @@
 
 `rs test` 命令使用 [Rstest](https://rstest.rs/zh/guide/basic/cli) 运行测试。
 
+如需了解更多测试相关用法，请参阅[测试](../testing)。
+
 ## 用法 \{#usage}
 
 ```bash

website/docs/zh/guide/configuration.mdx

@@ -144,6 +144,8 @@ define.test({
 
 如果测试根配置未定义 `extends` 且包含 `projects`，Rstack 会为每个未自行设置 `extends` 的内联项目应用自动继承。函数形式的应用或库配置只会解析一次，并由这些项目共享。字符串形式的项目会原样传给 Rstest；它们会独立加载外部配置，不继承当前应用或库的配置。
 
+> 如需了解更多测试相关用法，请参阅[测试](./testing)。
+
 ### `define.lint()` \{#define-lint}
 
 定义 [Rslint 配置](https://rslint.rs/config/)。可以直接传入配置，也可以使用异步函数，按需从 `rstack/lint` 加载预设和插件。