diff --git a/website/docs/en/config/test/projects.mdx b/website/docs/en/config/test/projects.mdx index 924271ae..93c4d072 100644 --- a/website/docs/en/config/test/projects.mdx +++ b/website/docs/en/config/test/projects.mdx @@ -17,10 +17,6 @@ Define multiple test projects. It can be an array of directories, configuration Rstest will run the tests for each project according to the configuration defined in each project, and the test results from all projects will be combined and displayed. -You can filter the specified projects to run by using the [--project](/guide/basic/test-filter#filter-by-project-name) option. - -If there is no `projects` field, `rstest` will treat current directory as a single project. - ```ts name='rstest.config.ts' import { defineConfig } from '@rstest/core'; @@ -52,67 +48,4 @@ export default defineConfig({ }); ``` -## Configuration notes - -- Project configuration does not inherit root configuration. If there is shared configuration between your sub-projects, you can extract the shared configuration and import it in the sub-project. -- Some root-level options such as `reporters`, `pool`, and `isolate` are not valid in a project configuration. - -```ts title='packages/pkg-a/rstest.config.ts' -import { defineConfig } from '@rstest/core'; -import sharedConfig from '../shared/rstest.config'; - -export default defineConfig({ - ...sharedConfig, -}); -``` - -## Inline configuration - -`rstest` supports configuring projects inline in the `projects` field. This lets you define multiple test projects in a single root without creating separate config files for each test project. - -```ts name='rstest.config.ts' -import { defineConfig } from '@rstest/core'; - -export default defineConfig({ - projects: [ - // inline project configs - { - name: 'node', - include: ['tests/node/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], - }, - { - name: 'react', - include: ['tests/react/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], - testEnvironment: 'jsdom', - }, - ], -}); -``` - -## Nested projects - -Rstest supports nested project definitions within the rstest config of sub-projects. This allows you to define more test projects in sub-projects without having to define all projects in the root project. - -This is especially useful when your sub-projects need to support multiple test environments or multiple configurations. - -### Example - -Define Node.js and browser test environments for `packages/pkg-a`: - -```ts title='packages/pkg-a/rstest.config.ts' -import { defineConfig } from '@rstest/core'; - -export default defineConfig({ - projects: [ - { - name: 'node', - include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s?(x)'], - }, - { - name: 'react', - include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'], - testEnvironment: 'jsdom', - }, - ], -}); -``` +More information about projects can be found in [Test projects](/guide/basic/projects). diff --git a/website/docs/en/guide/advanced/debugging.mdx b/website/docs/en/guide/advanced/debugging.mdx index e7b248f1..26a49e37 100644 --- a/website/docs/en/guide/advanced/debugging.mdx +++ b/website/docs/en/guide/advanced/debugging.mdx @@ -2,7 +2,7 @@ ## Debug mode -Rstest provides a debug mode to troubleshoot problems, you can add the `DEBUG=rstest` environment variable when building to enable Rstest's debug mode. +Rstest provides a debug mode to troubleshoot problems, you can add the `DEBUG=rstest` environment variable when testing to enable Rstest's debug mode. ```bash DEBUG=rstest pnpm test diff --git a/website/docs/en/guide/basic/_meta.json b/website/docs/en/guide/basic/_meta.json index 3583e3e3..d36bb506 100644 --- a/website/docs/en/guide/basic/_meta.json +++ b/website/docs/en/guide/basic/_meta.json @@ -1 +1,8 @@ -["cli", "configure-rstest", "test-filter", "vscode-extension", "upgrade-rstest"] +[ + "cli", + "configure-rstest", + "test-filter", + "projects", + "vscode-extension", + "upgrade-rstest" +] diff --git a/website/docs/en/guide/basic/projects.mdx b/website/docs/en/guide/basic/projects.mdx new file mode 100644 index 00000000..29374ee9 --- /dev/null +++ b/website/docs/en/guide/basic/projects.mdx @@ -0,0 +1,156 @@ +# Test projects + +Rstest supports running multiple test projects simultaneously within a single Rstest process. These projects can have different test configurations and test environments. + +## Use cases + +- **Monorepo projects**: When your codebase contains multiple sub-packages or modules, each sub-project might have different test configuration requirements. +- **Different test environments**: Different sub-projects (or even the same sub-project) might need to run in different environments (e.g., Node environment and browser environment). +- **File-specific testing**: You can specify different test or build configurations for specific test files/directories. + +## Example + +Define each sub-project in a monorepo as a project through the [projects](/config/test/projects) field, where each sub-project has its own test configuration. + +Rstest will automatically recognize each subdirectory under the `packages` directory as an independent test project and run tests according to the [rstest.config.ts](/guide/basic/configure-rstest#configuration-files) file (if present) in the subdirectory. + +```ts name='rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + // A monorepo: each package directory is a project + 'packages/*', + ], +}); +``` + +## Configuration description + +You can define multiple test projects through the [projects](/config/test/projects) field. Rstest will run the corresponding tests according to the configurations defined by each project, and all test results will be merged and displayed. + +If there is no `projects` field, `rstest` will treat the current directory as a single project. + +### Configuration syntax + +The `projects` field supports the following configuration methods: + +- **Directory path**: Specify a directory, and Rstest will automatically recognize all subdirectories under that directory as projects. +- **Configuration file path**: Specify a configuration file path, and Rstest will run tests according to that file's configuration. +- **Glob pattern**: Use glob patterns to match multiple directories or files, and Rstest will use the matching results as projects. +- **Inline configuration object**: Directly define project configuration objects in the `projects` field. This allows you to define multiple test projects within a single project without creating separate configuration files for each test project. +- **Nested projects**: Define projects nested within the rstest config of sub-projects. + +```ts name='rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + // A monorepo: each package directory is a project + 'packages/*', + + // All projects under the apps directory that provide an rstest config file + 'apps/**/rstest.config.ts', + + // A specific project directory + '/services/auth', + + // A specific project's config file + './projects/web/rstest.config.ts', + + // inline project configs + { + name: 'node', + include: ['tests/node/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], + }, + { + name: 'react', + include: ['tests/react/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], + testEnvironment: 'jsdom', + }, + ], +}); +``` + +### Root configuration + +When the `projects` field exists in the root directory's rstest config file, Rstest will not treat it as a test project. In this case, the root directory's rstest.config file is only used to define `projects` and [global configuration](#global-configuration). + +If you want to treat the root directory as a project as well, you can define the test configuration for the root directory in `projects`. + +```ts name='rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + { + name: 'root', + include: ['/tests/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], + }, + 'packages/*', + ], +}); +``` + +#### Global configuration + +The following configurations are global configurations and are invalid when configured in projects. If you need to modify global configuration, you need to configure it in the root project's rstest config or override it through CLI options. + +- `reporters`: Global reporters configuration. +- `pool`: Global pool configuration. +- `isolate`: Global isolate configuration. +- `coverage`: Global coverage configuration. +- `bail`: Global bail configuration. + +### Project configuration + +Project configuration does not inherit the configuration from the root directory. Only the `projects` field and [global configuration](#global-configuration) in the root directory are effective. + +If there are reusable configuration items between your sub-projects, you can extract shared configurations and introduce them in sub-projects respectively: + +```ts title='packages/pkg-a/rstest.config.ts' +import { defineConfig, mergeRstestConfig } from '@rstest/core'; +import sharedConfig from '../shared/rstest.config'; + +export default mergeRstestConfig(sharedConfig, { + name: 'pkg-a', +}); +``` + +You can override all project configurations through [CLI options](/guide/basic/cli#cli-options). + +### Nested projects + +Rstest supports defining nested projects in sub-project rstest config files. This allows you to define more test projects in sub-projects without defining all projects in the root project. + +This is especially useful when your sub-projects need to support multiple test environments or multiple configurations. + +For example, define Node.js and browser test environments for `packages/pkg-a`: + +```ts title='packages/pkg-a/rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + { + name: 'node', + include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s?(x)'], + }, + { + name: 'react', + include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'], + testEnvironment: 'jsdom', + }, + ], +}); +``` + +### Inspect configuration + +If you want to view the final effective configuration of Rstest, you can enable [debug mode](/guide/advanced/debugging#debug-mode) through the `DEBUG=rstest` environment variable. Rstest will write the final effective Rstest configuration and build configuration to the output directory. + +## Filtering projects + +You can filter projects through the [--project](/guide/basic/test-filter#filter-by-project-name) CLI option, or you can filter specific files under projects by directly filtering file names or file paths. + +For more information, please refer to the [Test Filtering](/guide/basic/test-filter) chapter. diff --git a/website/docs/en/guide/start/features.mdx b/website/docs/en/guide/start/features.mdx index 7c687051..8a8adc54 100644 --- a/website/docs/en/guide/start/features.mdx +++ b/website/docs/en/guide/start/features.mdx @@ -16,7 +16,7 @@ Rstest is powered by Rspack, enabling high-performance builds and optimizations Rstest provides multi-project testing capabilities, allowing you to run tests for multiple projects in parallel within a single Rstest process. -Learn more about [Projects](/config/test/projects). +Learn more about [Test projects](/guide/basic/projects). ## In-source tests diff --git a/website/docs/zh/config/test/projects.mdx b/website/docs/zh/config/test/projects.mdx index 8a200da9..69464605 100644 --- a/website/docs/zh/config/test/projects.mdx +++ b/website/docs/zh/config/test/projects.mdx @@ -15,10 +15,6 @@ type Projects = (string | ProjectConfig)[]; 定义多个测试项目,可以是一个目录、配置文件或 glob 模式,也可以是一个对象。 Rstest 将会按照各个项目定义的配置运行对应的测试,所有项目的测试结果将会合并展示。 -你可以通过 [--project](/guide/basic/test-filter#根据项目名称过滤) 选项来过滤运行特定项目。 - -如果没有 `projects` 字段,`rstest` 会将当前目录视为单个项目。 - ```ts name='rstest.config.ts' import { defineConfig } from '@rstest/core'; @@ -50,69 +46,4 @@ export default defineConfig({ }); ``` -## 配置说明 - -需要注意的是: - -- project 配置并不会继承全局配置,如果你的子项目间存在共享配置,可以抽取 shared 配置,并在子项目中引入 -- 一些全局配置,如 `reporters`、`pool`、`isolate` 等,在 project 配置中是无效的 - -```ts title='packages/pkg-a/rstest.config.ts' -import { defineConfig } from '@rstest/core'; -import sharedConfig from '../shared/rstest.config'; - -export default defineConfig({ - ...sharedConfig, -}); -``` - -## 内联配置 - -Rstest 支持在 `projects` 字段中直接通过内联的方式配置 project。这允许你在单个项目下定义多个测试项目,而无需为每个测试项目创建单独的配置文件。 - -```ts name='rstest.config.ts' -import { defineConfig } from '@rstest/core'; - -export default defineConfig({ - projects: [ - // inline project configs - { - name: 'node', - include: ['tests/node/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], - }, - { - name: 'react', - include: ['tests/react/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], - testEnvironment: 'jsdom', - }, - ], -}); -``` - -## 嵌套 Projects - -Rstest 支持在子项目的 rstest config 中嵌套定义 projects。这允许你在子项目中定义更多的测试项目,而无需在根项目中定义所有项目。 - -这尤其适用于你的子项目需要同时支持多个测试环境或多份配置的情况。 - -### 示例 - -为 `packages/pkg-a` 定义 Node.js 和浏览器两个测试环境: - -```ts title='packages/pkg-a/rstest.config.ts' -import { defineConfig } from '@rstest/core'; - -export default defineConfig({ - projects: [ - { - name: 'node', - include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s?(x)'], - }, - { - name: 'react', - include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'], - testEnvironment: 'jsdom', - }, - ], -}); -``` +更多关于项目配置的信息,请参考[多项目测试](/guide/basic/projects)。 diff --git a/website/docs/zh/guide/advanced/debugging.mdx b/website/docs/zh/guide/advanced/debugging.mdx index 149089ef..0d19639b 100644 --- a/website/docs/zh/guide/advanced/debugging.mdx +++ b/website/docs/zh/guide/advanced/debugging.mdx @@ -2,7 +2,7 @@ ## 开启调试模式 -为了便于排查问题,Rstest 提供了调试模式,你可以在执行构建时添加 `DEBUG=rstest` 环境变量来开启 Rstest 的调试模式。 +为了便于排查问题,Rstest 提供了调试模式,你可以在执行测试时添加 `DEBUG=rstest` 环境变量来开启 Rstest 的调试模式。 ```bash DEBUG=rstest pnpm test diff --git a/website/docs/zh/guide/basic/_meta.json b/website/docs/zh/guide/basic/_meta.json index 3583e3e3..d36bb506 100644 --- a/website/docs/zh/guide/basic/_meta.json +++ b/website/docs/zh/guide/basic/_meta.json @@ -1 +1,8 @@ -["cli", "configure-rstest", "test-filter", "vscode-extension", "upgrade-rstest"] +[ + "cli", + "configure-rstest", + "test-filter", + "projects", + "vscode-extension", + "upgrade-rstest" +] diff --git a/website/docs/zh/guide/basic/projects.mdx b/website/docs/zh/guide/basic/projects.mdx new file mode 100644 index 00000000..48af16c8 --- /dev/null +++ b/website/docs/zh/guide/basic/projects.mdx @@ -0,0 +1,156 @@ +# 多项目测试 + +Rstest 支持在单个 Rstest 进程中同时运行多个测试项目,这些项目可以有不同的测试配置和环境。 + +## 适用场景 + +- Monorepo 项目:当你的代码库包含多个子包或模块时,每个子项目可能有不同的测试配置需求。 +- 不同环境:不同 / 同一个子项目可能需要在不同的环境下运行(例如,Node 环境和浏览器环境)。 +- 针对特定文件的测试:你可以为特定的测试文件 / 目录指定不同的测试或构建配置。 + +## 示例 + +通过 [projects](/config/test/projects) 字段在 monorepo 中将每个子项目定义为一个 project,每个子项目有自己的测试配置。 + +Rstest 会自动识别 `packages` 目录下的每个子目录作为一个独立的测试项目,并根据子目录中的 [rstest.config.ts](/guide/basic/configure-rstest#配置文件) 文件(如果存在)配置进行测试。 + +```ts name='rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + // A monorepo: each package directory is a project + 'packages/*', + ], +}); +``` + +## 配置说明 + +你可以通过 [projects](/config/test/projects) 字段定义多个测试项目。Rstest 将会按照各个项目定义的配置运行对应的测试,所有项目的测试结果将会合并展示。 + +如果没有 `projects` 字段,`rstest` 会将当前目录视为单个项目。 + +### 配置语法 + +`projects` 字段支持以下几种配置方式: + +- 目录路径:指定一个目录,Rstest 会自动识别该目录下的所有子目录作为项目。 +- 配置文件路径:指定一个配置文件路径,Rstest 会根据该文件的配置运行测试。 +- glob 模式:使用 glob 模式匹配多个目录或文件,Rstest 会根据匹配结果作为项目。 +- 内联配置对象:直接在 `projects` 字段中定义项目的配置对象。这允许你在单个项目下定义多个测试项目,而无需为每个测试项目创建单独的配置文件 +- 嵌套 projects:在子项目的 rstest config 中嵌套定义 projects。 + +```ts name='rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + // A monorepo: each package directory is a project + 'packages/*', + + // All projects under the apps directory that provide an rstest config file + 'apps/**/rstest.config.ts', + + // A specific project directory + '/services/auth', + + // A specific project's config file + './projects/web/rstest.config.ts', + + // inline project configs + { + name: 'node', + include: ['tests/node/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], + }, + { + name: 'react', + include: ['tests/react/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], + testEnvironment: 'jsdom', + }, + ], +}); +``` + +### 根目录配置 + +当根目录的 rstest config 文件中存在 projects 字段时,Rstest 不会将其视为一个测试项目,此时,根目录的 rstest.config 文件仅用于定义 `projects` 和[全局配置](#全局配置)。 + +如果你希望将根目录也视为一个项目,可以在 `projects` 中定义根目录下的测试配置。 + +```ts name='rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + { + name: 'root', + include: ['/tests/**/*.{test,spec}.{js,cjs,mjs,ts,tsx}'], + }, + 'packages/*', + ], +}); +``` + +#### 全局配置 + +以下配置为全局配置,在 project 中配置无效。如果你需要修改全局配置,需要在根项目的 rstest config 中配置或通过 CLI 选项覆盖。 + +- `reporters`:全局 reporters 配置。 +- `pool`:全局 pool 配置。 +- `isolate`:全局 isolate 配置。 +- `coverage`:全局 coverage 配置。 +- `bail`:全局 bail 配置。 + +### Project 配置 + +Project 配置并不会继承根目录下的配置,根目录下仅 projects 字段和[全局配置](#全局配置)生效。 + +如果你的子项目间存在可复用的配置项,可以抽取 shared 配置,并分别在子项目中引入: + +```ts title='packages/pkg-a/rstest.config.ts' +import { defineConfig, mergeRstestConfig } from '@rstest/core'; +import sharedConfig from '../shared/rstest.config'; + +export default mergeRstestConfig(sharedConfig, { + name: 'pkg-a', +}); +``` + +可通过 [CLI 选项](/guide/basic/cli#cli-选项) 覆盖所有项目配置。 + +### 嵌套 projects + +Rstest 支持在子项目的 rstest config 中嵌套定义 projects。这允许你在子项目中定义更多的测试项目,而无需在根项目中定义所有项目。 + +这尤其适用于你的子项目需要同时支持多个测试环境或多份配置的情况。 + +如,为 `packages/pkg-a` 定义 Node.js 和浏览器两个测试环境: + +```ts title='packages/pkg-a/rstest.config.ts' +import { defineConfig } from '@rstest/core'; + +export default defineConfig({ + projects: [ + { + name: 'node', + include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s?(x)'], + }, + { + name: 'react', + include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'], + testEnvironment: 'jsdom', + }, + ], +}); +``` + +### 查看配置 + +如果你希望查看 Rstest 最终生效的配置,可以通过 `DEBUG=rstest` 环境变量开启[调试模式](/guide/advanced/debugging#开启调试模式),Rstest 会将最终生效的 Rstest 配置及构建配置写入到产物目录下。 + +## 过滤项目 + +你可以通过 [--project](/guide/basic/test-filter#根据项目名称过滤) CLI 选项来过滤项目,也可以直接通过过滤文件名或文件路径的方式来过滤运行项目下的特定文件。 + +更多介绍请参考 [测试过滤](/guide/basic/test-filter) 章节。 diff --git a/website/docs/zh/guide/start/features.mdx b/website/docs/zh/guide/start/features.mdx index 4270f5a9..745c8869 100644 --- a/website/docs/zh/guide/start/features.mdx +++ b/website/docs/zh/guide/start/features.mdx @@ -16,7 +16,7 @@ Rstest 底层使用 Rspack 构建,能够在 Rstest 中享受 Rspack 带来的 Rstest 提供了多项目测试的能力,支持在单个 Rstest 进程中并行对多个项目进行测试。 -了解更多关于 [多项目测试](/config/test/projects)。 +了解更多关于 [多项目测试](/guide/basic/projects)。 ## 源码内联测试 diff --git a/website/rspress.config.ts b/website/rspress.config.ts index 63058362..8fa832b7 100644 --- a/website/rspress.config.ts +++ b/website/rspress.config.ts @@ -18,7 +18,9 @@ export default defineConfig({ logo: 'https://assets.rspack.rs/rstest/rstest-logo.svg', logoText: 'Rstest', markdown: { - checkDeadLinks: true, + link: { + checkDeadLinks: true, + }, }, search: { codeBlocks: true, @@ -47,29 +49,20 @@ export default defineConfig({ content: 'https://discord.gg/XsaKEEk4mW', }, ], + editLink: { + docRepoBaseUrl: + 'https://github.com/web-infra-dev/rstest/tree/main/website/docs', + }, locales: [ { lang: 'en', label: 'English', description, - editLink: { - docRepoBaseUrl: - 'https://github.com/web-infra-dev/rstest/tree/main/website/docs', - text: '📝 Edit this page on GitHub', - }, }, { lang: 'zh', label: '简体中文', - outlineTitle: '目录', - prevPageText: '上一页', - nextPageText: '下一页', description: '由 Rspack 驱动的测试框架', - editLink: { - docRepoBaseUrl: - 'https://github.com/web-infra-dev/rstest/tree/main/website/docs', - text: '📝 在 GitHub 上编辑此页', - }, }, ], }, @@ -102,5 +95,12 @@ export default defineConfig({ }, }), ], + performance: { + printFileSize: { + total: true, + detail: false, + compressed: false, + }, + }, }, });