mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-21 03:05:26 +08:00
* feat(mcp): attach to a test held at screen.pause() or --step
A test held at `screen.pause()` or at an `e2e run --step` hold now prints
an ID, such as `Paused (p1) in pays with a card [web]:`. You can pass it to
`open_session {attach: "p1"}` in `e2e mcp` to look at the held test's app
and act on it.
The tools run in the worker, on the engine session the held attempt already
has. Requests go from the MCP server to the runner over the directory's
step socket, and the runner relays them to the worker. Replies are redacted
with the attempt's secret ledger before they're sent.
- `close_session` detaches and leaves the test held.
- When the test resumes, the session ends right away and a call still in
progress is cancelled.
- Attached calls aren't recorded as steps in the report or the trace.
- `run_code`, the recording tools, and `type_secret` aren't available in an
attached session.
- `e2e run --step` in a terminal now listens on the step socket like a pause
does, so you can attach at its holds.
With several workers paused, each prompt is now drawn from the hold it
names. Before, it could show one test's title next to another test's screen.
* fix(mcp): print output a tool's timer writes after its attached call ends
Output is muted only while the attached call is running. The call scope
lives in its own module, so process-output.ts doesn't load the attach tools.
* feat(mcp): record in an attached session when the run doesn't record
start_recording and stop_recording join the attached catalog, which now
lists exactly the normal session's tools. If the run already records the
test, start_recording fails with the run's video directory. A recording
still running when the session ends is saved.
The docs no longer describe what a pause ID looks like. The examples and
sample output show one.
* fix(mcp): don't hold a resumed test while an attached recording saves
On a resume or an interrupt the worker sends the stop for the agent's
recording and lets the test continue. The file finishes in the background
and its path goes to the log. Teardown waits for a save still in progress
for at most cleanupTimeout.
A project tool's attachScreenshot works in an attached session and stays
out of the test's report. In the live list a long title ends in an
ellipsis, so the pause ID stays visible.
1444 lines
48 KiB
Plaintext
1444 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.
|
|
Use the pause ID to [attach over MCP](/reference/mcp#attaching-to-a-held-test).
|
|
|
|
```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_UNAVAILABLE` 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_UNAVAILABLE` | `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.
|