From 27ffbf23ee5c2ba8fe5ff39caad6a4e1c1dca35e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ari=20Perkki=C3=B6?= Date: Wed, 18 Mar 2026 19:25:14 +0200 Subject: [PATCH 1/4] docs(recipes): missing `test` property (#9902) --- guide/recipes.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/guide/recipes.md b/guide/recipes.md index 7732006e..7ab89617 100644 --- a/guide/recipes.md +++ b/guide/recipes.md @@ -15,15 +15,19 @@ export default defineConfig({ test: { projects: [ { - // Non-isolated unit tests - name: 'Unit tests', - isolate: false, - exclude: ['**.integration.test.ts'], + test: { + // Non-isolated unit tests + name: 'Unit tests', + isolate: false, + exclude: ['**.integration.test.ts'], + }, }, { - // Isolated integration tests - name: 'Integration tests', - include: ['**.integration.test.ts'], + test: { + // Isolated integration tests + name: 'Integration tests', + include: ['**.integration.test.ts'], + }, }, ], }, @@ -41,13 +45,17 @@ export default defineConfig({ test: { projects: [ { - name: 'Parallel', - exclude: ['**.sequential.test.ts'], + test: { + name: 'Parallel', + exclude: ['**.sequential.test.ts'], + }, }, { - name: 'Sequential', - include: ['**.sequential.test.ts'], - fileParallelism: false, + test: { + name: 'Sequential', + include: ['**.sequential.test.ts'], + fileParallelism: false, + }, }, ], }, From 2516a3fddf339f847e4128d62d5f0169b6c86158 Mon Sep 17 00:00:00 2001 From: Shaneth Dehipitiya Date: Wed, 18 Mar 2026 15:29:17 -0400 Subject: [PATCH 2/4] docs(browser): explain locator differences from testing-library (#9903) Co-authored-by: Vladimir Sheremet --- api/browser/locators.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/api/browser/locators.md b/api/browser/locators.md index fbcd838b..a4da5a8c 100644 --- a/api/browser/locators.md +++ b/api/browser/locators.md @@ -13,6 +13,29 @@ The locator API uses a fork of [Playwright's locators](https://playwright.dev/do This page covers API usage. To better understand locators and their usage, read [Playwright's "Locators" documentation](https://playwright.dev/docs/locators). ::: +::: tip Difference from `testing-library` +Vitest's `page.getBy*` methods return a locator object, not a DOM element. This makes locator queries composable and allows Vitest to retry interactions and assertions when needed. + +Compared to testing-library queries: + +- Use locator chaining (`.getBy*`, `.filter`, `.nth`) instead of `within(...)`. +- Keep locators around and interact with them later (`await locator.click()`), instead of resolving elements up front. +- Single-element escape hatches like `.element()` and `.query()` are strict and throw if multiple elements match. + +```ts +import { expect } from 'vitest' +import { page } from 'vitest/browser' + +const deleteButton = page + .getByRole('row') + .filter({ hasText: 'Vitest' }) + .getByRole('button', { name: /delete/i }) + +await deleteButton.click() +await expect.element(deleteButton).toBeEnabled() +``` +::: + ## getByRole ```ts From 533b7d49f571f3024e559dee4f55f67d7212a838 Mon Sep 17 00:00:00 2001 From: Srasti Jain Date: Thu, 19 Mar 2026 01:32:21 +0530 Subject: [PATCH 3/4] docs: add Unhandled Promise Rejection section to common errors guide (#9879) Co-authored-by: Vladimir Sheremet --- guide/common-errors.md | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/guide/common-errors.md b/guide/common-errors.md index e3808fb7..23a154ef 100644 --- a/guide/common-errors.md +++ b/guide/common-errors.md @@ -121,3 +121,47 @@ export default defineConfig({ vitest --pool=forks ``` ::: + +## Unhandled Promise Rejection + +This error happens when a Promise rejects but no `.catch()` handler or `await` is attached to it before the microtask queue flushes. This behavior comes from JavaScript itself and is not specific to Vitest. Learn more in the [Node.js documentation](https://nodejs.org/api/process.html#event-unhandledrejection). + +A common cause is calling an async function without `await`ing it: + +```ts +async function fetchUser(id) { + const res = await fetch(`/api/users/${id}`) + if (!res.ok) { + throw new Error(`User ${id} not found`) // [!code highlight] + } + return res.json() +} + +test('fetches user', async () => { + fetchUser(123) // [!code error] +}) +``` + +Because `fetchUser()` is not `await`ed, its rejection has no handler and Vitest reports: + +``` +Unhandled Rejection: Error: User 123 not found +``` + +### Fix + +`await` the promise so Vitest can catch the error: + +```ts +test('fetches user', async () => { + await fetchUser(123) // [!code ++] +}) +``` + +If you expect the call to throw, use [`expect().rejects`](/api/expect#rejects): + +```ts +test('rejects for missing user', async () => { + await expect(fetchUser(123)).rejects.toThrow('User 123 not found') +}) +``` From 778e3e267f0e34dce23a38a75fb4ace29a708967 Mon Sep 17 00:00:00 2001 From: noise Date: Fri, 20 Mar 2026 00:37:28 +0800 Subject: [PATCH 4/4] docs(cn): dissolve the conflict --- api/browser/locators.md | 2 +- guide/common-errors.md | 2 +- guide/recipes.md | 12 ------------ 3 files changed, 2 insertions(+), 14 deletions(-) diff --git a/api/browser/locators.md b/api/browser/locators.md index 0bf36d5f..023a8bc1 100644 --- a/api/browser/locators.md +++ b/api/browser/locators.md @@ -12,7 +12,7 @@ outline: [2, 3] ::: tip 本页介绍了 API 的使用。为了更好地了解定位器及其用法，请阅读 [Playwright 的“定位器”文档](https://playwright.dev/docs/locators)。 ::: - + ::: tip Difference from `testing-library` Vitest's `page.getBy*` methods return a locator object, not a DOM element. This makes locator queries composable and allows Vitest to retry interactions and assertions when needed. diff --git a/guide/common-errors.md b/guide/common-errors.md index 21c87a60..ae7bbf0a 100644 --- a/guide/common-errors.md +++ b/guide/common-errors.md @@ -123,7 +123,7 @@ vitest --pool=forks ``` ::: - + ## Unhandled Promise Rejection This error happens when a Promise rejects but no `.catch()` handler or `await` is attached to it before the microtask queue flushes. This behavior comes from JavaScript itself and is not specific to Vitest. Learn more in the [Node.js documentation](https://nodejs.org/api/process.html#event-unhandledrejection). diff --git a/guide/recipes.md b/guide/recipes.md index 82c9b925..973c0659 100644 --- a/guide/recipes.md +++ b/guide/recipes.md @@ -15,17 +15,6 @@ export default defineConfig({ test: { projects: [ { -<<<<<<< HEAD - // 禁用隔离的单元测试 - name: 'Unit tests', - isolate: false, - exclude: ['**.integration.test.ts'], - }, - { - // 集成隔离的测试 - name: 'Integration tests', - include: ['**.integration.test.ts'], -======= test: { // Non-isolated unit tests name: 'Unit tests', @@ -39,7 +28,6 @@ export default defineConfig({ name: 'Integration tests', include: ['**.integration.test.ts'], }, ->>>>>>> 533b7d49f571f3024e559dee4f55f67d7212a838 }, ], },