Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -613,7 +613,7 @@ export default ({ mode }: { mode: string }) => {
],
},
{
text: 'Browser Mode',
text: '浏览器模式',
collapsed: false,
items: [
{
Expand Down
8 changes: 3 additions & 5 deletions config/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,10 @@ outline: deep

Vitest 服务器可以通过 API 保存测试文件或快照文件。这意味着任何能连接到 API 的人都可以在你的机器上运行任意代码。

<!-- TODO: translation -->

In Browser Mode Vitest saves [annotation attachments](/guide/test-annotations), [artifacts](/api/advanced/artifacts) and [snapshots](/guide/snapshot) by receiving a WebSocket connection from the browser. This allows anyone who can connect to the API write any arbitrary code on your machine within the root of your project (configured by [`fs.allow`](https://vite.dev/config/server-options#server-fs-allow)). This option also gates privileged browser APIs that can write files indirectly, such as raw Chrome DevTools Protocol access through [`cdp()`](/api/browser/context#cdp).
在浏览器模式下,Vitest 通过接收来自浏览器的 WebSocket 连接来保存 [注解附件](/guide/test-annotations)、[产物](/api/advanced/artifacts) 和 [快照](/guide/snapshot)。这使得任何能够连接到 API 的人都可以在你机器上的项目根目录(由 [`fs.allow`](https://cn.vite.dev/config/server-options#server-fs-allow) 配置)内写入任意代码。此选项还会限制可间接写入文件的特权浏览器 API,例如通过 [`cdp()`](/api/browser/context#cdp) 直接访问 Chrome DevTools Protocol。

::: danger 安全警告
Vitest 默认不会将 API 暴露到互联网,仅在 `localhost` 上监听。但如果 `host` 被手动暴露到网络,任何连接到它的人都可以在你的机器上运行任意代码,除非将 `api.allowWrite` 和 `api.allowExec` 设置为`false`。
Vitest 默认不会将 API 暴露到互联网,仅在 `localhost` 上监听。但如果 `host` 被手动暴露到网络,任何连接到它的人都可以在你的机器上运行任意代码,除非将 `api.allowWrite` 和 `api.allowExec` 设置为 `false`。

如果 host 设置为 `localhost` 或 `127.0.0.1` 以外的任何值,Vitest 会默认将 `api.allowWrite` 和 `api.allowExec` 设置为 `false`。这意味着任何写入操作(例如 在 UI 模式中修改代码)将不起作用。如果你了解安全风险,可以覆盖这些设置。
:::
Expand All @@ -33,4 +31,4 @@ Vitest 默认不会将 API 暴露到互联网,仅在 `localhost` 上监听。
- **类型:** `boolean`
- **默认值:** `true` 表示未暴露在公共网络中,`false` 则表示已暴露

允许通过 API 运行任何测试文件。 This applies to the interactive elements (and the server code behind them) in the [UI](/guide/ui) that can run the code. This option also gates privileged browser APIs that can execute code indirectly, such as raw Chrome DevTools Protocol access through [`cdp()`](/api/browser/context#cdp).
允许通过 API 运行任何测试文件。适用于 [UI 模式](/guide/ui) 中能够运行代码的交互元素(以及其背后的服务端代码)。此选项还会限制可间接执行代码的特权浏览器 API,例如通过 [`cdp()`](/api/browser/context#cdp) 直接访问 Chrome DevTools Protocol。
4 changes: 2 additions & 2 deletions config/attachmentsdir.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,6 @@ outline: deep
- **类型:** `string`
- **默认值:** `'.vitest/attachments'`

Directory path for storing file attachments created by [`context.annotate`](/guide/test-context#annotate).
指定通过 [`context.annotate`](/guide/test-context#annotate) 创建的文件附件的存储目录。

This option is resolved relative to the root Vitest config. When using [`projects`](/guide/projects), all projects share the same `attachmentsDir`; it cannot be configured per project.
Vitest 会相对于根配置解析此路径。使用 [`projects`](/guide/projects) 时,所有项目共用同一个 `attachmentsDir`,无法为每个项目单独配置。
38 changes: 19 additions & 19 deletions config/benchmark.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,57 +7,57 @@ outline: deep

- **类型:** `{ include?, exclude?, ... }`

运行 `vitest bench` 时使用的选项
<!-- TODO: translation -->
运行 `vitest bench` 时生效的选项

## benchmark.enabled

- **Type:** `boolean`
- **Default:** `false`
- **类型:** `boolean`
- **默认值:** `false`

Enables the benchmark project. When set, Vitest creates a dedicated benchmark project alongside your regular test project, runs files matching [`benchmark.include`](#benchmark-include) in it, and exposes the [`bench` fixture](/guide/test-context#bench) to those files. Running `vitest bench` enables this automatically.
启用独立的基准测试项目。启用后,Vitest 会在常规测试项目之外创建一个专门用于基准测试的项目。该项目会运行与 [`benchmark.include`](#benchmark-include) 匹配的文件,并向这些文件提供 [`bench` fixture](/guide/test-context#bench)。运行 `vitest bench` 时,此选项会自动启用。

## benchmark.include

- **类型:** `string[]`
- **默认值:** `['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']`

匹配包含基准测试文件的 glob 规则
用于匹配基准测试文件的 glob 模式

## benchmark.exclude

- **类型:** `string[]`
- **默认值:** `['node_modules', 'dist', '.idea', '.git', '.cache']`

匹配排除基准测试文件的 glob 规则
用于排除基准测试文件的 glob 模式

## benchmark.includeSource

- **类型:** `string[]`
- **默认值:** `[]`

匹配包含内联基准测试文件的 glob 规则。此选项类似于 [`includeSource`](/config/include-source)。
用于匹配包含内联基准测试的源文件的 glob 模式。此选项与 [`includeSource`](/config/include-source) 类似

定义后,Vitest 将运行所有匹配的文件,其中包含 `import.meta.vitest`。
配置此选项后,Vitest 会运行所有符合模式且包含 `import.meta.vitest` 的文件

## benchmark.retainSamples

- **Type:** `boolean`
- **Default:** `false`
- **类型:** `boolean`
- **默认值:** `false`

Include the `samples` array of per-iteration timings on every benchmark result. Disabled by default to reduce memory usage; enable when a custom reporter or API consumer needs the raw samples.
启用后,每项基准测试的结果都会包含 `samples` 数组,用于记录每次迭代的耗时。此选项默认禁用,以减少内存占用。自定义报告器或 API 使用方需要原始采样数据时,可将其启用。

## benchmark.provider

- **Type:** `string`
- **Default:** `undefined` (uses the built-in provider)
- **类型:** `string`
- **默认值:** `undefined`(使用内置 provider

The benchmark provider that executes registered benchmarks and returns their results. Set this to a module path whose default export implements `BenchmarkProvider`. Relative paths are resolved from the project root.
指定负责执行已注册基准测试并返回结果的 provider。该选项应设置为模块路径,并且模块的默认导出必须实现 `BenchmarkProvider`。如果使用相对路径,Vitest 会从项目根目录开始解析。

See the [Custom Benchmark Provider](/guide/advanced/benchmark-provider) guide for setup instructions and the provider API.
有关配置方法和 provider API,请参阅 [自定义基准测试 provider](/guide/advanced/benchmark-provider) 指南。

## benchmark.suppressExportGetterWarnings

- **Type:** `boolean`
- **Default:** `false`
- **类型:** `boolean`
- **默认值:** `false`

Suppress the warning printed when a benchmark accesses module export getters too many times. Vitest tracks getter access during benchmark runs because Vite's module runner wraps every export in a getter, and excessive access can dominate the measurement (see [Module Runner Overhead](/guide/benchmarking#module-runner-overhead)). Enable this when you've intentionally accepted the overhead, or when the warning is noisy for benchmarks where the getter cost is negligible.
禁止显示因基准测试频繁访问模块导出 getter 而产生的警告。Vite 的模块运行器会将每个导出包装为 getter,因此 Vitest 会在基准测试运行期间记录 getter 的访问次数。访问过于频繁时,这部分开销可能成为影响测量结果的主要因素(参阅 [模块运行器开销](/guide/benchmarking#module-runner-overhead))。如果你已接受这项开销,或者 getter 的开销可以忽略不计但警告过于频繁造成了干扰,可启用此选项。
16 changes: 8 additions & 8 deletions config/browser/dependencysourcemaps.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
title: browser.dependencySourcemaps | Config
title: browser.dependencySourcemaps | 配置
outline: deep
---

# browser.dependencySourcemaps

- **Type:** `boolean`
- **Default:** `true`
- **类型:** `boolean`
- **默认值:** `true`

Serve sourcemaps of your dependencies (files in `node_modules`) to the browser during headless test runs.
在无头模式下运行测试时,向浏览器提供依赖项(即 `node_modules` 中的文件)的 source map。

These sourcemaps are used by browser devtools: with `dependencySourcemaps: false`, pausing inside dependency code shows the compiled code the browser actually runs instead of the dependency's original sources. If you don't debug into your dependencies this way, disabling them makes test runs faster: the server doesn't generate and inline the maps, and every browser tab downloads several times fewer bytes.
浏览器开发者工具会使用这些 source map。设置 `dependencySourcemaps: false` 后,如果调试时暂停在依赖项代码中,开发者工具会显示浏览器实际运行的编译后代码,而不是依赖项的原始源代码。如果不需要以这种方式调试依赖项,可以禁用此选项来加快测试速度。禁用后,服务器无需生成并内联这些 source map,每个浏览器标签页需要下载的数据量也会减少数倍。

Reported test errors are not affected: when an error is thrown inside a pre-bundled dependency, Vitest maps its stack frames using the sourcemaps stored on disk even when this option is disabled. Frames from dependencies that are served without pre-bundling (for example, [linked packages](https://vite.dev/guide/dep-pre-bundling#monorepos-and-linked-dependencies)) that don't ship their own sourcemaps fall back to the position in the served code, which usually matches the original file.
测试错误的报告结果不受此选项影响。如果错误由预打包的依赖项抛出,即使禁用了此选项,Vitest 仍会使用存储在磁盘上的 source map 映射堆栈帧。对于未经过预打包便直接提供的依赖项,例如 [链接的包](https://cn.vite.dev/guide/dep-pre-bundling#monorepos-and-linked-dependencies),如果它们自身不包含 source map,堆栈帧会回退到所提供代码中的位置。该位置通常与原始文件一致。

Vitest never serves sourcemaps of its own pre-built modules in headless runs (unless [`--inspect`](/guide/cli#inspect) is used) — their frames are hidden from stack traces anyway. Sourcemaps of your own source files are always served.
在无头模式下运行测试时,Vitest 不会提供自身预构建模块的 source map,除非使用 [`--inspect`](/guide/cli#inspect)。这些模块的堆栈帧本来就会从堆栈跟踪中隐藏。项目自身源文件的 source map 则始终会提供给浏览器。

::: tip
If some of your workspace code resolves to a `node_modules` path (for example, with `resolve.preserveSymlinks`), set [`server.sourcemapIgnoreList`](https://vite.dev/config/server-options#server-sourcemapignorelist) to keep its sourcemaps even when this option is disabled.
如果工作区中的部分代码被解析为 `node_modules` 下的路径,例如启用了 `resolve.preserveSymlinks`,请配置 [`server.sourcemapIgnoreList`](https://cn.vite.dev/config/server-options#server-sourcemapignorelist),确保即使禁用了此选项,浏览器仍能获取这些代码的 source map。
:::
12 changes: 6 additions & 6 deletions config/browser/expect.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,15 @@ export default defineConfig({
```

[`toMatchScreenshot` 断言中所有可用选项](/api/browser/assertions#options) 均可在此配置。此外还提供两个路径解析函数:`resolveScreenshotPath` 和 `resolveDiffPath`。
<!-- TODO: translation -->

## browser.expect.toMatchScreenshot.screenshotDirectory

- **Type:** `string | undefined`
- **Default:** `__screenshots__`
- **类型:** `string | undefined`
- **默认值:** `__screenshots__`

The directory name used for storing reference screenshots.
用于存放参考截图的目录名称。

This value is passed as `screenshotDirectory` to [`browser.expect.toMatchScreenshot.resolveScreenshotPath`](#browserexpecttomatchscreenshotresolvescreenshotpath) and [`browser.expect.toMatchScreenshot.resolveDiffPath`](#browserexpecttomatchscreenshotresolvediffpath), and used in the default path resolution of `resolveScreenshotPath`.
该值会作为 `screenshotDirectory` 参数传递给 [`browser.expect.toMatchScreenshot.resolveScreenshotPath`](#browserexpecttomatchscreenshotresolvescreenshotpath) [`browser.expect.toMatchScreenshot.resolveDiffPath`](#browserexpecttomatchscreenshotresolvediffpath)`resolveScreenshotPath` 的默认路径解析逻辑也会使用该值。

## browser.expect.toMatchScreenshot.resolveScreenshotPath

Expand Down Expand Up @@ -115,7 +115,7 @@ This value is passed as `screenshotDirectory` to [`browser.expect.toMatchScreens

- `project: TestProject` <Version type="experimental">4.1.6</Version> <Experimental />

The [`TestProject`](/api/advanced/test-project) the test belongs to.
测试所属的 [`TestProject`](/api/advanced/test-project)

例如,以下示例按浏览器分组存储截图:

Expand Down
6 changes: 3 additions & 3 deletions config/browser/webdriverio.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 配置 WebdriverIO {#configuring-webdriverio}
<!-- TODO: translation -->
::: info Community maintained
The WebdriverIO provider ([`@vitest/browser-webdriverio`](https://github.com/vitest-community/vitest-webdriverio)) is maintained by the Vitest community in the [`vitest-community`](https://github.com/vitest-community) organization, separately from the core Vitest packages. Please report provider-specific issues to its repository.

::: info 由社区维护
WebdriverIO provider[`@vitest/browser-webdriverio`](https://github.com/vitest-community/vitest-webdriverio))由 [`vitest-community`](https://github.com/vitest-community) 组织中的 Vitest 社区负责维护,与 Vitest 核心包分开开发。如果遇到该 provider 特有的问题,请提交到对应的仓库。
:::

要使用 WebdriverIO 运行测试,你需要安装 [`@vitest/browser-webdriverio`](https://npmx.dev/package/@vitest/browser-webdriverio) npm 包,并在配置中的 `test.browser.provider` 属性中指定其 `webdriverio` 导出:
Expand Down
18 changes: 9 additions & 9 deletions config/changed.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
title: changed | Config
title: changed | 配置
outline: deep
---
<!-- TODO: translation -->

### changed <CRoot />

- **Type:** `boolean | string`
- **Default:** `false`
- **CLI:** `--changed`, `--changed=HEAD~1`
- **类型:** `boolean | string`
- **默认值:** `false`
- **命令行终端:** `--changed`, `--changed=HEAD~1`

Run tests only against changed files. If no value is provided, it will run tests against uncommitted changes (including staged and unstaged).
仅运行受文件变更影响的测试。未指定值时,Vitest 会根据尚未提交的变更(包括已暂存和未暂存的变更)筛选并运行测试。

To run tests against changes made in the last commit, you can use `--changed HEAD~1`. You can also pass commit hash (e.g. `--changed 09a9920`) or branch name (e.g. `--changed origin/develop`).
要运行受最近一次提交影响的测试,可使用 `--changed HEAD~1`。也可以传入提交哈希(例如 `--changed 09a9920`)或分支名称(例如 `--changed origin/develop`)。

When used with code coverage the report will contain only the files that were related to the changes.
启用代码覆盖率时,报告中只会包含与这些变更相关的文件。

If paired with the [`forceRerunTriggers`](/config/forcereruntriggers) config option it will run the whole test suite if at least one of the files listed in the `forceRerunTriggers` list changes. By default, changes to the Vitest config file and `package.json` will always rerun the whole suite.
[`forceRerunTriggers`](/config/forcereruntriggers) 配置项配合使用时,只要列表中的任一文件发生变更,Vitest 就会运行整个测试套件。默认情况下,只要 Vitest 配置文件或 `package.json` 发生变更,也会重新运行整个测试套件。
Loading
Loading