docs(en): merge docs-cn/sync-docs into docs-cn/dev @ eb948575

.vitepress/config.ts

@@ -152,6 +152,7 @@ export default ({ mode }: { mode: string }) => {
 
           search: {
             provider: 'local',
+<<<<<<< HEAD
             options: {
               translations: {
                 button: {
@@ -168,6 +169,8 @@ export default ({ mode }: { mode: string }) => {
                 },
               },
             },
+=======
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
           },
 
           // banner: {
@@ -731,6 +734,10 @@ export default ({ mode }: { mode: string }) => {
                     text: 'browser.trackUnhandledErrors',
                     link: '/config/browser/trackunhandlederrors',
                   },
+                  {
+                    text: 'browser.importMapMocks',
+                    link: '/config/browser/importmapmocks',
+                  },
                   {
                     text: 'browser.expect',
                     link: '/config/browser/expect',
@@ -1107,6 +1114,10 @@ export default ({ mode }: { mode: string }) => {
                     text: '并行和串行测试文件',
                     link: '/guide/recipes/parallel-sequential',
                   },
+                  {
+                    text: 'Running Only Affected Tests',
+                    link: '/guide/recipes/affected-tests',
+                  },
                 ],
               },
               {

.vitepress/scripts/cli-generator.ts

@@ -9,7 +9,7 @@ const cliTablePath = resolve(docsDir, './guide/cli-generated.md')
 
 const nonNullable = <T>(value: T): value is NonNullable<T> => value !== null && value !== undefined
 
-const skipCli = new Set(['mergeReports', 'shard'])
+const skipCli = new Set(['mergeReports', 'shard', 'sinceLastRun'])
 
 const skipConfig = new Set([
   'config',
@@ -25,6 +25,7 @@ const skipConfig = new Set([
   'coverage.thresholds.functions',
   'coverage.thresholds.lines',
   'standalone',
+  'lastFailed',
   'clearScreen',
   'configLoader',
   'color',

.vitepress/sponsors.ts

@@ -31,22 +31,12 @@ export const sponsors: SponsorTier[] = [
         url: 'https://bolt.new',
         img: '/bolt.svg',
       },
-      {
-        name: 'Latitude',
-        url: 'https://latitude.so/',
-        img: '/latitude.svg',
-      },
     ],
   },
   {
     tier: '金牌赞助商',
     size: 'medium',
     items: [
-      {
-        name: 'vital',
-        url: 'https://vital.io/',
-        img: '/vital.svg',
-      },
       {
         name: 'Mailmeteor',
         url: 'https://mailmeteor.com/',
@@ -62,11 +52,6 @@ export const sponsors: SponsorTier[] = [
         url: 'https://kraken.tech/',
         img: '/kraken.svg',
       },
-      {
-        name: 'Aerius Ventilation',
-        url: 'https://aerius.se/',
-        img: '/aerius.png',
-      },
       {
         name: 'TestMu AI',
         url: 'https://www.testmuai.com/?utm_medium=sponsor&utm_source=vitest-dev',

.vitepress/theme/styles.css

@@ -25,6 +25,17 @@
   --vp-code-color: #007d38;
 }
 
+/* .ansi code blocks color the background of inverse and background-colored text */
+html:not(.dark) .shiki span[style*='--shiki-light-bg'],
+html[data-theme='light'] .shiki span[style*='--shiki-light-bg'] {
+  background-color: var(--shiki-light-bg);
+}
+
+html.dark:not([data-theme]) .shiki span[style*='--shiki-dark-bg'],
+html[data-theme='dark'] .shiki span[style*='--shiki-dark-bg'] {
+  background-color: var(--shiki-dark-bg);
+}
+
 .highlighted-word {
   background-color: var(--vp-code-line-highlight-color);
   transition: background-color 0.5s;

api/advanced/runner.md

@@ -271,6 +271,37 @@ export interface TaskResult {
    * The zero-based index of the current repeat.
    */
   repeatCount?: number
+  /**
+   * Individual results for every retry and repeat attempt.
+   */
+  attempts?: TaskResultAttempt[]
+}
+
+export interface TaskResultAttempt {
+  /**
+   * The state after applying the test's expected failure option.
+   */
+  state: 'pass' | 'fail' | 'skip'
+  /**
+   * Errors produced by this attempt.
+   */
+  errors?: TestError[]
+  /**
+   * How long in milliseconds the attempt took to run.
+   */
+  duration: number
+  /**
+   * Time in milliseconds when the attempt started running.
+   */
+  startTime: number
+  /**
+   * The zero-based retry index within the repeat.
+   */
+  retryIndex: number
+  /**
+   * The zero-based repeat index.
+   */
+  repeatIndex: number
 }
 ```
 

api/advanced/test-case.md

@@ -228,7 +228,11 @@ interface TestResultPassed {
 ```
 
 ::: warning
+<<<<<<< HEAD
 请注意，状态为 `passed` 的测试仍可能附带有错误——如果 `retry` 至少触发了一次，这种情况就可能发生。
+=======
+Note that the test with `passed` state can still have errors attached - this can happen if `retry` was triggered at least once. Use [`attempts()`](#attempts) to see which run produced each error.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 :::
 
 ## diagnostic
@@ -278,6 +282,58 @@ interface TestDiagnostic {
 如果测试尚未被安排运行，`diagnostic()` 将返回 `undefined`。
 :::
 
+## attempts <Version>5.1.0</Version> {#attempts}
+
+```ts
+function attempts(): ReadonlyArray<TestAttempt>
+```
+
+Results of every run of the test, in execution order. A test runs more than once when [`retry`](/config/retry) or [`repeats`](/api/test#repeats) is configured, and each run produces one entry. Unlike `result()`, which only reports the final outcome and merges errors from all runs, each attempt keeps its own state, errors and timing.
+
+```ts
+interface TestAttempt {
+  /**
+   * The state of this attempt. `fails` tests are already inverted,
+   * so an expected failure is reported as `passed`.
+   */
+  readonly state: 'passed' | 'failed' | 'skipped'
+  /**
+   * Errors thrown during this attempt only.
+   */
+  readonly errors: ReadonlyArray<TestError> | undefined
+  /**
+   * How long in milliseconds the attempt took to run.
+   */
+  readonly duration: number
+  /**
+   * Time in milliseconds when the attempt started.
+   */
+  readonly startTime: number
+  /**
+   * The zero-based retry index within the current repeat.
+   */
+  readonly retryIndex: number
+  /**
+   * The zero-based repeat index.
+   */
+  readonly repeatIndex: number
+}
+```
+
+For example, a test with `retry: 2` that passes on its third run returns:
+
+```ts
+[
+  { state: 'failed', retryIndex: 0, repeatIndex: 0, errors: [/* ... */] },
+  { state: 'failed', retryIndex: 1, repeatIndex: 0, errors: [/* ... */] },
+  { state: 'passed', retryIndex: 2, repeatIndex: 0, errors: undefined },
+]
+```
+
+::: info
+`attempts()` returns an empty array if the test has not run yet.
+:::
+
 ## annotations
 
 ```ts

api/advanced/test-module.md

@@ -48,7 +48,11 @@ if (task.type === 'module') {
 function state(): TestModuleState
 ```
 
+<<<<<<< HEAD
 与 [`testSuite.state()`](/api/advanced/test-suite#state) 的工作方式相同，但如果模块尚未执行，还可以返回 `queued`。
+=======
+Works the same way as [`testSuite.state()`](/api/advanced/test-suite#state), but can also return `queued` if the module is queued, but Vitest did not collect its tests yet.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ## meta <Version>3.1.0</Version> {#meta}
 

api/advanced/test-specification.md

@@ -38,7 +38,13 @@ Vite 模块图中的模块 ID。通常，它是一个使用 POSIX 分隔符的
 
 ## testModule
 
+<<<<<<< HEAD
 与规范相关联的 [`TestModule`](/api/advanced/test-module) 实例。如果测试还未加入队列，则将是 `undefined`。
+=======
+Instance of [`TestModule`](/api/advanced/test-module) associated with the specification. This is `undefined` until Vitest queues the module or parses it, for example, with [`experimental.preParse`](/config/experimental#experimental-preparse) or [`parseSpecifications`](/api/advanced/vitest#parsespecifications).
+
+Vitest keeps the module after the test run finishes. If the specification runs again, this returns the module of the previous run until the module is queued again.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ## pool
 
@@ -86,6 +92,10 @@ describe('a group of tests', () => { // [!code error]
 
 当前 TestSpecification 中需要运行的任务 ID 集合。
 
+## testNames <Version>5.1.0</Version> {#testnames}
+
+The full names of the tests inside of this specification to run, including the parent suites separated with `>`.
+
 ## testTagsFilter <Version>4.1.0</Version> {#testtagsfilter}
 
 测试必须通过的 [标签过滤器](/guide/test-tags#syntax) 才能被纳入运行范围。多个过滤器将按 `AND` 逻辑处理。

api/advanced/test-suite.md

@@ -171,7 +171,11 @@ function state(): TestSuiteState
 - **skipped**：此套件在收集过程中被跳过。
 
 ::: warning
+<<<<<<< HEAD
 请注意，[测试模块](/api/advanced/test-module) 也有一个 `state` 方法，返回相同的值，但如果模块尚未执行，它还可以返回一个额外的 `queued` 状态。
+=======
+Note that [test module](/api/advanced/test-module) also has a `state` method that returns the same values, but it can also return an additional `queued` state if the module is queued, but Vitest did not collect its tests yet.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 :::
 
 ## errors

api/advanced/vitest.md

@@ -44,9 +44,13 @@ const testCase = vitest.state.getReportedEntity(task) // 新 API
 
 ## cache
 
+<<<<<<< HEAD
 <!-- TODO: translation -->
 
 Cache manager that stores the results of the previous test runs. In Vitest itself this is only used by the default sequencer to sort tests.
+=======
+Cache manager that stores the results of the previous test runs. Vitest uses it to sort tests in the default sequencer and to select tests with [`--last-failed`](/guide/cli#last-failed).
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ### cache.getTestSpecificationResult <Version type="experimental">5.0.4</Version> {#cache-gettestspecificationresult}
 
@@ -60,7 +64,7 @@ function getTestSpecificationResult(
 interface CachedTestFileResult {
   /**
    * The file has a known failure.
-   * Only a complete run of the file clears it.
+   * A complete run of the file clears it, or a run in which every known failed test passes.
    */
   failed: boolean
   /**
@@ -72,6 +76,12 @@ interface CachedTestFileResult {
    * It is not set if the file never ran completely.
    */
   lastRun?: number
+  /**
+   * Full names of the tests that failed in the last run of the file.
+   * `--last-failed` runs only these tests.
+   * It is not set if the failure happened outside of tests, for example in a hook or during collection.
+   */
+  failedTests?: string[]
 }
 ```
 
@@ -231,7 +241,11 @@ function collect(
 
 根据 `staticParse` 的设置，此方法要么通过静态分析收集测试文件（默认行为），要么运行代码但不执行测试回调。`collect` 返回未处理的错误以及一个 [测试模块](/api/advanced/test-module) 数组。它接受用于匹配测试文件的字符串过滤器——这些过滤器与 [CLI 支持的过滤器](/guide/filtering#cli) 相同。
 
+<<<<<<< HEAD
 此方法根据配置的 `include`、`exclude` 和 `includeSource` 值解析 TestSpecification。有关更多信息，请参阅 [`project.globTestFiles`](/api/advanced/test-project#globtestfiles)。如果指定了 `--changed` 参数，则列表将被过滤为仅包含已更改的文件。
+=======
+This method resolves tests specifications based on the config `include`, `exclude`, and `includeSource` values. Read more at [`project.globTestFiles`](/api/advanced/test-project#globtestfiles). If `--changed` flag was specified, the list will be filtered to include only files that changed. If [`--shard`](/guide/cli#shard) was specified, only the files of the current shard are collected.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ::: warning
 注意，自 Vitest 5 起，默认通过静态分析收集测试。如果通过第二个参数禁用了此功能，Vitest 将像运行常规测试一样，以隔离方式运行每个测试文件。除非在收集测试前手动禁用隔离，否则这会使该方法变得非常慢。
@@ -300,7 +314,11 @@ function runTestSpecifications(
 ): Promise<TestRunResult>
 ```
 
+<<<<<<< HEAD
 该方法会遍历并执行所有根据 [测试规格](/api/advanced/test-specification) 定义的测试用例。第二个参数 `allTestsRun` 则供覆盖率工具判断是否应在覆盖率报告中加入那些没有被任何测试覆盖到的文件。
+=======
+This method runs every test based on the received [specifications](/api/advanced/test-specification). It does not apply the [`--shard`](/guide/cli#shard) option. The second argument, `allTestsRun`, is used by the coverage provider to determine if it needs to include uncovered files in report.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ::: warning
 此方法不会触发 `onWatcherRerun`、`onWatcherStart` 和 `onTestsRerun` 回调。如果我们基于文件更改重新运行测试，请考虑使用 [`rerunTestSpecifications`](#reruntestspecifications) 代替。
@@ -350,7 +368,11 @@ function collectTests(
 
 执行测试文件而不运行测试回调。`collectTests` 返回未处理的错误和 [测试模块](/api/advanced/test-module) 数组。
 
+<<<<<<< HEAD
 此方法与 [`collect`](#collect) 完全相同，但我们需要自己提供 TestSpecification。
+=======
+This method works exactly the same as [`collect`](#collect), but you need to provide test specifications yourself. It does not apply the [`--shard`](/guide/cli#shard) option.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ::: warning
 请注意，Vitest 不使用静态分析来收集测试。Vitest 将像运行常规测试一样在隔离环境中运行每个测试文件。
@@ -602,7 +624,11 @@ function experimental_parseSpecification(
 ): Promise<TestModule>
 ```
 
+<<<<<<< HEAD
 该函数会收集文件内的所有测试，但不会执行它们。它借助 Vite 的 `ssrTransform`，并在其之上使用 rollup 的 `parseAst` 进行静态分析，从而提取所有可识别的测试用例。
+=======
+This function will collect all tests inside the file without running it. It uses rollup's `parseAst` function on top of Vite's `ssrTransform` to statically analyse the file and collect all tests that it can. A call is collected only if its first argument is a string, a template string, a number, a variable, a property like `MyClass.name`, or a condition (`a ? b : c`, `a ?? b`, `a || b`) of those, so `test(getName(), fn)` is not collected. A name that is not a literal, such as `test(isWindows ? 'a' : 'b', fn)`, is collected with its source code as the name. The test keeps its location, but a test name pattern cannot match it.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 ::: warning
 如果 Vitest 无法解析测试的名称，它将在测试或套件中注入一个 `dynamic: true` 属性。`id` 也会带有 `-dynamic` 后缀，以避免破坏已正确收集的测试。

api/browser/assertions.md

@@ -55,7 +55,11 @@ interface ExpectPollOptions {
 ```
 
 ::: tip
+<<<<<<< HEAD
 与 [expect.poll](/api/expect#poll) 类似，`expect.element` 会反复重试 DOM 断言，直到断言通过或达到超时时间。当接收到定位器时，Vitest 会先通过 [locator.findElement()](/api/browser/locators#findelement) 解析该定位器，再执行 DOM 断言。`timeout` 参数适用于整个重试过程。`interval` 参数控制失败 DOM 断言的重试频率，但定位器解析使用 `findElement` 自身递增的重试间隔。
+=======
+Like [`expect.poll`](/api/expect#poll), `expect.element` retries DOM assertions until they pass or the timeout is reached. When it receives a locator, Vitest resolves it with [`locator.findElement()`](/api/browser/locators#findelement) before running the DOM assertion. The `timeout` option applies to the whole retry operation. The `interval` option controls how often failed DOM assertions are retried, but locator resolution uses `findElement`'s own increasing retry intervals. If [fake timers](/api/vi#vi-usefaketimers) are enabled, `expect.element` advances them while it retries. See [Automatic Advancing](/guide/mocking/timers#automatic-advancing) for details.
+>>>>>>> eb948575f5ffa8346112d64ab6f6522ee538b4e9
 
 `toMatchTextContent` 以及其他所有断言在常规的 `expect` 中仍然可用，但没有内置的重试机制：