mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 18:19:48 +08:00
A test fails with this code only when it reaches `screen.pause()` with `CI` set, now that the MCP `run_tests` tool is gone. The name says so.
1443 lines
48 KiB
Plaintext
1443 lines
48 KiB
Plaintext
---
|
|
title: screen and Locator
|
|
description: Queries, refinement, actions, and reads.
|
|
"og:image": "https://e2e.com/docs/images/og/reference/screen.png?v=1b21c45d37"
|
|
"twitter:image": "https://e2e.com/docs/images/og/reference/screen.png?v=1b21c45d37"
|
|
---
|
|
|
|
The `screen` fixture builds locators. A `Locator` stores a query and resolves
|
|
it when an action, read, or assertion runs. Every query also runs on a
|
|
locator, scoped to its subtree.
|
|
|
|
```ts title="tests/invoices.e2e.ts"
|
|
import { expect, test } from 'e2e';
|
|
|
|
test('void an invoice', async ({ app, screen }) => {
|
|
await app.open('/invoices');
|
|
const row = screen.getByRole('listitem').filter({ hasText: 'Invoice 42' });
|
|
await row.getByRole('button', 'Void').tap();
|
|
await expect(row.getByText('Voided')).toBeVisible();
|
|
});
|
|
```
|
|
|
|
## Reference
|
|
|
|
### Queries
|
|
|
|
| Method | Returns |
|
|
| --- | --- |
|
|
| [`getByRole`](#getbyrole) | `Locator` |
|
|
| [`getByLabel`](#getbylabel) | `Locator` |
|
|
| [`getByPlaceholder`](#getbyplaceholder) | `Locator` |
|
|
| [`getByText`](#getbytext) | `Locator` |
|
|
| [`getByDisplayValue`](#getbydisplayvalue) | `Locator` |
|
|
| [`getByTestId`](#getbytestid) | `Locator` |
|
|
|
|
Every query returns a `Locator` synchronously and performs no work. An
|
|
option key the query does not take (`{ nam: 'Save' }`) throws
|
|
`INVALID_LOCATOR` naming the keys it does.
|
|
|
|
A string passed to `getByRole` as the name, `getByLabel`, `getByPlaceholder`,
|
|
`getByText`, or `getByDisplayValue` matches the whole text, case-sensitive,
|
|
after whitespace normalization: `getByRole('button', 'Save')` does not match
|
|
`Save changes`. `{ exact: false }` makes it a case-insensitive substring
|
|
match, and a `RegExp` matches as written.
|
|
|
|
Every query accepts `visible: true`; see
|
|
[Hidden duplicates](#hidden-duplicates).
|
|
|
|
#### `getByRole`
|
|
|
|
Matches nodes by [role](#types), optionally narrowed to an accessible name
|
|
and to states.
|
|
|
|
```ts
|
|
/** Creates a lazy role query. An alias such as `img` is rewritten to its role. */
|
|
getByRole(role: Role | RoleAlias, options?: RoleOptions): Locator;
|
|
/** Creates a lazy role query narrowed to an accessible name: `getByRole('button', 'Sign in')`. */
|
|
getByRole(role: Role | RoleAlias, name: TextMatch, options?: Omit<RoleOptions, 'name'>): Locator;
|
|
```
|
|
|
|
```ts
|
|
screen.getByRole('button', 'Save');
|
|
screen.getByRole('button', 'Save', { exact: false });
|
|
screen.getByRole('button', { name: 'Save', disabled: true }); // the object form
|
|
screen.getByRole('heading', /welcome/i, { level: 1 });
|
|
```
|
|
|
|
The accessible name goes second, a string or a `RegExp`, with the other
|
|
options after it. The object form, `{ name: 'Save' }`, is the same query.
|
|
The options are [`RoleOptions`](#types).
|
|
|
|
<Note>
|
|
A role query never matches a node hidden from the accessibility tree: one
|
|
that does not render, or one under `aria-hidden`. On the other query kinds,
|
|
`visible: true` keeps only nodes that render, the same check `toBeVisible()`
|
|
makes, so an `aria-hidden` node that still paints counts as visible. See
|
|
[Hidden duplicates](#hidden-duplicates).
|
|
</Note>
|
|
|
|
##### `img` alias
|
|
|
|
`img` is an alias, not a role ([`RoleAlias`](#types)).
|
|
`getByRole('img', { name })` builds the same query as
|
|
`getByRole('image', { name })`, so a test ported from Playwright keeps its
|
|
spelling. On the web, `image` covers `<img>` with alt text and any element
|
|
with `role="img"`. An `<img alt="">` is decoration and matches nothing,
|
|
unless it has a `title`, a `tabindex`, or a global ARIA attribute: then it is
|
|
an `image`.
|
|
|
|
##### Roles on the web
|
|
|
|
The web engine derives the roles from HTML the way HTML-AAM does:
|
|
|
|
- `<progress>` is `progressbar`, `<meter>` is `meter`, `<hr>` is `separator`.
|
|
- `<fieldset>` and `<details>` are `group`.
|
|
- `<input type="number">` is `spinbutton`. `<input type="file">` is `button`,
|
|
as Chrome and Playwright read it.
|
|
- `<select size="3">` is a `listbox`, like a `multiple` one. An
|
|
`<input list>` naming a `<datalist>` is a `combobox`.
|
|
- A `<td>` of a `role="grid"` table is a `gridcell`.
|
|
- `<thead>` and `<tbody>` are `rowgroup`.
|
|
- `<th scope="row">` is `rowheader`. A scope-less `<th>` beside a data cell
|
|
with text or children is also a `rowheader`; header-only rows keep
|
|
`columnheader`. A lone scope-less header in a one-row table has no header
|
|
role, but an explicit `scope="col"` or `scope="colgroup"` keeps
|
|
`columnheader`.
|
|
- `<figure>` is `figure`, `<article>` is `article`.
|
|
- `<header>` and `<footer>` are `banner` and `contentinfo` only outside
|
|
sectioning content or an element with a sectioning role (`article`,
|
|
`complementary`, `main`, `navigation`, `region`).
|
|
- `<form>` and `<section>` are `form` and `region` only when they carry an
|
|
`aria-label`, `aria-labelledby`, or `title`.
|
|
- `<menu>` is a `list`; only `role="menu"` is a `menu`.
|
|
- `role="presentation"` and `role="none"` are ignored on a focusable element
|
|
or one with a global ARIA attribute such as `aria-label`, as `getByRole`
|
|
reads them: `<button role="none">` is still a `button`.
|
|
|
|
Names follow the same rules:
|
|
|
|
- A `<legend>`, `<figcaption>`, or `<caption>` names its fieldset, figure, or
|
|
table, so `toHaveAccessibleName` reads what `getByRole('group', { name })`
|
|
matched.
|
|
- A role that accname names from content (a button, link, heading, tab, menu
|
|
item, option, checkbox, radio, switch, cell, row or column header, row, tree
|
|
item, tooltip) takes its name from its descendants, a custom element's
|
|
shadow tree included. So `getByRole('checkbox', { name })` and
|
|
`toHaveAccessibleName(name)` agree on a `<div role="checkbox">`. A
|
|
descendant with a role of its own that is not text or structure (a `status`
|
|
badge, a tree item's child `group`, an `img`) adds only its label or
|
|
`title`: a tab holding `Inbox <span role="status">3</span>` is `Inbox`.
|
|
- An `<input type="submit">` or `type="reset"` with no `value` reads `Submit`
|
|
or `Reset`.
|
|
|
|
##### Roles on a device
|
|
|
|
A device engine maps the platform types it has: a tab bar or segmented
|
|
control is a `tablist`, a progress indicator a `progressbar`, a stepper a
|
|
`spinbutton`. It keeps any other type verbatim, so a role with no native
|
|
widget, such as `tooltip` or `figure`, matches nothing on a phone.
|
|
|
|
##### Editing hosts
|
|
|
|
A `contenteditable` editing host, the root a TipTap, ProseMirror, Lexical, or
|
|
Slate editor renders into, is a `textbox`.
|
|
|
|
- Its value is its text as rendered. While it has focus, its `selection` is
|
|
the text selected inside it. The value keeps spaces and newlines, so
|
|
`toHaveValue` and `inputValue()` read a `white-space: pre-wrap` editor like
|
|
a textarea.
|
|
- An empty editor reads as `''`: one holding only the `<p><br></p>` or the
|
|
zero-width no-break space its editor pads an empty line with. That padding
|
|
is never part of a value.
|
|
- It is named by its `aria-label`, `aria-placeholder`, or the
|
|
`data-placeholder` its editor paints. The blocks inside it are content, not
|
|
textboxes.
|
|
- The tag does not matter: an `<article contenteditable>` is the editor, not
|
|
an article. A native control or a drawn surface made editable keeps its own
|
|
role.
|
|
- A name from a block's `data-placeholder` (TipTap, ProseMirror) goes once
|
|
the editor has content, as the painted hint does. From then on the host is
|
|
an unnamed `textbox`. A name from the host's own `aria-label`,
|
|
`aria-labelledby`, `aria-placeholder`, or `data-placeholder` (Quill) stays.
|
|
|
|
`getByRole` resolves through Playwright's role selector, which has no such
|
|
rule. So `getByRole` finds an editor only when the host carries
|
|
`role="textbox"`; `getByLabel` and `getByTestId` reach it either way. Anchor
|
|
a test on a label or a test id, not on the placeholder.
|
|
|
|
#### `getByLabel`
|
|
|
|
```ts
|
|
/** Creates a lazy accessible-label query. */
|
|
getByLabel(text: TextMatch, options?: TextMatchOptions): Locator;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('Email').fill('ada@example.test');
|
|
```
|
|
|
|
#### `getByPlaceholder`
|
|
|
|
```ts
|
|
/** Creates a lazy placeholder query. */
|
|
getByPlaceholder(text: TextMatch, options?: TextMatchOptions): Locator;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByPlaceholder('Search memory...').fill('launch');
|
|
```
|
|
|
|
#### `getByText`
|
|
|
|
```ts
|
|
/** Creates a lazy visible-text query. */
|
|
getByText(text: TextMatch, options?: TextMatchOptions): Locator;
|
|
```
|
|
|
|
```ts
|
|
screen.getByText('Welcome back', { exact: false });
|
|
```
|
|
|
|
##### Echoed text
|
|
|
|
`getByText` answers with the innermost matching node, so a container that
|
|
echoes its child's text counts once. Browsers do this natively. On a device
|
|
the engine applies the same rule, since iOS reports a React Native `Text` as
|
|
a host view plus a `StaticText` child with the same label. Two matches that
|
|
do not contain each other remain `LOCATOR_AMBIGUOUS`.
|
|
|
|
#### `getByDisplayValue`
|
|
|
|
Matches controls by their displayed value.
|
|
|
|
```ts
|
|
/** Creates a lazy displayed-value query. */
|
|
getByDisplayValue(value: TextMatch, options?: TextMatchOptions): Locator;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByDisplayValue('ada@example.test').clear();
|
|
```
|
|
|
|
<Note>
|
|
In the web engine a `getByDisplayValue` locator cannot be the scope of a
|
|
child query or a `has` filter; both fail with `UNSUPPORTED_CAPABILITY`.
|
|
Playwright has no selector for a control's current value, so the engine
|
|
filters candidates after the fact.
|
|
</Note>
|
|
|
|
#### `getByTestId`
|
|
|
|
Matches the node's `testId`.
|
|
|
|
```ts
|
|
/** Creates a lazy test-id query: a string matches the whole id, case-sensitive; a RegExp tests it. An engine may also match an id without its platform's namespacing. */
|
|
getByTestId(id: TextMatch, options?: { visible?: boolean }): Locator;
|
|
```
|
|
|
|
```ts
|
|
screen.getByTestId('todo-3');
|
|
screen.getByTestId(/total-budgeted$/);
|
|
```
|
|
|
|
- On the web, `testId` is the value of the engine's test-id attribute
|
|
(`web({ testIdAttribute })`, default `data-testid`).
|
|
- On a device, it is the accessibility identifier or resource id. For
|
|
namespacing, see the mobile engine's
|
|
[Android resource ids](/reference/mobile#capabilities).
|
|
- `visible` is the only option.
|
|
|
|
#### Hidden duplicates
|
|
|
|
Every query accepts `visible: true`, which drops nodes the platform reports
|
|
as hidden before the exactly-one rule runs. Frameworks often keep a hidden
|
|
copy of content in the document, such as a closed drawer or an inactive tab
|
|
panel, and without `visible` both copies match.
|
|
|
|
```ts
|
|
await browser.reload();
|
|
// Two "No memories yet" nodes exist for a moment; one is display:none.
|
|
await expect(screen.getByText('No memories yet', { visible: true })).toBeVisible();
|
|
await screen.getByPlaceholder('Search memory...', { visible: true }).fill('launch');
|
|
await screen.getByTestId('memory-list', { visible: true }).getByRole('listitem').first().tap();
|
|
```
|
|
|
|
`visible` uses the same visibility check as `toBeVisible()`, `isVisible()`,
|
|
and `waitFor()`: what renders, as Playwright reads it.
|
|
|
|
- Hidden: `display: none`, `visibility: hidden`, a box with no size, a closed
|
|
`<details>` body, and content under `content-visibility: hidden`.
|
|
- Not hidden: `aria-hidden`, since a decorative spinner marked with it still
|
|
paints, so `toBeHidden()` on one waits until it leaves.
|
|
- A child that sets `visibility: visible` under a hidden parent is visible.
|
|
- On the web, text directly under a `display: contents` element with
|
|
`visibility: hidden` is hidden, where Playwright calls it visible.
|
|
- On the web, everything inside a hidden `<iframe>` is hidden, cross-origin
|
|
frames included.
|
|
- It works with scopes, `filter`, `first`, `last`, and `nth`:
|
|
`getByText('Save', { visible: true }).first()` is the first visible match.
|
|
|
|
Prefer it over `browser.locator('p:visible')`, which ties the test to CSS.
|
|
|
|
### Refinement
|
|
|
|
| Method | Returns |
|
|
| --- | --- |
|
|
| [`filter`](#filter) | `Locator` |
|
|
| [`or`](#or) | `Locator` |
|
|
| [`first`](#first) | `Locator` |
|
|
| [`last`](#last) | `Locator` |
|
|
| [`nth`](#nth) | `Locator` |
|
|
|
|
Refinement returns a new locator without querying the app.
|
|
|
|
#### `filter`
|
|
|
|
```ts
|
|
/** Adds deterministic locator filters. */
|
|
filter(options: { hasText?: TextMatch; hasNotText?: TextMatch; has?: Locator; hasNot?: Locator }): Locator;
|
|
```
|
|
|
|
```ts
|
|
const row = screen.getByRole('listitem').filter({ hasText: 'Invoice 42', hasNotText: 'Paid' });
|
|
await row.getByRole('button', 'Void').tap();
|
|
```
|
|
|
|
- `hasText` with a string is a case-insensitive substring match over the
|
|
match and its descendants, unlike a query text, which matches exactly. Pass
|
|
a `RegExp` for anything stricter.
|
|
- `hasNotText` excludes matches with that subtree text, using the same
|
|
substring or `RegExp` rules.
|
|
- `has` keeps a match whose subtree resolves the inner locator.
|
|
- `hasNot` drops a match whose subtree resolves the inner locator. It follows
|
|
the same scoping rules as `has`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_LOCATOR` | None of `hasText`, `hasNotText`, `has`, or `hasNot` is given. |
|
|
| `INVALID_LOCATOR` | Any other key, even beside them: `visible` is not a filter here. |
|
|
| `INVALID_LOCATOR` | `has` or `hasNot` is not a runner locator, or was made by another target's screen. |
|
|
|
|
#### `or`
|
|
|
|
```ts
|
|
/** Matches either locator, preserving document order without duplicate nodes. */
|
|
or(other: Locator): Locator;
|
|
```
|
|
|
|
`a.or(b)` matches either branch once, in document order. It stays strict:
|
|
when both match different nodes, an action throws `LOCATOR_AMBIGUOUS`.
|
|
Add `first()` if either will do. Both locators must come from the same
|
|
screen and attempt. On web, both need identical literal frame-selector
|
|
chains; display-value branches cannot be composed.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_LOCATOR` | `other` is not a runner locator, or belongs to another screen or attempt. |
|
|
| `UNSUPPORTED_CAPABILITY` | Web branches have different frame-selector chains, or a branch is a display-value query. |
|
|
|
|
#### `first`
|
|
|
|
```ts
|
|
/** Selects the first current match. */
|
|
first(): Locator;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('listitem').first().tap();
|
|
```
|
|
|
|
#### `last`
|
|
|
|
```ts
|
|
/** Selects the last current match. */
|
|
last(): Locator;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('listitem').last().tap();
|
|
```
|
|
|
|
#### `nth`
|
|
|
|
```ts
|
|
/** Selects one zero-based current match. */
|
|
nth(index: number): Locator;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('row').nth(2).getByRole('checkbox').check();
|
|
```
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_LOCATOR` | A negative or non-integer index. |
|
|
|
|
### Screen actions
|
|
|
|
| Method | Returns |
|
|
| --- | --- |
|
|
| [`screen.tapAt`](#screen-tapat) | `Promise<void>` |
|
|
| [`screen.doubleTapAt`](#screen-doubletapat) | `Promise<void>` |
|
|
| [`screen.swipe`](#screen-swipe) | `Promise<void>` |
|
|
| [`screen.scrollUntilVisible`](#screen-scrolluntilvisible) | `Promise<void>` |
|
|
|
|
`tapAt`, `doubleTapAt`, and `swipe` act on the viewport.
|
|
|
|
#### `screen.tapAt`
|
|
|
|
Use it for a pin on a canvas or a control the tree does not list.
|
|
|
|
```ts
|
|
/** Taps a viewport point, with no node behind it. */
|
|
tapAt(point: Point, options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
const map = (await screen.getByRole('image', 'Map').boundingBox())!;
|
|
await screen.tapAt({ x: map.x + 360, y: map.y + 70 });
|
|
```
|
|
|
|
- The point is in CSS pixels, the space `boundingBox()` reports in.
|
|
- Nothing is resolved or waited for; the page decides what the tap lands on.
|
|
- Uses `config.actionTimeout`.
|
|
- Prefer a locator when the tree lists the control, since a point moves with
|
|
the layout. For a point inside a node, `tap({ position })` reads the node's
|
|
box for you.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | A negative or non-finite coordinate. |
|
|
| `UNSUPPORTED_CAPABILITY` | The engine does not list `tap` in its pointer actions. |
|
|
|
|
<Note>
|
|
`tapAt` is not scoped: on a locator it still taps a viewport point.
|
|
</Note>
|
|
|
|
#### `screen.doubleTapAt`
|
|
|
|
Use it to double-tap a viewport point when the tree does not list the target.
|
|
|
|
```ts
|
|
/** Double-taps a viewport point, with no node behind it. */
|
|
doubleTapAt(point: Point, options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.doubleTapAt({ x: 120, y: 240 }, { timeout: 1_000 });
|
|
```
|
|
|
|
- Use viewport coordinates in the same units as `boundingBox()`.
|
|
- The page or device decides what receives the gesture. On web, this sends a primary-button double-click.
|
|
- On a device, this sends two presses at the point, as `doubleTap()` does on a node. See [Known device limitations](/mobile#known-device-limitations) for their timing on iOS.
|
|
- Defaults to `config.actionTimeout`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | A negative or non-finite coordinate, or an unknown option. |
|
|
| `UNSUPPORTED_CAPABILITY` | The engine does not list `doubleTap` in its pointer actions. |
|
|
|
|
<Note>
|
|
`doubleTapAt` is not scoped: on a locator it still double-taps a viewport point.
|
|
</Note>
|
|
|
|
#### `screen.swipe`
|
|
|
|
```ts
|
|
/** Performs a viewport-level swipe: in a direction, or along a path from one point to another. */
|
|
swipe(options: SwipeOptions | SwipePathOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.swipe({ direction: 'up', momentum: 'fast' });
|
|
|
|
const row = (await screen.getByText('Design review').boundingBox())!;
|
|
await screen.swipe({
|
|
from: { x: row.x + row.width - 10, y: row.y + row.height / 2 },
|
|
to: { x: row.x + 10, y: row.y + row.height / 2 },
|
|
duration: 300,
|
|
});
|
|
```
|
|
|
|
`{ direction, momentum? }` is a scroll gesture on the screen:
|
|
|
|
- `direction` is the way the content scrolls, not the finger: `'down'`
|
|
reveals what is below.
|
|
- `momentum` is its fling strength, `'none'` by default. `'none'` is a
|
|
plain drag of half the surface, `'slow'` a short fling, `'fast'` a long
|
|
one. The engine decides how far each carries.
|
|
|
|
`{ from, to, duration? }` is a swipe along a path between two viewport
|
|
points: a touch swipe on a device, a pointer drag on a document platform.
|
|
Use it to reveal a row action, dismiss a sheet, or drag a card between
|
|
columns.
|
|
|
|
- `duration` is how long the gesture takes, an integer from 16 through
|
|
10000 ms. Omitted, it is the engine's default.
|
|
|
|
Uses `config.actionTimeout` and takes no `timeout` option.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `ACTION_FAILED` | The gesture is rejected. |
|
|
| `INVALID_ARGUMENT` | A mix of the two shapes, an out-of-range duration, a coordinate off the plane, or a `timeout` key. |
|
|
| `UNSUPPORTED_CAPABILITY` | The engine does not list `swipe` in its actions (a direction) or `swipeTo` in its pointer actions (a path). |
|
|
|
|
#### `screen.scrollUntilVisible`
|
|
|
|
```ts
|
|
/**
|
|
* Scrolls until a locator resolves visibly or times out: the viewport on
|
|
* `screen`, the node itself on a locator. `momentum` is the stride of each
|
|
* step, `slow` unless told otherwise.
|
|
*/
|
|
scrollUntilVisible(
|
|
target: Locator,
|
|
options?: { direction?: ScrollDirection; momentum?: Momentum; timeout?: number },
|
|
): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.scrollUntilVisible(screen.getByRole('button', 'Accept'));
|
|
await screen.getByTestId('feed').scrollUntilVisible(row);
|
|
```
|
|
|
|
| Option | Type | Default |
|
|
| --- | --- | --- |
|
|
| `target` | `Locator` | - |
|
|
| `options.direction` | `ScrollDirection` | `'down'` |
|
|
| `options.momentum` | `Momentum` | `'slow'` |
|
|
| `options.timeout` | `number` | `30000` |
|
|
|
|
- `momentum` is as [`screen.swipe`](#screen-swipe) defines it. A longer step
|
|
is faster, but it must not carry the target past the surface unseen, as a
|
|
virtualized list does.
|
|
- `timeout` is its own default, not `config.actionTimeout`. It bounds the
|
|
whole scroll, each swipe included.
|
|
- On a locator each step swipes that node. So a feed or a table that is its
|
|
own scroll container pages without the pointer hovering it first.
|
|
- It stops at the first match that is not hidden. On a device, a node under
|
|
the soft keyboard is hidden, so the scroll goes on
|
|
([Mobile visibility](/reference/mobile#visibility)).
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_LOCATOR` | `target` is not a runner locator, or was made by another target's screen. |
|
|
| `INVALID_ARGUMENT` | An option it does not take. |
|
|
| `LOCATOR_NOT_FOUND` | The deadline expires first, a swipe it cut short included. |
|
|
|
|
### Screen reads
|
|
|
|
| Method | Returns |
|
|
| --- | --- |
|
|
| [`screen.tree`](#screen-tree) | `Promise<string>` |
|
|
| [`screen.debug`](#screen-debug) | `Promise<void>` |
|
|
| [`screen.pause`](#screen-pause) | `Promise<void>` |
|
|
|
|
`tree` and `debug` read the whole screen once, without waiting, and work on
|
|
every engine. They run as a step. A locator does not have them, and a frame
|
|
throws `INVALID_ARGUMENT`.
|
|
|
|
#### `screen.tree`
|
|
|
|
Returns the screen as the agent reads it. Use it to write a locator.
|
|
|
|
```ts
|
|
/**
|
|
* Reads the whole screen once, without waiting, as the agent reads it: one
|
|
* node per line, `#id role "name" text="…" [states]`, children indented,
|
|
* secrets redacted.
|
|
*/
|
|
tree(options?: ActionOptions): Promise<string>;
|
|
```
|
|
|
|
```text
|
|
#n29 textbox "New todo"
|
|
#n30 button "Add"
|
|
#n35 listitem "Milk Delete Milk" testid="todo"
|
|
#n36 checkbox "Milk" [checked]
|
|
```
|
|
|
|
- Uses `config.actionTimeout`.
|
|
- The text has the same format and size limit as the trace's
|
|
[screen at failure](/debugging#traces).
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | Called on a frame, or with an option it does not take. |
|
|
|
|
#### `screen.debug`
|
|
|
|
Prints [`screen.tree()`](#screen-tree) to the test's
|
|
[console output](/debugging#console-output).
|
|
|
|
```ts
|
|
/** Prints `tree()` to the test's output. */
|
|
debug(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.debug();
|
|
```
|
|
|
|
#### `screen.pause`
|
|
|
|
The test is paused at this line, with the app open, until it is resumed.
|
|
See [Pause a test](/debugging#pause-a-test) for the keys and commands.
|
|
|
|
```ts
|
|
/**
|
|
* Pauses the test at this line, with the app open, until it is resumed with
|
|
* Enter in the terminal or with `e2e run --step next` from another shell in
|
|
* the same directory. In `e2e run`, the test is paused each time the line
|
|
* runs. Paused time doesn't count toward the test's timeout. Call it with
|
|
* `await` on `screen`, between steps in fixture setup, a `beforeEach` hook,
|
|
* or the test body. Anywhere else, or with `CI` set, the test isn't paused
|
|
* and the call fails.
|
|
*/
|
|
pause(): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.pause();
|
|
```
|
|
|
|
- The test is paused on every attempt, retries and setup tests included.
|
|
- In a `--step` run, the test is still paused at `screen.pause()` after
|
|
`n`, `a`, or `e2e run --step rest`.
|
|
- Paused time doesn't count toward any timeout.
|
|
- A test isn't paused in a session that an [MCP](/mcp-server)
|
|
`open_session {test}` opens, in a program on `@e2e-dev/core` or
|
|
`openHost`, or in `run()` from `e2e/runner`. With `CI` set, the test still
|
|
fails with `PAUSE_IN_CI` in `run()`, as in `e2e run`.
|
|
- In `e2e run --watch`, only the current run is cancelled when `q` is pressed
|
|
at a pause or `e2e run --step stop` is run.
|
|
- A locator doesn't have it.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `PAUSE_IN_CI` | `CI` is set. Remove the call before you commit, or run the test with `e2e run` in a terminal. A call where a pause isn't allowed fails with its error below instead. |
|
|
| `INVALID_ARGUMENT` | It is called on a locator or a frame, in an [`afterEach`](/reference/test#aftereach) hook, a fixture teardown, or unawaited code that runs after the body returned. Call it on `screen`, between steps in fixture setup, a `beforeEach` hook, or the test body. |
|
|
| `ACTION_FAILED` | It is called inside an agent step, such as an [`onAction`](/reference/agent#agent-act) hook or a [custom executor](/executors). The step fails with the pause's message, and the test isn't paused. In a [project tool](/tools) on the built-in agent, the refusal goes back to the model as a failed tool result and the step continues. Call it between steps instead. |
|
|
| `ASSERTION_FAILED` | It is called inside an [`expect.poll`](/reference/expect#polling-a-value) read. The read is retried until the poll times out. Call it outside the read. |
|
|
| `STEP_NOT_AWAITED` | The test body returns while a `screen.pause()` it did not await is still waiting. The test fails at the pause's line. Put `await` in front of the call. |
|
|
| `RUNNER_BUSY` | The run doesn't have a terminal, and another run in the directory is already controlled with `e2e run --step`. End that run with `e2e run --step stop`, or run this test in a terminal. Once the other run has ended, a test is paused at the next `screen.pause()` in this run. |
|
|
|
|
### Locator actions
|
|
|
|
| Method | Returns |
|
|
| --- | --- |
|
|
| [`tap`](#tap) | `Promise<void>` |
|
|
| [`click`](#tap) | `Promise<void>` |
|
|
| [`doubleTap`](#doubletap) | `Promise<void>` |
|
|
| [`dblclick`](#doubletap) | `Promise<void>` |
|
|
| [`secondaryTap`](#secondarytap) | `Promise<void>` |
|
|
| [`longPress`](#longpress) | `Promise<void>` |
|
|
| [`fill`](#fill) | `Promise<void>` |
|
|
| [`pressSequentially`](#presssequentially) | `Promise<void>` |
|
|
| [`clear`](#clear) | `Promise<void>` |
|
|
| [`press`](#press) | `Promise<void>` |
|
|
| [`check`](#check) | `Promise<void>` |
|
|
| [`uncheck`](#uncheck) | `Promise<void>` |
|
|
| [`selectOption`](#selectoption) | `Promise<void>` |
|
|
| [`focus`](#focus) | `Promise<void>` |
|
|
| [`hover`](#hover) | `Promise<void>` |
|
|
| [`setInputFiles`](#setinputfiles) | `Promise<void>` |
|
|
| [`dragTo`](#dragto) | `Promise<void>` |
|
|
| [`scrollIntoView`](#scrollintoview) | `Promise<void>` |
|
|
| [`swipe`](#swipe) | `Promise<void>` |
|
|
|
|
Each action resolves one node, waits for actionability, and performs one
|
|
operation. The timeout is
|
|
[`config.actionTimeout`](/reference/config#actiontimeout), and every action
|
|
takes `{ timeout }` to override it: `0` waits until
|
|
the test timeout, or `cleanupTimeout` in `afterEach`. An
|
|
action takes only the options its signature names.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `UNSUPPORTED_CAPABILITY` | The engine does not list the action's kind in `actions`; thrown before reaching the engine. |
|
|
| `INVALID_ARGUMENT` | An option key the action does not take, Playwright's `trial`, `force`, or `noWaitAfter` included, or a negative, `NaN`, or infinite `timeout`. Thrown before the node is resolved, so the control is never touched. |
|
|
| `LOCATOR_NOT_FOUND` | No match before the timeout. |
|
|
| `LOCATOR_AMBIGUOUS` | More than one match. |
|
|
| `ACTION_FAILED` | The action may already have committed; it is never repeated. |
|
|
|
|
#### `tap`
|
|
|
|
```ts
|
|
/** Taps exactly one matching actionable node; with `position`, taps that point of its box once it is in view, with no other actionability check. */
|
|
tap(options?: TapOptions): Promise<void>;
|
|
/** Alias of tap. */
|
|
click(options?: TapOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('button', 'Save').tap({ timeout: 10_000 });
|
|
await screen.getByRole('image', 'Seat map').tap({ position: { x: 120, y: 48 } });
|
|
await row.click({ modifiers: ['Shift'] });
|
|
```
|
|
|
|
The options are [`TapOptions`](#types):
|
|
|
|
- `modifiers`: the browser engine holds them.
|
|
- `position`: an offset from the node's top-left corner, inside its border,
|
|
in CSS pixels. The engine scrolls the node into view when it lists
|
|
`scrollIntoView`. Then it reads the node's box and dispatches the pointer at
|
|
the point. No node is behind the gesture, so the platform's other
|
|
actionability checks (enabled, not covered) do not run.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | An unknown or repeated modifier, or `modifiers` beside `position`. |
|
|
| `UNSUPPORTED_CAPABILITY` | `modifiers` on an engine that does not declare `tapModifiers`, the mobile engine among them; thrown before it acts. |
|
|
| `UNSUPPORTED_CAPABILITY` | `position` on an engine without the `tap` pointer action. |
|
|
| `ACTION_FAILED` | `position` on a node the browser engine cannot bring into view; its scroll waits for visibility. Other engines fail as they report it. |
|
|
| `LOCATOR_NOT_FOUND` | `position` on a node that resolves but never shows a visible box within the timeout. |
|
|
|
|
#### `doubleTap`
|
|
|
|
```ts
|
|
/** Double-taps exactly one matching actionable node. */
|
|
doubleTap(options?: ClickOptions): Promise<void>;
|
|
/** Alias of doubleTap. */
|
|
dblclick(options?: ClickOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('cell', 'Q3 budget').doubleTap();
|
|
```
|
|
|
|
Takes `timeout` and `modifiers`, with the same rules and errors as
|
|
[`tap`](#tap).
|
|
|
|
#### `secondaryTap`
|
|
|
|
```ts
|
|
/** Secondary-taps exactly one matching actionable node: a right click, a two-finger tap. */
|
|
secondaryTap(options?: ClickOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('row', /Invoice 42/).secondaryTap();
|
|
```
|
|
|
|
Takes `timeout` and `modifiers`, with the same rules and errors as
|
|
[`tap`](#tap).
|
|
|
|
#### `longPress`
|
|
|
|
```ts
|
|
/** Long-presses exactly one matching actionable node. */
|
|
longPress(options?: LongPressOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByText('Design review').longPress({ duration: 800 });
|
|
```
|
|
|
|
- `duration` is the hold time, an integer from 100 through 10000 ms.
|
|
Anything else is `INVALID_ARGUMENT`.
|
|
- Without it the engine's default applies: 500 ms on the browser engine, one
|
|
second on the mobile engine, past a React Native `Pressable`'s
|
|
`delayLongPress`.
|
|
|
|
#### `fill`
|
|
|
|
Replaces the input's current content.
|
|
|
|
```ts
|
|
/** Fills exactly one input. Secret values are never logged. */
|
|
fill(value: string | Secret, options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('Email').fill('ada@example.test');
|
|
await screen.getByLabel('Password').fill(credentials.user('member').password);
|
|
```
|
|
|
|
A `Secret` is resolved on the host right before the call and never logged,
|
|
reported, or sent to a model.
|
|
|
|
<Note>
|
|
`fill` sets the value directly and fires no key events. An autocomplete, a
|
|
search-as-you-type box, or a masked input wired to `keydown` or `keyup`
|
|
never reacts to it. Use [`pressSequentially`](#presssequentially) for those.
|
|
</Note>
|
|
|
|
#### `pressSequentially`
|
|
|
|
Types through the engine's keyboard and appends to the current content.
|
|
|
|
```ts
|
|
/**
|
|
* Focuses exactly one input and types `text` through the keyboard, one
|
|
* character at a time, so the app receives key events. A `Secret` is
|
|
* refused; it goes through `fill`.
|
|
*/
|
|
pressSequentially(text: string, options?: PressSequentiallyOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('City').pressSequentially('War', { delay: 50 });
|
|
```
|
|
|
|
- `delay` waits that many milliseconds between characters, each sent in its
|
|
own keyboard call. Without it the whole text goes in one call.
|
|
- Focus, pauses, and keystrokes share the one action deadline: a pause is cut
|
|
short at it and no character is sent past it.
|
|
- It relies on the [keyboard contract](/reference/engine#engine): `type` must
|
|
deliver text as a person typing would, so key events reach the app where
|
|
the platform has them.
|
|
- The step records the locator, not the text, like `fill`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `ACTION_FAILED` | The deadline passed mid-text; the error names how many characters landed. |
|
|
| `UNSUPPORTED_CAPABILITY` | The engine lacks the `focus` action or the `keyboard` capability; thrown before any node resolves. |
|
|
| `INVALID_ARGUMENT` | A `Secret` at runtime (a type error at compile time): a secret is filled, never typed as keystrokes. |
|
|
|
|
#### `clear`
|
|
|
|
```ts
|
|
/** Clears exactly one input. */
|
|
clear(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('Search').clear();
|
|
```
|
|
|
|
#### `press`
|
|
|
|
```ts
|
|
/** Sends one key to exactly one node. */
|
|
press(key: string, options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('textbox', 'Search').press('Enter');
|
|
await screen.getByRole('textbox', 'Notes').press('ControlOrMeta+a');
|
|
```
|
|
|
|
A key is zero or more modifiers and one key, joined with `+`, as the
|
|
[key grammar](/reference/engine#keys) lists them. `Shift++` presses `+`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `UNSUPPORTED_CAPABILITY` | A key the platform lacks. |
|
|
|
|
#### `check`
|
|
|
|
```ts
|
|
/** Checks exactly one node. */
|
|
check(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('checkbox', 'Remember me').check();
|
|
```
|
|
|
|
On the web engine, a checkbox or radio hidden under its own label (as in
|
|
Element Plus) is clicked through that label. Anything else on top of the
|
|
point the click lands on still fails `ACTION_FAILED`.
|
|
|
|
#### `uncheck`
|
|
|
|
```ts
|
|
/** Unchecks exactly one node. */
|
|
uncheck(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('checkbox', 'Remember me').uncheck();
|
|
```
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `ACTION_FAILED` | A checked native radio button, which only another radio in its group clears. |
|
|
|
|
#### `selectOption`
|
|
|
|
```ts
|
|
/** Selects one option from exactly one control. */
|
|
selectOption(value: SelectOption, options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('Plan').selectOption('Pro');
|
|
await screen.getByLabel('Plan').selectOption({ label: 'Pro' });
|
|
await screen.getByLabel('Plan').selectOption({ value: 'pro' });
|
|
```
|
|
|
|
Pass a label string, or an object with exactly one of `label`, `value` (the
|
|
value attribute, which the form submits), or `index` (zero-based).
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | More than one option per call: an array, or an object with more than one of those keys. Also a negative or fractional `index`. Thrown before the engine acts. |
|
|
|
|
#### `focus`
|
|
|
|
```ts
|
|
/** Focuses exactly one node. */
|
|
focus(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('Email').focus();
|
|
```
|
|
|
|
#### `hover`
|
|
|
|
```ts
|
|
/** Hovers over exactly one matching actionable node. */
|
|
hover(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('button', 'Account').hover();
|
|
```
|
|
|
|
#### `setInputFiles`
|
|
|
|
```ts
|
|
/** Sets the files of exactly one file input, or of a control that opens a file chooser; paths resolve from the project root, and an empty array clears the input. */
|
|
setInputFiles(paths: string | readonly string[], options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByLabel('Receipt').setInputFiles('fixtures/receipt.pdf');
|
|
await screen.getByLabel('Receipt').setInputFiles([]);
|
|
```
|
|
|
|
Web only. An empty array clears the input and fires `input` and `change`. It also takes a button that opens a file chooser.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | A blank path. |
|
|
| `UNSUPPORTED_CAPABILITY` | On a device, which has no file input. |
|
|
| `ACTION_FAILED` | A button that opens no file chooser. |
|
|
|
|
#### `dragTo`
|
|
|
|
```ts
|
|
/** Drags exactly one node to exactly one target. */
|
|
dragTo(target: Locator, options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByText('Design review').dragTo(screen.getByRole('region', 'Done'));
|
|
```
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_LOCATOR` | `target` is not a runner locator, or was made by another target's screen. |
|
|
|
|
#### `scrollIntoView`
|
|
|
|
```ts
|
|
/** Scrolls exactly one node into view. */
|
|
scrollIntoView(options?: ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByRole('contentinfo').scrollIntoView();
|
|
```
|
|
|
|
#### `swipe`
|
|
|
|
```ts
|
|
/** Performs a swipe scoped to exactly one node. */
|
|
swipe(options: SwipeOptions & ActionOptions): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByTestId('feed').swipe({ direction: 'down', momentum: 'slow' });
|
|
```
|
|
|
|
It takes `{ direction, momentum? }` as [`screen.swipe`](#screen-swipe)
|
|
defines them, plus `timeout`, which `screen.swipe` refuses. It has no
|
|
`{ from, to }` form.
|
|
|
|
### Locator reads
|
|
|
|
| Method | Returns |
|
|
| --- | --- |
|
|
| [`textContent`](#textcontent) | `Promise<string \| null>` |
|
|
| [`inputValue`](#inputvalue) | `Promise<string>` |
|
|
| [`getAttribute`](#getattribute) | `Promise<string \| null>` |
|
|
| [`isVisible`](#isvisible) | `Promise<boolean>` |
|
|
| [`isHidden`](#ishidden) | `Promise<boolean>` |
|
|
| [`isEnabled`](#isenabled) | `Promise<boolean>` |
|
|
| [`isDisabled`](#isdisabled) | `Promise<boolean>` |
|
|
| [`isChecked`](#ischecked) | `Promise<boolean>` |
|
|
| [`boundingBox`](#boundingbox) | `Promise<{ x, y, width, height } \| null>` |
|
|
| [`count`](#count) | `Promise<number>` |
|
|
| [`all`](#all) | `Promise<Locator[]>` |
|
|
| [`allTextContents`](#alltextcontents) | `Promise<string[]>` |
|
|
| [`waitFor`](#waitfor) | `Promise<void>` |
|
|
|
|
Reads follow the [Match rules](#match-rules). `count`, `all`, and
|
|
`allTextContents` take a snapshot and do not wait.
|
|
|
|
On a secure field, `textContent`, `inputValue`, `getAttribute`, and
|
|
`allTextContents` throw `POLICY_DENIED`, as the matching
|
|
[`expect` matchers](/reference/expect#secure-fields) do. `isEnabled`,
|
|
`isDisabled`, `isChecked`, and `boundingBox` are allowed there.
|
|
|
|
#### `textContent`
|
|
|
|
Reads the node's rendered text with whitespace collapsed to single spaces.
|
|
|
|
```ts
|
|
/** Reads normalized text once a match exists, without retrying for a particular value. */
|
|
textContent(): Promise<string | null>;
|
|
```
|
|
|
|
```ts
|
|
const message = await screen.getByRole('alert').textContent();
|
|
```
|
|
|
|
- On the web that is what `innerText` reads, not the DOM's `textContent`:
|
|
CSS `text-transform` applies, `display: none` descendants are left out, and
|
|
a `<br>` reads as a space.
|
|
- A node that is not rendered itself, such as a `display: none` one, reads
|
|
its DOM text, as `innerText` does.
|
|
|
|
#### `inputValue`
|
|
|
|
```ts
|
|
/** Reads the current input value. */
|
|
inputValue(): Promise<string>;
|
|
```
|
|
|
|
```ts
|
|
const email = await screen.getByLabel('Email').inputValue();
|
|
```
|
|
|
|
On a checkbox or radio, `inputValue()` and `toHaveValue` read its value
|
|
attribute, `on` when it has none, whatever its checked state. `isChecked()`
|
|
reads the state.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `ACTION_FAILED` | A node with no value, such as a heading or a button. A field with no value reads `""`. |
|
|
|
|
#### `getAttribute`
|
|
|
|
```ts
|
|
/** Reads one attribute. */
|
|
getAttribute(name: string): Promise<string | null>;
|
|
```
|
|
|
|
```ts
|
|
const href = await screen.getByRole('link', 'Docs').getAttribute('href');
|
|
```
|
|
|
|
#### `isVisible`
|
|
|
|
```ts
|
|
/** Reads current visibility. */
|
|
isVisible(): Promise<boolean>;
|
|
```
|
|
|
|
```ts
|
|
const open = await screen.getByRole('dialog').isVisible();
|
|
```
|
|
|
|
- `false` for zero matches, and for a `frameLocator` whose frame is not in
|
|
the document.
|
|
- Uses the same visibility check as `visible: true` (see
|
|
[Hidden duplicates](#hidden-duplicates)).
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `LOCATOR_AMBIGUOUS` | Several matches. |
|
|
|
|
#### `isHidden`
|
|
|
|
```ts
|
|
/** Reads current hidden or absent state, the negation of `isVisible`. */
|
|
isHidden(): Promise<boolean>;
|
|
```
|
|
|
|
```ts
|
|
const gone = await screen.getByTestId('spinner').isHidden();
|
|
```
|
|
|
|
It has the same strictness as `isVisible`: `true` for zero matches.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `LOCATOR_AMBIGUOUS` | Several matches. |
|
|
|
|
#### `isEnabled`
|
|
|
|
```ts
|
|
/** Reads current enabled state. */
|
|
isEnabled(): Promise<boolean>;
|
|
```
|
|
|
|
```ts
|
|
const ready = await screen.getByRole('button', 'Pay').isEnabled();
|
|
```
|
|
|
|
#### `isDisabled`
|
|
|
|
```ts
|
|
/** Reads current disabled state, the negation of `isEnabled`. */
|
|
isDisabled(): Promise<boolean>;
|
|
```
|
|
|
|
```ts
|
|
const blocked = await screen.getByRole('button', 'Pay').isDisabled();
|
|
```
|
|
|
|
It has the same strictness as `isEnabled`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `LOCATOR_NOT_FOUND` | Zero matches. |
|
|
| `LOCATOR_AMBIGUOUS` | Several matches. |
|
|
|
|
#### `isChecked`
|
|
|
|
```ts
|
|
/** Reads current checked state. */
|
|
isChecked(): Promise<boolean>;
|
|
```
|
|
|
|
```ts
|
|
const remembered = await screen.getByRole('checkbox', 'Remember me').isChecked();
|
|
```
|
|
|
|
A checkable role with no state reported, such as an ARIA switch without
|
|
`aria-checked`, reads `false`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `ACTION_FAILED` | A node with no checked state, such as a button or a heading. |
|
|
|
|
#### `boundingBox`
|
|
|
|
```ts
|
|
/** Reads the current viewport-relative rectangle. */
|
|
boundingBox(): Promise<{ x: number; y: number; width: number; height: number } | null>;
|
|
```
|
|
|
|
```ts
|
|
const map = (await screen.getByRole('image', 'Map').boundingBox())!;
|
|
```
|
|
|
|
The box is in CSS pixels, and on a device in points (physical pixels on
|
|
Android). It is `null` for a node that lays out no box
|
|
(`display: none` on it or an ancestor). A `visibility: hidden` node keeps
|
|
its box.
|
|
|
|
#### `count`
|
|
|
|
```ts
|
|
/** Counts current matches without auto-waiting. */
|
|
count(): Promise<number>;
|
|
```
|
|
|
|
```ts
|
|
const rows = await screen.getByRole('row').count();
|
|
```
|
|
|
|
`0` for zero matches, and for a `frameLocator` whose frame is not in the
|
|
document.
|
|
|
|
#### `all`
|
|
|
|
Resolves the query one time, so a loop can act on each row.
|
|
|
|
```ts
|
|
/** One `nth(i)` locator per current match, without auto-waiting; empty when nothing matches. */
|
|
all(): Promise<Locator[]>;
|
|
```
|
|
|
|
```ts
|
|
for (const row of await screen.getByRole('row').all()) {
|
|
await row.getByRole('checkbox').check();
|
|
}
|
|
```
|
|
|
|
- It neither waits nor enforces exactly-one: zero matches is an empty array,
|
|
the same snapshot rule as `count()`. A `frameLocator` whose frame is not in
|
|
the document counts as zero matches here, where an action or assertion
|
|
polls for it.
|
|
- Each locator that `all()` returns re-resolves when used. A list that changes
|
|
under the loop can make a later `nth(i)` point at a different row, or at
|
|
nothing. Follow the loop with an assertion on the list.
|
|
|
|
#### `allTextContents`
|
|
|
|
```ts
|
|
/** Reads the normalized text of every current match, without auto-waiting; empty when nothing matches. */
|
|
allTextContents(): Promise<string[]>;
|
|
```
|
|
|
|
```ts
|
|
expect(await screen.getByRole('listitem').allTextContents()).toEqual(['Alpha', 'Beta']);
|
|
```
|
|
|
|
- Text reads as in [`textContent`](#textcontent).
|
|
- It neither waits nor enforces exactly-one: zero matches is an empty array,
|
|
as for [`all`](#all).
|
|
- To check the texts, use
|
|
[`toHaveText([...])`](/reference/expect#locator-matchers) instead of a
|
|
loop.
|
|
|
|
#### `waitFor`
|
|
|
|
```ts
|
|
/**
|
|
* Waits for the requested locator state, `visible` by default: `attached`
|
|
* for one match, visible or not; `detached` for none; `hidden` for none or
|
|
* a hidden one.
|
|
*/
|
|
waitFor(options?: { state?: 'attached' | 'detached' | 'visible' | 'hidden'; timeout?: number }): Promise<void>;
|
|
```
|
|
|
|
```ts
|
|
await screen.getByTestId('spinner').waitFor({ state: 'hidden' }); // default state: 'visible'
|
|
```
|
|
|
|
| State | Waits for |
|
|
| --- | --- |
|
|
| `'visible'` (default) | One visible match. |
|
|
| `'attached'` | One match, hidden or shown. |
|
|
| `'detached'` | No match. |
|
|
| `'hidden'` | A hidden match, or none. |
|
|
|
|
`timeout` defaults to `config.actionTimeout`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `LOCATOR_NOT_FOUND` | The timeout expires. |
|
|
| `LOCATOR_AMBIGUOUS` | Several matches, in every state. |
|
|
| `INVALID_ARGUMENT` | Any other state, or an option key besides `state` and `timeout`; thrown before anything is resolved. |
|
|
|
|
## Match rules
|
|
|
|
Most operations require exactly one match. A read polls for its one match
|
|
until the action timeout, as an action does. Then it returns the current
|
|
value without waiting for it to change. Use [`expect`](/reference/expect) to
|
|
wait for a value.
|
|
|
|
A node the engine reports stale is re-resolved within the same timeout:
|
|
a resolve that raced a navigation, or a match the app replaced while it was
|
|
read.
|
|
|
|
| Operation | Zero matches | Multiple matches |
|
|
| --- | --- | --- |
|
|
| Actions | Poll until the timeout, then `LOCATOR_NOT_FOUND` | `LOCATOR_AMBIGUOUS` |
|
|
| Reads | Poll until the timeout, then `LOCATOR_NOT_FOUND` | `LOCATOR_AMBIGUOUS` |
|
|
| `count()`, `all()`, `allTextContents()` | `0`, `[]`, `[]` | The count, one locator per match, one text per match |
|
|
| `isVisible()`, `isHidden()` | `false`, `true` | `LOCATOR_AMBIGUOUS` |
|
|
| Assertions | Poll until the timeout, then `ASSERTION_FAILED` | `LOCATOR_AMBIGUOUS` |
|
|
| Any of these under a frame that is not in the document | As zero matches for `count()`, `all()`, `allTextContents()`, `isVisible()`, and `isHidden()`; actions and reads poll for the frame until the timeout, then `LOCATOR_NOT_FOUND`; assertions, then `ASSERTION_FAILED` | `LOCATOR_AMBIGUOUS` when several frames match |
|
|
|
|
## Types
|
|
|
|
```ts
|
|
/**
|
|
* The closed role vocabulary; an unsupported role is a type error. Every
|
|
* engine maps its platform's element types onto these names, so a role query
|
|
* reads the same against a browser and a device. A role the platform has no
|
|
* widget for matches nothing there; it is never a type error.
|
|
*/
|
|
export type Role =
|
|
| 'button'
|
|
| 'link'
|
|
| 'textbox'
|
|
| 'searchbox'
|
|
| 'combobox'
|
|
| 'listbox'
|
|
| 'option'
|
|
| 'checkbox'
|
|
| 'radio'
|
|
| 'radiogroup'
|
|
| 'switch'
|
|
| 'slider'
|
|
| 'spinbutton'
|
|
| 'progressbar'
|
|
| 'meter'
|
|
| 'image'
|
|
| 'heading'
|
|
| 'tab'
|
|
| 'tablist'
|
|
| 'tabpanel'
|
|
| 'menu'
|
|
| 'menubar'
|
|
| 'menuitem'
|
|
| 'menuitemcheckbox'
|
|
| 'menuitemradio'
|
|
| 'toolbar'
|
|
| 'tooltip'
|
|
| 'tree'
|
|
| 'treeitem'
|
|
| 'list'
|
|
| 'listitem'
|
|
| 'table'
|
|
| 'grid'
|
|
| 'row'
|
|
| 'rowgroup'
|
|
| 'rowheader'
|
|
| 'cell'
|
|
| 'gridcell'
|
|
| 'columnheader'
|
|
| 'separator'
|
|
| 'group'
|
|
| 'article'
|
|
| 'figure'
|
|
| 'form'
|
|
| 'status'
|
|
| 'alert'
|
|
| 'dialog'
|
|
| 'alertdialog'
|
|
| 'main'
|
|
| 'navigation'
|
|
| 'banner'
|
|
| 'contentinfo'
|
|
| 'complementary'
|
|
| 'region';
|
|
|
|
/**
|
|
* Spellings `getByRole` accepts beside the vocabulary and rewrites to a `Role`
|
|
* before the query is built: `img` is the ARIA name of `image`. An alias never
|
|
* reaches an engine, the replay cache, or a report; a `Role` is what they see.
|
|
*/
|
|
export type RoleAlias = 'img';
|
|
|
|
/** A string matches exactly; a RegExp uses its own source and flags. */
|
|
export type TextMatch = string | RegExp;
|
|
|
|
export interface TextMatchOptions {
|
|
/** Exact match, the default. `false` is case-insensitive substring matching; a RegExp ignores it. */
|
|
exact?: boolean;
|
|
/**
|
|
* When true, nodes the platform reports as hidden are excluded before the
|
|
* exactly-one rule is applied, so a visible node with a hidden twin (a
|
|
* prerendered copy kept after navigation, a closed drawer) still resolves.
|
|
* Omitted or false keeps every match, hidden ones included.
|
|
*/
|
|
visible?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Role query options. A role query never matches a node hidden from the
|
|
* accessibility tree, on every engine; `visible` (inherited) is the one knob
|
|
* that narrows the other query kinds, to the nodes `toBeVisible()` accepts.
|
|
*/
|
|
export interface RoleOptions extends TextMatchOptions {
|
|
/** Accessible name filter. */
|
|
name?: TextMatch;
|
|
/** Requires the checked state. */
|
|
checked?: boolean;
|
|
/** Requires the disabled state. */
|
|
disabled?: boolean;
|
|
/** Requires the selected state. */
|
|
selected?: boolean;
|
|
/** Requires the expanded state. */
|
|
expanded?: boolean;
|
|
/** Requires the pressed state of a toggle button. */
|
|
pressed?: boolean;
|
|
/** Requires a heading level, 1 through 6. */
|
|
level?: number;
|
|
}
|
|
|
|
export interface ActionOptions {
|
|
/** Deadline in milliseconds; defaults to `config.actionTimeout`. */
|
|
timeout?: number;
|
|
}
|
|
|
|
/** `longPress` options: the hold time in milliseconds, 100 through 10000, default the engine's own. */
|
|
export interface LongPressOptions extends ActionOptions {
|
|
/** Hold time in milliseconds, 100 through 10000; unset, the engine's default. */
|
|
duration?: number;
|
|
}
|
|
|
|
/** `pressSequentially` options: an optional pause between characters. */
|
|
export interface PressSequentiallyOptions extends ActionOptions {
|
|
/** Milliseconds to wait between characters; omitted types the whole text in one call. */
|
|
delay?: number;
|
|
}
|
|
|
|
export interface SwipeOptions {
|
|
/** Swipe direction. */
|
|
direction: ScrollDirection;
|
|
/** Fling strength; default `none`. The three values are defined under screen.swipe. */
|
|
momentum?: Momentum;
|
|
from?: never;
|
|
to?: never;
|
|
duration?: never;
|
|
}
|
|
|
|
/** A swipe along a path between two viewport points: a touch swipe on a device, a pointer drag on a document platform. */
|
|
export interface SwipePathOptions {
|
|
/** Where the finger goes down. */
|
|
from: Point;
|
|
/** Where it lifts. */
|
|
to: Point;
|
|
/** Gesture duration, an integer from 16 through 10000 ms; omitted = the engine's default. */
|
|
duration?: number;
|
|
direction?: never;
|
|
momentum?: never;
|
|
}
|
|
|
|
/**
|
|
* A point in CSS pixels. For `screen.tapAt`, `screen.doubleTapAt`, and `screen.swipe` the origin is
|
|
* the viewport's top-left corner, the space `boundingBox()` reports in; for
|
|
* `tap({ position })` it is the node's own top-left corner, inside its
|
|
* border on a document platform.
|
|
*/
|
|
export type Point = ViewportPoint; // { x: number; y: number }
|
|
|
|
/** `tap`, `click`, `doubleTap`, `dblclick`, and `secondaryTap` options: the action timeout and the keys held for the click. */
|
|
export interface ClickOptions extends ActionOptions {
|
|
/**
|
|
* Keys held while the pointer clicks, as a Shift-click extends a selection:
|
|
* `Shift`, `Control`, `Alt`, `Meta`, or `ControlOrMeta` (Control on Windows
|
|
* and Linux, Meta on macOS). Needs an engine that declares `tapModifiers`,
|
|
* `UNSUPPORTED_CAPABILITY` otherwise.
|
|
*/
|
|
modifiers?: readonly KeyModifier[];
|
|
}
|
|
|
|
/** A modifier key, for `modifiers` and the `press` key grammar. */
|
|
export type KeyModifier = 'Shift' | 'Control' | 'Alt' | 'Meta' | 'ControlOrMeta';
|
|
|
|
/** `tap` and `click` options. */
|
|
export interface TapOptions extends ClickOptions {
|
|
/**
|
|
* Where to tap, relative to the node's top-left corner, inside its border
|
|
* on a document platform. Without it the platform picks a point of the
|
|
* node, usually its center, behind its own actionability checks; with it
|
|
* the pointer is dispatched at that point once the node is in view and has
|
|
* a box, which needs the engine's `tap` pointer action.
|
|
*/
|
|
position?: Point;
|
|
}
|
|
|
|
/** One option of a select: its label (a bare string too), its `value` attribute, or its zero-based index. */
|
|
export type SelectOption =
|
|
| string
|
|
| { label: string; value?: never; index?: never }
|
|
| { value: string; label?: never; index?: never }
|
|
| { index: number; label?: never; value?: never };
|
|
|
|
/** A swipe or scroll direction. */
|
|
export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
|
|
|
|
/** Fling strength of a swipe; defined under screen.swipe. */
|
|
export type Momentum = 'none' | 'slow' | 'fast';
|
|
```
|
|
|
|
## Related
|
|
|
|
[`expect`](/reference/expect) waits for a locator's state. The
|
|
[`browser`](/reference/web) fixture adds CSS locators and frames.
|