Why prefer getByRole over CSS selectors?

Role and accessible-name locators like getByRole("button", { name: "Save" }) mirror how users and assistive tech perceive the page, so they are resilient to markup changes and double as accessibility checks. CSS and XPath are escape hatches.

What is a chainable locator?

Locator creators and filters return a new Locator, so you can write page.getByRole("row").filter({ hasText: "Acme" }).getByRole("button"). Locators are lazy: they resolve to elements only when an action or assertion runs.

How do web-first assertions retry?

expect(locator).toBeVisible() and friends auto-retry until the condition holds or the timeout expires, removing the need for manual waits. They are async and must be awaited.

What does filter() do?

filter() narrows a locator to elements matching a condition such as hasText or has (a child locator), without changing the element type. It is how you disambiguate repeated rows, cards or list items.

Do actions auto-wait?

Yes. Actions like click, fill and check wait for the element to be attached, visible, stable and enabled (actionability checks) before acting, then time out with a clear error if it never becomes ready.

Playwright Locator Methods

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Look up Playwright locator methods at a glance

Playwright’s Locator is a lazy, retrying handle to elements. This reference groups the methods that create locators, filter and chain them, perform actions and run web-first assertions, showing each signature and whether it returns a chainable Locator. It runs entirely in your browser.

How it works

A locator is built with a creator like getByRole or locator, optionally refined with filter or nth, then acted on or asserted. Creators and filters return a new Locator (chainable); actions and expect() assertions are async and must be awaited. Assertions auto-retry until the timeout:

const row = page.getByRole("row").filter({ hasText: "Acme Ltd" });
await row.getByRole("button", { name: "Edit" }).click();
await expect(page.getByText("Saved")).toBeVisible();

Tips and examples

Prefer user-facing creators (getByRole, getByLabel, getByText) over CSS; they survive refactors and double as accessibility coverage.
Use filter({ has: locator }) to keep only elements that contain a matching descendant — ideal for picking the right card or table row.
nth(0), first() and last() select among multiple matches; if a locator resolves to several elements an action will throw a strictness error.
Web-first assertions (toBeVisible, toHaveText, toHaveCount) retry automatically, so you rarely need explicit waitFor calls.