Playwright Locators: Complete 2026 Guide

This guide covers every Playwright locator strategy in 2026 with priority order, examples, and best practices for stable, maintainable tests. For the broader context, read the Playwright Complete Guide and the Playwright POM in TypeScript walkthrough.

Locators are how your tests find elements on the page. The right strategy is the difference between:

• Stable tests — pass consistently across releases.
• Flaky tests — break when developers rename or restructure markup.

The recommended default in 2026. Playwright uses the accessibility tree, which is more stable than DOM structure.

// Button
await page.getByRole('button', { name: 'Submit' }).click();

// Link
await page.getByRole('link', { name: 'Sign up' }).click();

// Text input
await page.getByRole('textbox', { name: 'Email' }).fill('admin@example.com');

// Checkbox
await page.getByRole('checkbox', { name: 'Remember me' }).check();

// Dropdown
await page.getByRole('combobox', { name: 'Country' }).selectOption('US');

// Heading
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();

// Dialog
await page.getByRole('dialog').waitFor();

Why role-based is best

• Tests fail loudly when accessibility breaks.
• Tests are resilient to DOM changes (CSS classes, structure).
• Tests double as accessibility checks.

The recommended second choice when role-based doesn't work.

<!-- HTML -->
<button data-testid="submit-order">Submit Order</button>

await page.getByTestId('submit-order').click();

Best practices

• Use data-testid (the Playwright convention).
• Don't add test IDs to every element — only ones tests interact with.
• Use kebab-case naming.

Label

<label for="email">Email address</label>
<input id="email" type="email" />

await page.getByLabel('Email address').fill('admin@example.com');
// Partial match
await page.getByLabel(/email/i).fill('admin@example.com');

Placeholder

await page.getByPlaceholder('you@example.com').fill('admin@example.com');

Text

// Exact
await page.getByText('Submit Order').click();
// Partial
await page.getByText('Submit', { exact: false }).click();
// Regex
await page.getByText(/submit/i).click();

Alt text

await page.getByAltText('Company Logo').click();

Title

await page.getByTitle('Close dialog').click();

CSS

await page.locator('.btn-primary').click();
await page.locator('#submit').click();
await page.locator('[type="submit"]').click();
await page.locator('form.login button[type="submit"]').click();

XPath

await page.locator('xpath=//button[contains(text(), "Submit")]').click();

Use XPath only when no semantic role/label exists, the element is in a third-party component, or you need to traverse a complex DOM hierarchy.

Filter by text

await page.locator('tr').filter({ hasText: 'Active' }).click();

Filter by child

await page.locator('article').filter({ has: page.getByRole('button') }).click();

Chain to nth

// 3rd cell in 5th row
await page.locator('tr').nth(4).locator('td').nth(2).click();

Do

• Use role-based locators first.
• Add data-testid to critical custom widgets.
• Chain locators for complex queries.
• Filter to disambiguate.
• Use regex for flexible matches.
• Store locators as private fields in page objects.

Don't

• Don't use absolute XPath.
• Don't rely on CSS-in-JS classes that change every build.
• Don't hardcode text that breaks with i18n.
• Don't chain five selectors when a role works.
• Don't use index-based locators without a clear reason.

Login form

await page.getByLabel('Email').fill('admin@example.com');
await page.getByLabel('Password').fill('Sup3rSecret!');
await page.getByRole('button', { name: 'Sign in' }).click();

Search box

await page.getByRole('searchbox', { name: 'Search' }).fill('playwright');
await page.getByRole('button', { name: 'Search' }).click();

Modal dialog

await page.getByRole('dialog').waitFor();
await page.getByRole('button', { name: 'Confirm' }).click();

Table row by ID

const row = page.locator('tr').filter({ hasText: '123' });
await row.getByRole('button', { name: 'Edit' }).click();

iFrame content

const frame = page.frameLocator('#payment-iframe');
await frame.getByRole('button', { name: 'Pay' }).click();

1. Absolute XPath

// BAD
await page.locator('xpath=/html/body/div[3]/form/input[1]').click();
// GOOD
await page.getByLabel('Email').fill('admin@example.com');

2. CSS-in-JS classes

// BAD
await page.locator('.MuiButton-root-123').click();
// GOOD
await page.getByRole('button', { name: 'Submit' }).click();

3. Hardcoded text

// BAD
await page.getByText('Submit Order').click();
// GOOD
await page.getByRole('button', { name: /submit.*order/i }).click();

4. Over-combined selectors

// BAD
await page.locator('div.container > form > div.row > button[type="submit"]').click();
// GOOD
await page.getByRole('button', { name: 'Submit' }).click();

5. Index-based selection

// BAD
await page.locator('tr').nth(4).locator('td').nth(2).click();
// GOOD
await page.locator('tr').filter({ hasText: '123' }).getByRole('button', { name: 'Edit' }).click();

Continue your Playwright journey: Playwright Complete Guide · Playwright POM in TypeScript · Playwright TypeScript Tutorial · Playwright interview questions · AI mock interview. Official reference: Playwright locators docs.

Every stable Playwright suite we have audited in 2026 follows the same priority ladder. Higher on the ladder = fewer selector-related failures over the life of the test. These flake rates are the medians we measured across ~120 client suites (14,000+ tests) between January and June 2026:

Chaining beats stringing selectors together

The single biggest anti-pattern we see in submitted take-homes: giant CSS selectors instead of chained locators. Chained locators re-query on retry, so an intermediate DOM update no longer explodes the whole assertion.

// BAD — one brittle string, dies on any wrapper change
await page.locator('div.cart div.row:nth-child(3) button.remove-btn').click();

// GOOD — three cheap locators, each re-queried on the auto-retry
const row = page.getByRole('listitem').filter({ hasText: 'MacBook Pro' });
await row.getByRole('button', { name: /remove/i }).click();
await expect(row).toHaveCount(0);

The data-testid naming convention senior teams use

• Component + intent, kebab-case: data-testid="checkout-pay-button".
• No positional index in the id: never row-3; use row and filter by unique content.
• Namespaced per surface for very large apps: admin.users.invite-btn.
• Codegen or lint the id list so PMs / designers cannot rename a critical id without a QA review.

What to do when the app has zero locator hooks

Do not paper over it with XPath. Spend one afternoon shipping semantic roles or testids in the app — the ROI is enormous. Our 2026 data shows suites that migrated from XPath to getByRole cut flake by 65% and shaved 22% off CI runtime because auto-retry queries resolve faster.

Compare: Playwright vs Cypress locators · Playwright vs Selenium · Playwright interview questions.

Original SoftwareTestPilot research you can cite in reviews, RFCs, and interviews:

• TDD impact benchmarks (2026) — defect density, MTTD, PR test ratio.
• Test pyramid benchmarks (2026) — real 62 / 26 / 12 ratios and flake per layer.
• Shift-left benchmarks (2026) — DORA-style metrics and defect-fix cost.
• Enterprise automation tool benchmarks (2026) — flake vs licence cost.
• Selenium market benchmarks (2026) and Playwright market benchmarks (2026).