Playwright Locator Methods

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();

Method groups in this reference

Common patterns and when to use them

Selecting by accessible role is the first choice because it ties your test to what users and screen readers see, not to CSS class names that change with every refactor:

await page.getByRole("button", { name: "Submit" }).click();
await page.getByRole("textbox", { name: "Email" }).fill("[email protected]");

Chaining filter to a parent lets you pick the correct repeated element in a list or table without fragile :nth-child selectors:

const row = page.getByRole("row").filter({ hasText: "Invoice #42" });
await row.getByRole("button", { name: "Download" }).click();

Checking element count before interacting catches dynamic pages where a list may still be loading:

await expect(page.getByRole("listitem")).toHaveCount(5);

Handling multiple matches — if getByRole("button") returns several buttons and you act on it without narrowing, Playwright throws a strict-mode error. Use .first(), .nth(index), or a tighter filter to be explicit.

Actionability checks

Before running any action, Playwright waits for the locator to be:

• Attached to the DOM
• Visible (not hidden by CSS)
• Stable (not animating)
• Enabled (not disabled or read-only for input-type actions)

If these conditions are not met within the timeout (default 30 s), Playwright throws a clear timeout error with the locator expression, so diagnosing flaky tests is straightforward.

Tips

• 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.
• Web-first assertions (toBeVisible, toHaveText, toHaveCount) retry automatically, so you rarely need explicit waitFor calls.
• Set timeout on individual assertions when one step legitimately takes longer than others, rather than raising the global default.