From 4fa791b02754acb292019db553fe3f075b1c2ce3 Mon Sep 17 00:00:00 2001 From: koutaro-masaki <74706880+koutaro-masaki@users.noreply.github.com> Date: Sun, 7 Jun 2026 17:53:28 +0900 Subject: [PATCH 1/5] docs: document the assertion function limitation in in-source testing (#10527) --- api/assert.md | 28 ++++++++++++++++++++++++++++ guide/in-source.md | 4 ++++ 2 files changed, 32 insertions(+) diff --git a/api/assert.md b/api/assert.md index a10d06634..ee3a14c10 100644 --- a/api/assert.md +++ b/api/assert.md @@ -2,6 +2,34 @@ Vitest reexports the `assert` method from [`chai`](https://www.chaijs.com/api/assert/) for verifying invariants. +::: warning In-Source Testing {#in-source-testing} +When using [assertion functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions) such as `assert` from `import.meta.vitest` in [in-source tests](/guide/in-source), TypeScript reports error `TS2775` because they must be called via an explicitly annotated name. Annotate the variable with `Chai.Assert` or call it directly: + +::: code-group +```ts [Annotated variable] +if (import.meta.vitest) { + const { test, assert } = import.meta.vitest // [!code --] + const { test } = import.meta.vitest // [!code ++] + const assert: Chai.Assert = import.meta.vitest.assert // [!code ++] + + test('assert', () => { + assert('foo' !== 'bar', 'foo should not be equal to bar') + }) +} +``` +```ts [Direct call] +if (import.meta.vitest) { + const { test, assert } = import.meta.vitest // [!code --] + const { test } = import.meta.vitest // [!code ++] + + test('assert', () => { + assert('foo' !== 'bar', 'foo should not be equal to bar') // [!code --] + import.meta.vitest!.assert('foo' !== 'bar', 'foo should not be equal to bar') // [!code ++] + }) +} +``` +::: + ## assert - **Type:** `(expression: any, message?: string) => asserts expression` diff --git a/guide/in-source.md b/guide/in-source.md index f22b1843e..05e6f8864 100644 --- a/guide/in-source.md +++ b/guide/in-source.md @@ -152,6 +152,10 @@ To get TypeScript support for `import.meta.vitest`, add `vitest/importMeta` to y Reference to [`examples/in-source-test`](https://github.com/vitest-dev/vitest/tree/main/examples/in-source-test) for the full example. +::: warning +There is a limitation when using [assertion functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions) such as `assert` in in-source tests. See [`assert`](/api/assert#in-source-testing) for details and workarounds. +::: + ## Notes This feature could be useful for: From 2faf0d3031b3c8fea4349f2fb70e9199a71e8a72 Mon Sep 17 00:00:00 2001 From: Todor Andonov <45210624+todor-a@users.noreply.github.com> Date: Sun, 7 Jun 2026 17:53:14 +0300 Subject: [PATCH 2/5] feat(cli): add `--repeats` CLI option (#10504) --- .vitepress/config.ts | 4 ++++ config/repeats.md | 14 ++++++++++++++ guide/cli-generated.md | 7 +++++++ 3 files changed, 25 insertions(+) create mode 100644 config/repeats.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 6a57443d8..c42839e96 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -507,6 +507,10 @@ export default ({ mode }: { mode: string }) => { text: 'retry', link: '/config/retry', }, + { + text: 'repeats', + link: '/config/repeats', + }, { text: 'onConsoleLog', link: '/config/onconsolelog', diff --git a/config/repeats.md b/config/repeats.md new file mode 100644 index 000000000..733644c5f --- /dev/null +++ b/config/repeats.md @@ -0,0 +1,14 @@ +--- +title: repeats | Config +outline: deep +--- + +# repeats + +- **Type:** `number` +- **Default:** `0` +- **CLI:** `--repeats=` + +Repeat every test a specific number of times regardless of the result. A test that uses the [`repeats`](/api/test#repeats) test option takes precedence over this value. + +This is useful for verifying that tests are stable across multiple runs. If a test fails on any repetition, the whole test is reported as failed. diff --git a/guide/cli-generated.md b/guide/cli-generated.md index 7538e4f2e..9fe528713 100644 --- a/guide/cli-generated.md +++ b/guide/cli-generated.md @@ -637,6 +637,13 @@ Delay in milliseconds between retry attempts (default: `0`) Regex pattern to match error messages that should trigger a retry. Only errors matching this pattern will cause a retry (default: retry on all errors) +### repeats + +- **CLI:** `--repeats ` +- **Config:** [repeats](/config/repeats) + +Repeat every test a specific number of times regardless of the result (default: `0`) + ### diff.aAnnotation - **CLI:** `--diff.aAnnotation ` From 835ab3b00cf1e1787780c2a312451a096bb422c9 Mon Sep 17 00:00:00 2001 From: Hiroshi Ogawa Date: Mon, 8 Jun 2026 14:24:35 +0900 Subject: [PATCH 3/5] fix(browser)!: require `sessionId` for orchestrator html request (#10522) Co-authored-by: Hiroshi Ogawa <4232207+hi-ogawa@users.noreply.github.com> Co-authored-by: Codex --- guide/browser/index.md | 2 -- guide/migration.md | 6 ++++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/guide/browser/index.md b/guide/browser/index.md index 7f7fee18d..a1073ad46 100644 --- a/guide/browser/index.md +++ b/guide/browser/index.md @@ -119,8 +119,6 @@ export default defineConfig({ ::: info Vitest assigns port `63315` to avoid conflicts with the development server, allowing you to run both in parallel. You can change that with the [`browser.api`](/config/browser/api) option. - -The CLI does not print the Vite server URL automatically. You can press "b" to print the URL when running in watch mode. ::: If you have not used Vite before, make sure you have your framework's plugin installed and specified in the config. Some frameworks might require extra configuration to work - check their Vite related documentation to be sure. diff --git a/guide/migration.md b/guide/migration.md index ea3892bcb..b428acc22 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -138,6 +138,12 @@ $ cd subdir && vitest --config ../vitest.config.ts # [!code ++] Assignments to properties on `globalThis` or `window` in `jsdom` and `happy-dom` environments are now propagated to the underlying DOM implementation. Mutable properties such as `innerWidth` can affect APIs implemented by the DOM environment, for example `happy-dom`'s `matchMedia`. +### Browser Orchestrator URL Requires a Session + +Vitest no longer serves the browser orchestrator UI from a bare `/__vitest_test__/` URL. Browser runner URLs are now session-bound and must include the `sessionId` generated by Vitest, for example `/__vitest_test__/?sessionId=...`. + +If you manually opened the browser preview by copying the Vite server URL or visiting `/__vitest_test__/` directly, use the URL opened or printed by Vitest instead. + ## Migrating to Vitest 4.0 {#vitest-4} ::: warning Prerequisites From 8430ac3c5895ab2beaa27433b4386989c69fc6ee Mon Sep 17 00:00:00 2001 From: "Bonaventure C. J. Ugwu" <73999585+BonaventureCJ@users.noreply.github.com> Date: Mon, 8 Jun 2026 06:54:47 +0100 Subject: [PATCH 4/5] docs(guide): clarify beforeEach state isolation (#10512) --- guide/learn/setup-teardown.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/guide/learn/setup-teardown.md b/guide/learn/setup-teardown.md index 2eacac656..2985ec4a5 100644 --- a/guide/learn/setup-teardown.md +++ b/guide/learn/setup-teardown.md @@ -33,15 +33,20 @@ test('items starts with 3 fruits', () => { expect(items).toHaveLength(3) }) +test('can remove an item', () => { + items.pop() + expect(items).toHaveLength(2) +}) + test('can add an item', () => { items.push('date') expect(items).toHaveLength(4) - // afterEach will reset items for the next test, - // so this mutation won't leak into other tests + // beforeEach reset the array to 3 items before this test ran, + // proving that mutations from the previous test do not leak. }) ``` -Without these hooks, the second test's `push` would affect any test that runs after it, which is a classic source of flaky tests. The hooks guarantee clean state for every test. +Without these hooks, mutations like `pop` or `push` from earlier tests would affect subsequent ones, which is a classic source of flaky tests, while the hooks guarantee clean state for every test. ## One-Time Setup From 156799236972a7d668c54f05f0a8b2897dca0f56 Mon Sep 17 00:00:00 2001 From: noise Date: Tue, 9 Jun 2026 23:02:38 +0800 Subject: [PATCH 5/5] docs(cn): dissolve the conflict --- api/assert.md | 2 +- config/repeats.md | 2 +- guide/browser/index.md | 6 ------ guide/cli-generated.md | 2 +- guide/in-source.md | 8 ++------ guide/learn/setup-teardown.md | 11 +---------- guide/migration.md | 6 +----- 7 files changed, 7 insertions(+), 30 deletions(-) diff --git a/api/assert.md b/api/assert.md index b8380d4ad..5dad88bd7 100644 --- a/api/assert.md +++ b/api/assert.md @@ -1,7 +1,7 @@ # assert Vitest 从 [`chai`](https://www.chaijs.com/api/assert/) 重新导出了 `assert` 方法，用于验证不变量。 - + ::: warning In-Source Testing {#in-source-testing} When using [assertion functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions) such as `assert` from `import.meta.vitest` in [in-source tests](/guide/in-source), TypeScript reports error `TS2775` because they must be called via an explicitly annotated name. Annotate the variable with `Chai.Assert` or call it directly: diff --git a/config/repeats.md b/config/repeats.md index 733644c5f..7f13ebba3 100644 --- a/config/repeats.md +++ b/config/repeats.md @@ -4,7 +4,7 @@ outline: deep --- # repeats - + - **Type:** `number` - **Default:** `0` - **CLI:** `--repeats=` diff --git a/guide/browser/index.md b/guide/browser/index.md index 4aa057bde..40d27ee8f 100644 --- a/guide/browser/index.md +++ b/guide/browser/index.md @@ -118,13 +118,7 @@ export default defineConfig({ ``` ::: info -<<<<<<< HEAD Vitest 默认分配端口号 `63315` 以避免与开发服务器冲突，允许我们同时并行运行两者。我们可以通过 [`browser.api`](/config/browser/api) 选项来更改这个端口号。 - -CLI 不会自动打印 Vite 服务器 URL。在观察模式下运行时，你可以按 "b" 键来打印 URL。 -======= -Vitest assigns port `63315` to avoid conflicts with the development server, allowing you to run both in parallel. You can change that with the [`browser.api`](/config/browser/api) option. ->>>>>>> 8430ac3c5895ab2beaa27433b4386989c69fc6ee ::: 如果之前未使用过 Vite，请确保已安装框架插件并在配置中指定。有些框架可能需要额外配置才能运行，请查看其 Vite 相关文档以确定。 diff --git a/guide/cli-generated.md b/guide/cli-generated.md index 7f9b92fbc..9a0c9c0d5 100644 --- a/guide/cli-generated.md +++ b/guide/cli-generated.md @@ -636,7 +636,7 @@ UI 模式和 HTML 报告器中提供的 HTML 覆盖率输出目录。 - **配置:** [retry.condition](/config/retry#retry-condition) 触发重试操作的错误信息匹配正则表达式。仅当错误信息符合该模式时才会执行重试（默认值：所有错误都会触发重试） - + ### repeats - **CLI:** `--repeats ` diff --git a/guide/in-source.md b/guide/in-source.md index b4a32c1ad..0add65974 100644 --- a/guide/in-source.md +++ b/guide/in-source.md @@ -154,16 +154,12 @@ module.exports = { ``` 完整的示例请参考 [`examples/in-source-test`](https://github.com/vitest-dev/vitest/tree/main/examples/in-source-test)。 - -<<<<<<< HEAD -## 说明 {#notes} -======= + ::: warning There is a limitation when using [assertion functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions) such as `assert` in in-source tests. See [`assert`](/api/assert#in-source-testing) for details and workarounds. ::: -## Notes ->>>>>>> 8430ac3c5895ab2beaa27433b4386989c69fc6ee +## 说明 {#notes} 此功能可用于: diff --git a/guide/learn/setup-teardown.md b/guide/learn/setup-teardown.md index 04e25aabd..1823e439a 100644 --- a/guide/learn/setup-teardown.md +++ b/guide/learn/setup-teardown.md @@ -41,21 +41,12 @@ test('can remove an item', () => { test('can add an item', () => { items.push('date') expect(items).toHaveLength(4) -<<<<<<< HEAD - // afterEach 会为下一个测试重置项目， - // 因此此处的修改不会影响到其他测试 -}) -``` - -如果没有这些钩子，第二个测试的 `push` 操作会影响其后的所有测试，这是导致测试不稳定的典型原因。这些钩子确保了每个测试都拥有干净的状态。 -======= // beforeEach reset the array to 3 items before this test ran, // proving that mutations from the previous test do not leak. }) ``` - + Without these hooks, mutations like `pop` or `push` from earlier tests would affect subsequent ones, which is a classic source of flaky tests, while the hooks guarantee clean state for every test. ->>>>>>> 8430ac3c5895ab2beaa27433b4386989c69fc6ee ## 一次性初始化 {#one-time-setup} diff --git a/guide/migration.md b/guide/migration.md index 160c288d8..1758c866e 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -138,17 +138,13 @@ $ cd subdir && vitest --config ../vitest.config.ts # [!code ++] Assignments to properties on `globalThis` or `window` in `jsdom` and `happy-dom` environments are now propagated to the underlying DOM implementation. Mutable properties such as `innerWidth` can affect APIs implemented by the DOM environment, for example `happy-dom`'s `matchMedia`. -<<<<<<< HEAD -## 迁移至 Vitest 4.0 {#vitest-4} -======= ### Browser Orchestrator URL Requires a Session Vitest no longer serves the browser orchestrator UI from a bare `/__vitest_test__/` URL. Browser runner URLs are now session-bound and must include the `sessionId` generated by Vitest, for example `/__vitest_test__/?sessionId=...`. If you manually opened the browser preview by copying the Vite server URL or visiting `/__vitest_test__/` directly, use the URL opened or printed by Vitest instead. -## Migrating to Vitest 4.0 {#vitest-4} ->>>>>>> 8430ac3c5895ab2beaa27433b4386989c69fc6ee +## 迁移至 Vitest 4.0 {#vitest-4} ::: warning 前提条件 Vitest 4.0 要求 **Vite >= 6.0.0** 和 **Node.js >= 20.0.0**。