docs(en): merging all conflicts

Author: docschina-bot

.vitepress/config.ts

@@ -103,6 +103,7 @@ export default ({ mode }: { mode: string }) => {
               },
             }),
           ],
+      languages: ['js', 'jsx', 'ts', 'tsx'],
     },
     themeConfig: {
       logo: '/logo.svg',
@@ -342,7 +343,15 @@ export default ({ mode }: { mode: string }) => {
                 ],
               },
               {
+<<<<<<< HEAD
                 text: '运行器「Runner」 API',
+=======
+                text: 'Plugin API',
+                link: '/advanced/api/plugin',
+              },
+              {
+                text: 'Runner API',
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
                 link: '/advanced/runner',
               },
               {

advanced/api/plugin.md

@@ -0,0 +1,125 @@
+---
+title: Plugin API
+outline: deep
+---
+
+# Plugin API <Version>3.1.0</Version> {#plugin-api}
+
+::: warning
+This is an advanced API. If you just want to [run tests](/guide/), you probably don't need this. It is primarily used by library authors.
+
+This guide assumes you know how to work with [Vite plugins](https://vite.dev/guide/api-plugin.html).
+:::
+
+Vitest supports an experimental `configureVitest` [plugin](https://vite.dev/guide/api-plugin.html) hook hook since version 3.1. Any feedback regarding this API is welcome in [GitHub](https://github.com/vitest-dev/vitest/discussions/7104).
+
+::: code-group
+```ts [only vitest]
+import type { Vite, VitestPluginContext } from 'vitest/node'
+
+export function plugin(): Vite.Plugin {
+  return {
+    name: 'vitest:my-plugin',
+    configureVitest(context: VitestPluginContext) {
+      // ...
+    }
+  }
+}
+```
+```ts [vite and vitest]
+/// <reference types="vitest/config" />
+
+import type { Plugin } from 'vite'
+
+export function plugin(): Plugin {
+  return {
+    name: 'vitest:my-plugin',
+    transform() {
+      // ...
+    },
+    configureVitest(context) {
+      // ...
+    }
+  }
+}
+```
+:::
+
+::: tip TypeScript
+Vitest re-exports all Vite type-only imports via a `Vite` namespace, which you can use to keep your versions in sync. However, if you are writing a plugin for both Vite and Vitest, you can continue using the `Plugin` type from the `vite` entrypoint. Just make sure you have `vitest/config` referenced somewhere so that `configureVitest` is augmented correctly:
+
+```ts
+/// <reference types="vitest/config" />
+```
+:::
+
+Unlike [`reporter.onInit`](/advanced/api/reporters#oninit), this hooks runs early in Vitest lifecycle allowing you to make changes to configuration like `coverage` and `reporters`. A more notable change is that you can manipulate the global config from a [workspace project](/guide/workspace) if your plugin is defined in the project and not in the global config.
+
+## Context
+
+### project
+
+The current [test project](./test-project) that the plugin belongs to.
+
+::: warning Browser Mode
+Note that if you are relying on a browser feature, the `project.browser` field is not set yet. Use [`reporter.onBrowserInit`](./reporters#onbrowserinit) event instead.
+:::
+
+### vitest
+
+The global [Vitest](./vitest) instance. You can change the global configuration by directly mutating the `vitest.config` property:
+
+```ts
+vitest.config.coverage.enabled = false
+vitest.config.reporters.push([['my-reporter', {}]])
+```
+
+::: warning Config is Resolved
+Note that Vitest already resolved the config, so some types might be different from the usual user configuration. This also means that some properties will not be resolved again, like `setupFile`. If you are adding new files, make sure to resolve it first.
+
+At this point reporters are not created yet, so modifying `vitest.reporters` will have no effect because it will be overwritten. If you need to inject your own reporter, modify the config instead.
+:::
+
+### injectTestProjects
+
+```ts
+function injectTestProjects(
+  config: TestProjectConfiguration | TestProjectConfiguration[]
+): Promise<TestProject[]>
+```
+
+This methods accepts a config glob pattern, a filepath to the config or an inline configuration. It returns an array of resolved [test projects](./test-project).
+
+```ts
+// inject a single project with a custom alias
+const newProjects = await injectTestProjects({
+  // you can inherit the current project config by referencing `configFile`
+  // note that you cannot have a project with the name that already exists,
+  // so it's a good practice to define a custom name
+  configFile: project.vite.config.configFile,
+  test: {
+    name: 'my-custom-alias',
+    alias: {
+      customAlias: resolve('./custom-path.js'),
+    },
+  },
+})
+```
+
+::: warning Projects are Filtered
+Vitest filters projects during the config resolution, so if the user defined a filter, injected project might not be resolved unless it [matches the filter](./vitest#matchesprojectfilter). You can update the filter via the `vitest.config.project` option to always include your workspace project:
+
+```ts
+vitest.config.project.push('my-project-name')
+```
+
+Note that this will only affect projects injected with [`injectTestProjects`](#injecttestprojects) method.
+:::
+
+::: tip Referencing the Current Config
+If you want to keep the user configuration, you can specify the `configFile` property. All other properties will be merged with the user defined config.
+
+The project's `configFile` can be accessed in Vite's config: `project.vite.config.configFile`.
+
+Note that this will also inherit the `name` - Vitest doesn't allow multiple projects with the same name, so this will throw an error. Make sure you specified a different name. You can access the current name via the `project.name` property and all used names are available in the `vitest.projects` array.
+:::

advanced/api/reporters.md

@@ -52,7 +52,11 @@ function onInit(vitest: Vitest): Awaitable<void>
 当 [Vitest](/advanced/api/vitest) 初始化或启动时，但在测试被过滤之前，会调用此方法。
 
 ::: info
+<<<<<<< HEAD
 在内部，此方法在 [`vitest.start`](/advanced/api/vitest#start)、[`vitest.init`](/advanced/api/vitest#init) 或 [`vitest.mergeReports`](/advanced/api/vitest#mergereports) 中调用。如果我们使用的是编程式 API，请确保根据需要在调用 [`vitest.runTestSpecifications`](/advanced/api/vitest#runtestspecifications) 之前调用其中之一。内置的 CLI 将始终按正确顺序运行方法。
+=======
+Internally this method is called inside [`vitest.start`](/advanced/api/vitest#start), [`vitest.init`](/advanced/api/vitest#init) or [`vitest.mergeReports`](/advanced/api/vitest#mergereports). If you are using programmatic API, make sure to call either one depending on your needs before calling [`vitest.runTestSpecifications`](/advanced/api/vitest#runtestspecifications), for example. Built-in CLI will always run methods in correct order.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 :::
 
 请注意，我们还可以通过 [`project`](/advanced/api/test-project) 属性从测试用例、套件和测试模块中访问 `vitest` 实例，但在此方法中存储对 `vitest` 的引用也可能有用。
@@ -137,9 +141,15 @@ function onTestRunEnd(
 
 第三个参数指示测试运行结束的原因：
 
+<<<<<<< HEAD
 - `passed`：测试运行正常结束，没有错误
 - `failed`：测试运行至少有一个错误（由于收集期间的语法错误或测试执行期间的实际错误）
 - `interrupted`：测试被 [`vitest.cancelCurrentRun`](/advanced/api/vitest#cancelcurrentrun) 调用中断，或者在终端中按下了 `Ctrl+C`（请注意，在这种情况下仍可能有失败的测试）
+=======
+- `passed`: test run was finished normally and there are no errors
+- `failed`: test run has at least one error (due to a syntax error during collection or an actual error during test execution)
+- `interrupted`: test was interrupted by [`vitest.cancelCurrentRun`](/advanced/api/vitest#cancelcurrentrun) call or `Ctrl+C` was pressed in the terminal (note that it's still possible to have failed tests in this case)
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 如果 Vitest 没有找到任何要运行的测试文件，此事件将以空的模块和错误数组调用，状态将取决于 [`config.passWithNoTests`](/config/#passwithnotests) 的值。
 

advanced/api/test-project.md

@@ -124,7 +124,11 @@ const value = inject('key')
 ```
 :::
 
+<<<<<<< HEAD
 这些值可以动态提供。测试中提供的值将在下次运行时更新。
+=======
+The values can be provided dynamically. Provided value in tests will be updated on their next run.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ::: tip
 此方法也可用于 [全局设置文件](/config/#globalsetup)，以便在无法使用公共 API 的情况下使用：

advanced/api/test-specification.md

@@ -33,7 +33,7 @@ Vite 模块图中的模块 ID。通常，它是一个使用 POSIX 分隔符的
 
 ## testModule
 
-Instance of [`TestModule`](/advanced/api/test-module) assosiated with the specification. If test wasn't queued yet, this will be `undefined`.
+Instance of [`TestModule`](/advanced/api/test-module) associated with the specification. If test wasn't queued yet, this will be `undefined`.
 
 ## pool <Badge type="warning">experimental</Badge> {#pool}
 

advanced/api/vitest.md

@@ -93,7 +93,11 @@ const testCase = vitest.state.getReportedEntity(task) // 新 API
 
 全局快照管理器。Vitest 使用 `snapshot.add` 方法跟踪所有快照。
 
+<<<<<<< HEAD
 我们可以通过 `vitest.snapshot.summay` 属性获取快照的最新摘要。
+=======
+You can get the latest summary of snapshots via the `vitest.snapshot.summary` property.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ## cache
 
@@ -130,7 +134,11 @@ function provide<T extends keyof ProvidedContext & string>(
 
 Vitest 公开了 `provide` 方法，它是 `vitest.getRootProject().provide` 的简写。通过此方法，我们可以从主线程传递值到测试中。所有值在存储之前都通过 `structuredClone` 进行检查，但值本身不会被克隆。
 
+<<<<<<< HEAD
 要在测试中接收这些值，我们需要从 `vitest` 入口点导入 `inject` 方法：
+=======
+To receive the values in the test, you need to import `inject` method from `vitest` entrypoint:
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ```ts
 import { inject } from 'vitest'
@@ -155,7 +163,11 @@ declare module 'vitest' {
 ```
 
 ::: warning
+<<<<<<< HEAD
 从技术上讲，`provide` 是 [`TestProject`](/advanced/api/test-project) 的方法，因此它仅限于特定项目。然而，所有项目都继承自核心项目的值，这使得 `vitest.provide` 成为传递值到测试的通用方式。
+=======
+Technically, `provide` is a method of [`TestProject`](/advanced/api/test-project), so it is limited to the specific project. However, all projects inherit the values from the root project which makes `vitest.provide` universal way of passing down values to tests.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 :::
 
 ## getProvidedContext
@@ -172,7 +184,11 @@ function getProvidedContext(): ProvidedContext
 function getProjectByName(name: string): TestProject
 ```
 
+<<<<<<< HEAD
 此方法通过名称返回项目。类似于调用 `vitest.projects.find`。
+=======
+This method returns the project by its name. Similar to calling `vitest.projects.find`.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ::: warning
 如果项目不存在，此方法将返回根项目 - 请确保再次检查返回的项目是否是我们要找的项目。
@@ -297,7 +313,11 @@ function getModuleSpecifications(moduleId: string): TestSpecification[]
 function clearSpecificationsCache(moduleId?: string): void
 ```
 
+<<<<<<< HEAD
 当调用 [`globTestSpecifications`](#globtestspecifications) 或 [`runTestSpecifications`](#runtestspecifications) 时，Vitest 会自动缓存每个文件的测试规范。此方法清除给定文件的缓存或整个缓存，具体取决于第一个参数。
+=======
+Vitest automatically caches test specifications for each file when [`globTestSpecifications`](#globtestspecifications) or [`runTestSpecifications`](#runtestspecifications) is called. This method clears the cache for the given file or the whole cache altogether depending on the first argument.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ## runTestSpecifications
 
@@ -452,7 +472,11 @@ function exit(force = false): Promise<void>
 
 关闭所有项目并退出进程。如果 `force` 设置为 `true`，则进程将在关闭项目后立即退出。
 
+<<<<<<< HEAD
 如果进程在 [`config.teardownTimeout`](/config/#teardowntimeout) 毫秒后仍然处于活动状态，此方法还将强制调用 `process.exit()`。
+=======
+This method will also forcefully call `process.exit()` if the process is still active after [`config.teardownTimeout`](/config/#teardowntimeout) milliseconds.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ## shouldKeepServer
 
@@ -517,4 +541,18 @@ vitest.onFilterWatchedSpecification(specification =>
 )
 ```
 
+<<<<<<< HEAD
 Vitest 可以根据 `pool` 或 `locations` 选项为同一文件创建不同的规范，因此不要依赖引用。Vitest 还可以从 [`vitest.getModuleSpecifications`](#getmodulespecifications) 返回缓存的规范 - 缓存基于 `moduleId` 和 `pool`。请注意，[`project.createSpecification`](/advanced/api/test-project#createspecification) 总是返回一个新实例。
+=======
+Vitest can create different specifications for the same file depending on the `pool` or `locations` options, so do not rely on the reference. Vitest can also return cached specification from [`vitest.getModuleSpecifications`](#getmodulespecifications) - the cache is based on the `moduleId` and `pool`. Note that [`project.createSpecification`](/advanced/api/test-project#createspecification) always returns a new instance.
+
+## matchesProjectFilter <Version>3.1.0</Version> {#matchesprojectfilter}
+
+```ts
+function matchesProjectFilter(name: string): boolean
+```
+
+Check if the name matches the current [project filter](/guide/cli#project). If there is no project filter, this will always return `true`.
+
+It is not possible to programmatically change the `--project` CLI option.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69

advanced/guide/tests.md

@@ -71,7 +71,11 @@ finally {
 }
 ```
 
+<<<<<<< HEAD
 如果你打算保留 `Vitest` 实例，请确保至少调用 [`init`](/advanced/api/vitest#init)。这将初始化报告器和覆盖率提供者，但不会运行任何测试。即使你不打算使用 Vitest 监视器，但希望保持实例运行，也建议启用 `watch` 模式。Vitest 依赖于这个标志，以确保某些功能在持续过程中正常工作。
+=======
+If you intend to keep the `Vitest` instance, make sure to at least call [`init`](/advanced/api/vitest#init). This will initialise reporters and the coverage provider, but won't run any tests. It is also recommended to enable the `watch` mode even if you don't intend to use the Vitest watcher, but want to keep the instance running. Vitest relies on this flag for some of its features to work correctly in a continuous process.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 报告器初始化后，如果需要手动运行测试，可以使用 [`runTestSpecifications`](/advanced/api/vitest#runtestspecifications) 或 [`rerunTestSpecifications`](/advanced/api/vitest#reruntestspecifications) 来运行测试。
 
@@ -88,7 +92,11 @@ watcher.on('change', async (file) => {
 ```
 
 ::: warning
+<<<<<<< HEAD
 上述示例展示了如果你禁用默认监视器行为的一个潜在用例。默认情况下，Vitest 在文件发生变化时已经会重新运行测试。
+=======
+The example above shows a potential use-case if you disable the default watcher behaviour. By default, Vitest already reruns tests if files change.
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 另外请注意，`getModuleSpecifications` 不会解析测试文件，除非这些文件已经通过 `globTestSpecifications` 处理过。如果文件刚刚创建，应使用 `project.matchesGlobPattern`：
 

api/index.md

@@ -134,6 +134,18 @@ test('skipped test', (context) => {
 })
 ```
 
+Since Vitest 3.1, if the condition is unknonwn, you can provide it to the `skip` method as the first arguments:
+
+```ts
+import { assert, test } from 'vitest'
+
+test('skipped test', (context) => {
+  context.skip(Math.random() < 0.5, 'optional message')
+  // Test skipped, no error
+  assert.equal(Math.sqrt(4), 3)
+})
+```
+
 ### test.skipIf
 
 - **类型:** `(condition: any) => Test`
@@ -344,7 +356,8 @@ test.fails('fail test', async () => {
 - `%f`: floating point value
 - `%j`: json
 - `%o`: object
-- `%#`: index of the test case
+- `%#`: 0-based index of the test case
+- `%$`: 1-based index of the test case
 - `%%`: single percent sign ('%')
 
 ```ts
@@ -364,7 +377,11 @@ test.each([
 // ✓ add(2, 1) -> 3
 ```
 
+<<<<<<< HEAD
 如果使用对象作为参数，也可以使用前缀 `$` 访问对象属性：
+=======
+You can also access object properties and array elements with `$` prefix:
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 ```ts
 test.each([
@@ -374,6 +391,22 @@ test.each([
 ])('add($a, $b) -> $expected', ({ a, b, expected }) => {
   expect(a + b).toBe(expected)
 })
+<<<<<<< HEAD
+=======
+
+// this will return
+// ✓ add(1, 1) -> 2
+// ✓ add(1, 2) -> 3
+// ✓ add(2, 1) -> 3
+
+test.each([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+])('add($0, $1) -> $2', (a, b, expected) => {
+  expect(a + b).toBe(expected)
+})
+>>>>>>> 8c114323d7389495d09c1f8e137101ca70841c69
 
 // 这将返回
 // ✓ add(1, 1) -> 2