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.