Locators and Auto-Waiting

Use locator.waitFor() when an element must reach a state but there is nothing to assert - a precondition, or before a raw read. Where the test would assert, a retrying matcher is better: it reports the actual value.

Only on roles that support the state. Playwright reads the value from an aria attribute or the native control and rejects an unsupported pairing, such as pressed on anything but button, with an error naming the allowed roles.

The :has() pseudo-class takes a selector and keeps elements that contain a match for it. The :has-text() pseudo-class takes a string and keeps elements whose subtree contains that text, matched case-insensitively as a trimmed substring.

Call locator.visible(), added in Playwright 1.63, which returns a locator matching only the visible elements. The older :visible CSS pseudo-class does the same inside a selector string. Visible means a non-empty bounding box and no visibility:hidden.

Only the innermost element whose own text matches. Playwright drops any element that has a child element also matching, so the card and its wrapper are excluded and the span holding the title is returned.

Wait for the page's filechooser event. Start waiting before clicking the control, then call setFiles on the FileChooser Playwright hands you; this works even when script creates the input and discards it.

fill inserts the whole string in one step and dispatches only an input event, never keydown or keyup. A menu that opens on key handlers therefore never sees a trigger. Type the trigger characters with pressSequentially instead.

Forcing hides the failed check, not its cause. Playwright skips the actionability checks but still dispatches a real event at the computed point, so an overlay that owned that point still receives the click.

It returns one locator per currently matching element and waits for nothing. The array length is a snapshot, so a list still loading yields too few entries, and each entry is positional, so removing elements mid-loop shifts what the rest point at.

Read the set back first to see what the extras are, then exclude them by the property that really distinguishes them: visible true for unrendered nodes, hasNotText or hasNot for content, or a tighter starting locator for ancestors.

A Frame object is a reference to one live frame. When the issue view removes and re-creates the iframe, that frame is detached and every call through it fails. A frame locator re-resolves its selector on each use instead.

That error comes from acting through an ElementHandle whose node was replaced. Find where the handle is created and stored, usually a page-object field or a hook, and replace it with a locator that re-resolves on every action.

Because it inspects whichever document is current when the call runs. If the click has not committed a navigation yet, or never will because the app routes client-side, the old document already satisfies the state and it returns instantly.

Most often the element is hidden for accessibility purposes. Role queries skip anything with aria-hidden, display none, visibility hidden or the hidden attribute, on itself or an ancestor, unless includeHidden is true.

A div exposes no ARIA role, so no role query can select it. Playwright derives roles from an explicit role attribute or an implicit tag mapping, and div, span and an anchor without href have none.

The button sits inside an open shadow root. Playwright's CSS engine pierces open shadow roots, so css= reaches it; the XPath engine does not cross a shadow boundary, so xpath= only ever finds the host element.

Read the candidate list in the error: it prints both matched nodes and a generated locator for each, which identifies the new duplicate. Then decide whether the page changed, or a hidden copy was always there and only now matches.

Use first, last or nth when position genuinely is the requirement, such as the newest comment in a thread. Using them to silence an ambiguity you have not explained leaves a test that passes while acting on the wrong element.

Pass a RegExp instead of a string: page.getByText with a pattern such as one matching digits followed by the word comments. The exact option is ignored for a RegExp, and the pattern is case-sensitive unless you add the i flag.

Because page.getByLabel searches controls, not label elements. It matches an element through aria-labelledby, aria-label, or a real HTML label association on a form control. A styled div next to a label element has none of those, so nothing matches.

Handle them per test. A blanket accept-everything handler hides the dialogs a test should be asserting on, and turns a real regression -- a confirmation that stops appearing, or one that names the wrong issue -- into a silent pass.

Treat the raw devices as a documented exception. page.mouse takes viewport coordinates and page.keyboard goes wherever focus already is, so neither re-resolves an element. Reserve them for gestures with no element to name.

A trial run performs the actionability checks and then stops. Playwright waits for the element to be visible, stable, hit-testable and enabled, and never dispatches the click, so it verifies readiness without changing the page.

It starts the search in any frame of the subtree, main frame or iframe alike, so a test need not locate the iframe first. The rest of the chain still resolves in one frame; multi-frame matches error.

Use locator.evaluate() for one element: it resolves the locator, runs your function with that element and disposes the handle for you. Pass handles into page.evaluate() only when one function needs several live objects at once.

The >> token chains selector parts: each part is queried relative to the previous part's result, like nested querySelector calls. Prefixing a part with an asterisk captures that intermediate element instead of the last one.

Replace the blanket rule with a criterion. Typing costs one round trip per character and adds a re-render window between each, so reserve it for fields whose own behaviour depends on key events and use fill everywhere else.

Rank the signals by how directly they express what the test needs. Assertions on rendered content first, page.waitForURL for routing, locator.waitFor for preconditions, page.waitForFunction as a documented last resort, and networkidle nowhere at all.

Rarely. A custom engine earns its place only when a whole class of elements shares an addressing scheme the built-in engines cannot express and the application guarantees. Otherwise it adds a private query language every test author must learn.