Mastering Playwright Locators: The Complete Guide

The Importance of Selector Strategies

A selector is a query that identifies an element on a web page. If your selectors are too strict or rely on fragile DOM structures, your tests will break whenever the page layout is redesigned. Playwright resolves this by recommending user-centric locators that represent how users interact with the page, rather than implementation-specific HTML details.

Playwright's Core Locator Methods

Here are the recommended user-facing locator methods, ranked by priority:

1. page.getByRole()

This is the gold standard of locator strategies. It targets elements in the accessibility tree, ensuring your application is accessible while keeping tests resilient.

// Targets <button id="submit">Submit Form</button>
await page.getByRole('button', { name: 'Submit Form' }).click();

// Targets <input type="checkbox">
await page.getByRole('checkbox', { name: 'Accept Terms' }).check();

2. page.getByText()

Finds elements containing specific text strings. Excellent for non-interactive elements like paragraph messages, alerts, and descriptive labels.

await expect(page.getByText('Registration Successful!')).toBeVisible();

3. page.getByPlaceholder()

Targets input fields by their placeholder text values. Highly readable and user-centric.

await page.getByPlaceholder('Enter your email address').fill('[email protected]');

Chaining and Filtering Locators

Often, a button or input resides inside a list or specific layout wrapper. Playwright allows chaining locators together or filtering them to ensure uniqueness:

// Target a specific row in a data table, then target a button within that row
const row = page.locator('tr').filter({ hasText: 'Alice Cooper' });
await row.getByRole('button', { name: 'Delete' }).click();

Conclusion

Writing stable tests starts with choosing the right locators. By prioritizing getByRole and chaining filters, you ensure your test suites are accessible, highly readable, and resistant to DOM structure modifications. Test your locator skills in our interactive Locator Lab Engine!