Locators and Auto-Waiting

locator.fill() focuses the field, selects any existing text and replaces it in one insertion, firing a single input event. locator.pressSequentially() sends keydown, keypress, input and keyup per character and does not clear the field first.

locator.press focuses the matched element, holds Control, presses and releases Enter, then releases Control. The argument is one logical key name or a single character, with modifiers joined by plus signs.

Playwright retries a set of actionability checks until they all pass or the call times out: the element must be visible, stable in position, able to receive pointer events at the click point, and enabled.

A new locator matching the same kind of elements, minus the ones whose subtree lacks that text. The original locator is untouched, the match stays on the outer elements, and a string is matched case-insensitively as a substring.

Call page.frameLocator with a selector for the iframe, then chain the element locator onto it. Everything after the frame locator resolves inside that iframe, and locators built from page are unaffected, so there is nothing to switch back.

A Playwright Locator stores a recipe for finding an element and re-runs it on every use. An ElementHandle points at one DOM node captured once, so it breaks when the page re-renders that node.

page.goto() resolves when the load event fires on the new document. The waitUntil option moves that gate to domcontentloaded, commit, or the discouraged networkidle, and the call returns the main resource response.

page.getByRole('heading', { name: 'Issue 42' }) matches an element whose ARIA role is heading, implicit for h1 to h6 or set by a role attribute, and whose computed accessible name contains the text Issue 42.

Playwright reads an unprefixed string as XPath when it starts with // or .. , as a text selector when the whole string is quoted, and as CSS otherwise. Write css= or xpath= to remove the guess.

Playwright locators are strict: any call that targets a single DOM element throws a strict mode violation when the locator matches more than one. The error names the locator, the match count, and the candidates it found.

By default page.getByText matches a case-insensitive substring of an element's whitespace-normalized text, so Open also matches Reopened. With exact set to true the whole string must match, case-sensitively. Whitespace is normalized either way.

Playwright dismisses it automatically, so confirm() returns false and the click that opened it completes. Registering a dialog listener turns that off: your handler must then accept or dismiss, or the page freezes.

A plain string matches an option by its value or its label. An object narrows by value, label or index, and every property you state must match. An array selects several options in a multiple select.

They reshape one synthetic mouse gesture: which button is pressed, which modifier keys are held, where inside the element's padding box the pointer lands, how many clicks are sent, and the pause between mousedown and mouseup.

Use filter with has when the element you act on is the container and the inner locator is only a test. Chain locator.locator when the target is the descendant itself. Either way the inner locator is relative to the outer match.

The name option is a case-insensitive substring test against the accessible name by default, so any name containing Save matches. Pass exact: true for a case-sensitive whole-string match, or a RegExp for full control.

Strictness applies only to calls that need one target element. A click must choose a single element, so two matches is ambiguous and throws. Counting is defined over the whole matched set, so two is simply the answer it returns.

Because a test id match is always exact. page.getByTestId compares the whole attribute value case-sensitively, so there is nothing for an option to relax. It reads data-testid unless the testIdAttribute option names another attribute.

dragTo moves to the source, presses, moves to the target and releases. A board built on HTML5 drag and drop needs at least two mouse moves before dragover fires, so rebuild the gesture and hover the target twice.

Read the call log printed under the error. It replays the attempt in order and stops at the condition that never held - element is not visible, not stable, not enabled, or a named node that intercepts pointer events.

Playwright streams a download into a temporary location owned by the browser context and deletes it when that context closes. saveAs copies the bytes to a path you control; without it the file is gone once the test ends.

setChecked reads the control's current state first, clicks only if it differs, and then verifies the new state. A plain click toggles blindly, so an already-checked box ends up unchecked and an intercepted click passes silently.

locator.click drives a real pointer to the element and sends mousedown and mouseup. dispatchEvent builds a synthetic event in the page and fires it straight at the node, whatever its visibility, with no pointer, no coordinates and isTrusted false.

Different actions require different checks. Filling waits only for visible, enabled and editable, then sets the value directly. Clicking additionally requires stability and a hit test at the click point, which the overlay fails.

and() is an intersection: one element must satisfy both locators. or() is a union: an element matching either one qualifies. Use and() to pin down a single element by two properties, and or() to wait for whichever of two outcomes appears.

They convert between the two views of an iframe. locator.contentFrame() turns a Locator for the iframe element into a FrameLocator for the document inside it, and frameLocator.owner() turns a FrameLocator back into a Locator for the iframe element.

It waits for the locator to resolve to exactly one attached element and returns a handle to that DOM node. It waits for attachment only, not visibility, and throws when several elements match or when the timeout expires.

Both query once and return handles to whatever exists at that instant: page.$() resolves to null when nothing matches and page.$$() to an empty array, with no waiting. Locators re-resolve and auto-wait instead, so these two calls reintroduce flakiness.

networkidle resolves only after 500 ms with no network connections, which is a proxy for readiness that a polling or streaming app never satisfies. Playwright marks it discouraged and tells you to assert on the rendered result instead.