docs: polish up (#375)

fi3ework · web-flow · commit bd5949a917f8 · 2025-07-09T19:05:30.000+08:00
diff --git a/packages/core/tests/rstestEnv.d.ts b/packages/core/tests/rstestEnv.d.ts
@@ -0,0 +1 @@
+/// <reference types="@rstest/core/globals" />
diff --git a/packages/core/tests/tsconfig.json b/packages/core/tests/tsconfig.json
@@ -1,8 +1,7 @@
 {
   "extends": "@rstest/tsconfig/base",
   "compilerOptions": {
-    "baseUrl": "./",
-    "types": ["@rstest/core/globals"]
+    "baseUrl": "./"
   },
   "include": ["./**/*.ts"]
 }
diff --git a/tests/globals/fixtures/rstestEnv.d.ts b/tests/globals/fixtures/rstestEnv.d.ts
@@ -0,0 +1 @@
+/// <reference types="@rstest/core/globals" />
diff --git a/tests/globals/fixtures/tsconfig.json b/tests/globals/fixtures/tsconfig.json
@@ -1,8 +1,7 @@
 {
   "extends": "@rstest/tsconfig/base",
   "compilerOptions": {
-    "baseUrl": "./",
-    "types": ["@rstest/core/globals"]
+    "baseUrl": "./"
   },
   "include": ["./**/*.ts"]
 }
diff --git a/tests/in-source/fixtures/rslib.config.ts b/tests/in-source/fixtures/rslib.config.ts
@@ -9,7 +9,7 @@ export default defineConfig({
   ],
   source: {
     define: {
-      'import.meta.rstest': undefined,
+      'import.meta.rstest': false,
     },
   },
 });
diff --git a/tests/in-source/fixtures/src/rstestEnv.d.ts b/tests/in-source/fixtures/src/rstestEnv.d.ts
@@ -0,0 +1 @@
+/// <reference types="@rstest/core/importMeta" />
diff --git a/tests/in-source/fixtures/tsconfig.json b/tests/in-source/fixtures/tsconfig.json
@@ -9,8 +9,7 @@
     "isolatedModules": true,
     "resolveJsonModule": true,
     "moduleResolution": "bundler",
-    "useDefineForClassFields": true,
-    "types": ["@rstest/core/importMeta"]
+    "useDefineForClassFields": true
   },
   "include": ["src"]
 }
diff --git a/website/docs/en/config/test/disableConsoleIntercept.mdx b/website/docs/en/config/test/disableConsoleIntercept.mdx
@@ -6,4 +6,4 @@
 
 Disable interception of console logs. By default, Rstest intercepts the console log, which will help track log sources.
 
-If you don't want Rstest to intercept console logs, you can set this configuration to `true`. It should be noted that when you disable interception of console logs, the `onConsoleLog` and `printConsoleTrace` configurations will not take effect.
+If you don't want Rstest to intercept console logs, you can set this configuration to `true`. It should be noted that when you disable interception of console logs, the [onConsoleLog](/config/test/onConsoleLog) and [printConsoleTrace](/config/test/printConsoleTrace) configurations will not take effect.
diff --git a/website/docs/en/config/test/globals.mdx b/website/docs/en/config/test/globals.mdx
@@ -22,7 +22,7 @@ export default defineConfig({
 
 ## Usage
 
-When you enable `globals`, you can use the global APIs directly without `import from '@rstest/core'`.
+When you enable `globals`, you can use the global APIs directly without `import { ... } from '@rstest/core'`.
 
 ```diff title="index.test.ts"
 - import { describe, expect, it } from '@rstest/core';
@@ -36,12 +36,8 @@ describe('Index', () => {
 
 ### TypeScript support
 
-To get TypeScript working with the global APIs, add `@rstest/core/globals` to the types field in your `tsconfig.json`
+To get TypeScript working with the global APIs, you can create a `src/rstestEnv.d.ts` file to reference:
 
-```json title=tsconfig.json
-{
-  "compilerOptions": {
-    "types": ["@rstest/core/globals"]
-  }
-}
+```ts title=rstestEnv.d.ts
+/// <reference types="@rstest/core/globals" />
 ```
diff --git a/website/docs/en/config/test/includeSource.mdx b/website/docs/en/config/test/includeSource.mdx
@@ -46,22 +46,16 @@ import { defineConfig } from '@rsbuild/core';
 export default defineConfig({
   source: {
     define: {
-+      'import.meta.rstest': undefined,
++      'import.meta.rstest': false,
     },
   },
 });
 ```
 
 ### TypeScript
 
-To get TypeScript support for `import.meta.rstest`, you should add `@rstest/core/importMeta` to your `tsconfig.json`:
+To get TypeScript support for `import.meta.rstest`, you can create a `src/rstestEnv.d.ts` file to reference:
 
-```diff title=tsconfig.json
-{
-  "compilerOptions": {
-    "types": [
-+      "@rstest/core/importMeta"
-    ]
-  }
-}
+```ts title=rstestEnv.d.ts
+/// <reference types="@rstest/core/importMeta" />
 ```
diff --git a/website/docs/en/config/test/onConsoleLog.mdx b/website/docs/en/config/test/onConsoleLog.mdx
@@ -14,3 +14,7 @@ export default defineConfig({
   onConsoleLog: (log) => log.includes('test'),
 });
 ```
+
+:::note
+When [disableConsoleIntercept](/config/test/disableConsoleIntercept) is set to `true`, `onConsoleLog` will be ignored.
+:::
diff --git a/website/docs/en/config/test/printConsoleTrace.mdx b/website/docs/en/config/test/printConsoleTrace.mdx
@@ -13,3 +13,7 @@ export default defineConfig({
   printConsoleTrace: true,
 });
 ```
+
+:::note
+When [disableConsoleIntercept](/config/test/disableConsoleIntercept) is set to `true`, `printConsoleTrace` will be ignored.
+:::
diff --git a/website/docs/en/config/test/root.mdx b/website/docs/en/config/test/root.mdx
@@ -5,3 +5,5 @@
 - **CLI:** `-r=<path>`, `--root=<path>`
 
 Specify the project root directory. Can be an absolute path, or a path relative to `process.cwd()`.
+
+`root` determines the starting point for loading configuration files, searching test files, etc.
diff --git a/website/docs/en/config/test/testEnvironment.mdx b/website/docs/en/config/test/testEnvironment.mdx
@@ -32,18 +32,20 @@ export default defineConfig({
 
 You also need to install the corresponding package:
 
-```bash
-# For jsdom
-npm install jsdom -D
+import { PackageManagerTabs } from '@theme';
 
-# For happy-dom
-npm install happy-dom -D
-```
+For jsdom
+
+<PackageManagerTabs command="add jsdom -D" />
+
+For happy-dom
+
+<PackageManagerTabs command="add happy-dom -D" />
 
 After enabling DOM testing, you can write tests that use browser APIs like `document` and `window`.
 
 ```ts
-test('dom test', () => {
+test('DOM test', () => {
   document.body.innerHTML = '<p class="content">hello world</p>';
   const paragraph = document.querySelector('.content');
   expect(paragraph?.innerHTML).toBe('hello world');
diff --git a/website/docs/zh/config/test/disableConsoleIntercept.mdx b/website/docs/zh/config/test/disableConsoleIntercept.mdx
@@ -6,4 +6,4 @@
 
 禁用 console 日志的拦截。默认情况下，Rstest 会对 console 日志做拦截，这样将有助于追踪日志来源。
 
-如果你不想要 Rstest 对 console 日志做拦截，你可以将此配置设为 `true`。需要注意的是，当你禁用 console 日志的拦截时，`onConsoleLog` 和 `printConsoleTrace` 配置将不会生效。
+如果你不想要 Rstest 对 console 日志做拦截，你可以将此配置设为 `true`。需要注意的是，当你禁用 console 日志的拦截时，[onConsoleLog](/config/test/onConsoleLog) 和 [printConsoleTrace](/config/test/printConsoleTrace) 配置将不会生效。
diff --git a/website/docs/zh/config/test/globals.mdx b/website/docs/zh/config/test/globals.mdx
@@ -22,7 +22,7 @@ export default defineConfig({
 
 ## 使用
 
-当你启用 `globals` 后，就可以直接使用全局 API，而无需 `import from '@rstest/core'`。
+当你启用 `globals` 后，就可以直接使用全局 API，而无需 `import { ... } from '@rstest/core'`。
 
 ```diff title="index.test.ts"
 - import { describe, expect, it } from '@rstest/core';
@@ -36,12 +36,8 @@ describe('Index', () => {
 
 ### 类型支持
 
-为了让 TypeScript 支持全局 API，请在 `tsconfig.json` 的 types 字段中添加 `@rstest/core/globals`。
+为了让 TypeScript 支持全局 API，你可以创建一个 `src/rstestEnv.d.ts` 文件来引用：
 
-```json title=tsconfig.json
-{
-  "compilerOptions": {
-    "types": ["@rstest/core/globals"]
-  }
-}
+```ts title=rstestEnv.d.ts
+/// <reference types="@rstest/core/globals" />
 ```
diff --git a/website/docs/zh/config/test/includeSource.mdx b/website/docs/zh/config/test/includeSource.mdx
@@ -46,22 +46,16 @@ import { defineConfig } from '@rsbuild/core';
 export default defineConfig({
   source: {
     define: {
-+      'import.meta.rstest': undefined,
++      'import.meta.rstest': false,
     },
   },
 });
 ```
 
 ### TypeScript
 
-如需让 TypeScript 支持 `import.meta.rstest`，可在 `tsconfig.json` 中添加 `@rstest/core/importMeta`：
+如需让 TypeScript 支持 `import.meta.rstest`，你可以创建一个 `src/rstestEnv.d.ts` 文件来引用：
 
-```diff title=tsconfig.json
-{
-  "compilerOptions": {
-    "types": [
-+      "@rstest/core/importMeta"
-    ]
-  }
-}
+```ts title=rstestEnv.d.ts
+/// <reference types="@rstest/core/importMeta" />
 ```
diff --git a/website/docs/zh/config/test/onConsoleLog.mdx b/website/docs/zh/config/test/onConsoleLog.mdx
@@ -14,3 +14,7 @@ export default defineConfig({
   onConsoleLog: (log) => log.includes('test'),
 });
 ```
+
+:::note
+当 [disableConsoleIntercept](/config/test/disableConsoleIntercept) 为 `true` 时，`onConsoleLog` 将被忽略。
+:::
diff --git a/website/docs/zh/config/test/printConsoleTrace.mdx b/website/docs/zh/config/test/printConsoleTrace.mdx
@@ -13,3 +13,7 @@ export default defineConfig({
   printConsoleTrace: true,
 });
 ```
+
+:::note
+当 [disableConsoleIntercept](/config/test/disableConsoleIntercept) 为 `true` 时，`printConsoleTrace` 将被忽略。
+:::
diff --git a/website/docs/zh/config/test/retry.mdx b/website/docs/zh/config/test/retry.mdx
@@ -12,7 +12,7 @@ overviewHeaders: []
 
 ## 示例
 
-你可以通过设置 `retry：2` 来获得两次重试在测试失败时：
+你可以通过设置 `retry: 2` 来指定测试失败后重试两次：
 
 ```ts title="rstest.config.ts"
 import { defineConfig } from '@rstest/core';
diff --git a/website/docs/zh/config/test/root.mdx b/website/docs/zh/config/test/root.mdx
@@ -5,3 +5,5 @@
 - **CLI：** `-r=<path>`, `--root=<path>`
 
 指定项目根目录。可以是绝对路径，也可以是相对于 `process.cwd()` 的路径。
+
+`root` 将决定配置文件加载的起点，测试文件被搜索的起点等。
diff --git a/website/docs/zh/config/test/testEnvironment.mdx b/website/docs/zh/config/test/testEnvironment.mdx
@@ -32,18 +32,20 @@ export default defineConfig({
 
 你还需要安装对应的包：
 
-```bash
-# 使用 jsdom
-npm install jsdom -D
+import { PackageManagerTabs } from '@theme';
 
-# 使用 happy-dom
-npm install happy-dom -D
-```
+使用 jsdom
+
+<PackageManagerTabs command="add jsdom -D" />
+
+使用 happy-dom
+
+<PackageManagerTabs command="add happy-dom -D" />
 
 启用 DOM 测试后，你可以在测试用例中使用 `document` 和 `window` 等浏览器 API。
 
 ```ts
-test('dom test', () => {
+test('DOM test', () => {
   document.body.innerHTML = '<p class="content">hello world</p>';
   const paragraph = document.querySelector('.content');
   expect(paragraph?.innerHTML).toBe('hello world');

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/// <reference types="@rstest/core/globals" />`
Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"extends": "@rstest/tsconfig/base",`
`3`	`3`	`"compilerOptions": {`
`4`		`- "baseUrl": "./",`
`5`		`- "types": ["@rstest/core/globals"]`
	`4`	`+ "baseUrl": "./"`
`6`	`5`	`},`
`7`	`6`	`"include": ["./*/.ts"]`
`8`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/// <reference types="@rstest/core/importMeta" />`
Original file line number	Diff line number	Diff line change
`@@ -6,4 +6,4 @@`
`6`	`6`
`7`	`7`	`Disable interception of console logs. By default, Rstest intercepts the console log, which will help track log sources.`
`8`	`8`
`9`		-If you don't want Rstest to intercept console logs, you can set this configuration to `true`. It should be noted that when you disable interception of console logs, the `onConsoleLog` and `printConsoleTrace` configurations will not take effect.
	`9`	+If you don't want Rstest to intercept console logs, you can set this configuration to `true`. It should be noted that when you disable interception of console logs, the [onConsoleLog](/config/test/onConsoleLog) and [printConsoleTrace](/config/test/printConsoleTrace) configurations will not take effect.