[READ-ONLY] Mirror of https://github.com/vitest-dev/vitest. Next generation testing framework powered by Vite.
vitest.dev
test
testing-tools
vite
docs(browser): explain locator differences from testing-library (#9903)
Co-authored-by: Vladimir Sheremet <sleuths.slews0s@icloud.com>
authored by
Shaneth Dehipitiya
Vladimir Sheremet
and committed by
GitHub
(Mar 18, 2026, 8:29 PM +0100)
a2bfc0c2
75e8216f
+23
+23
docs/api/browser/locators.md
+23
docs/api/browser/locators.md
···
13
13
This page covers API usage. To better understand locators and their usage, read [Playwright's "Locators" documentation](https://playwright.dev/docs/locators).
14
14
:::
15
15
16
+
::: tip Difference from `testing-library`
17
+
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.
18
+
19
+
Compared to testing-library queries:
20
+
21
+
- Use locator chaining (`.getBy*`, `.filter`, `.nth`) instead of `within(...)`.
22
+
- Keep locators around and interact with them later (`await locator.click()`), instead of resolving elements up front.
23
+
- Single-element escape hatches like `.element()` and `.query()` are strict and throw if multiple elements match.
24
+
25
+
```ts
26
+
import { expect } from 'vitest'
27
+
import { page } from 'vitest/browser'
28
+
29
+
const deleteButton = page
30
+
.getByRole('row')
31
+
.filter({ hasText: 'Vitest' })
32
+
.getByRole('button', { name: /delete/i })
33
+
34
+
await deleteButton.click()
35
+
await expect.element(deleteButton).toBeEnabled()
36
+
```
37
+
:::
38
+
16
39
## getByRole
17
40
18
41
```ts