Selectors — Finding Elements

Locators: Finding Elements

What is a locator?

Before you can click, fill, or assert, you need to locate the element. Playwright calls this a locator — a lazy, retryable handle to an element.

// Lazy: does not query the DOM yet
const signInBtn = page.getByRole('button', { name: 'Sign in' });

// Interacts when called -- Playwright auto-waits + retries
await signInBtn.click();

Locators are your primary API. Below are the 5 strategies, in priority order.

getByRole1st choice

Accessible + resilient

getByText2nd

Visible text content

getByLabel3rd

Form fields with labels

getByTestId4th

Escape hatch

CSS / XPath5th

Last resort, brittle

getByRole:Accessible + resilient
getByText:Visible text content
getByLabel:Form fields with labels
getByTestId:Escape hatch
CSS / XPath:Last resort, brittle

Start at the top. Only drop down when the strategy above doesn't work.

The 5 Selector Strategies

1. getByRole — the default

Finds by ARIA role + accessible name. Mirrors how screen readers see the page.

await page.getByRole('button', { name: 'Submit Order' }).click();
await expect(page.getByRole('heading', { name: 'Welcome Back' })).toBeVisible();
await page.getByRole('link', { name: 'About Us' }).click();
await page.getByRole('checkbox', { name: 'Remember me' }).check();

Common roles: button, link, heading, textbox, checkbox, radio, dialog, navigation.

2. getByText — messages and static text

Finds by visible text content. Best for paragraphs, labels, and error messages.

await expect(page.getByText('Your order has been placed.')).toBeVisible();
await expect(page.getByText(/order has been/)).toBeVisible();
await expect(page.getByText('Invalid email address')).toBeVisible();

Watch out for duplicates — narrow with .first(), .nth(n), or .filter().

3. getByLabel — form fields

Finds form controls by their associated <label> text. Ideal for inputs, selects, textareas.

// <label for="email">Email Address</label>
await page.getByLabel('Email Address').fill('user@example.com');
await page.getByLabel('Password').fill('s3cureP@ss');

Prefer this over getByRole('textbox') when the label makes each field unique.

4. getByTestId — the escape hatch

Finds by data-testid. Use only when no semantic selector works — no role, no text, no label.

await page.getByTestId('user-avatar').click();
await expect(page.getByTestId('cart-item-42')).toBeVisible();

Test IDs are invisible to users/AT — they’re a testing-only contract. Always exhaust the 3 semantic options first.

5. CSS / XPath — last resort

Raw CSS and XPath work but couple tests to implementation details.

await page.locator('.btn-primary.submit-btn').click();      // fragile
await page.locator('//div[@class="header"]//button[1]').click(); // worse

A class rename breaks them. Prefer everything above.

Quick Check

Question 1 of 10 correct

Which selector should you reach for FIRST for a '<button>Submit</button>'?

Why getByRole Wins

Avoid CSS/XPath as First Choice

Selector Priority Summary

Priority	Strategy	Best For	Resilience
1st	`getByRole`	Buttons, links, headings, form elements	Highest — tests accessibility
2nd	`getByText`	Messages, labels, static text	High — text rarely changes
3rd	`getByLabel`	Form fields with labels	High — labels are user-visible
4th	`getByTestId`	Elements with no semantic hook	Medium — stable but not semantic
5th	CSS / XPath	Legacy code, complex DOM queries	Low — breaks on refactors

Practice: Match HTML to the Best Selector

Match each HTML snippet on the left with the best Playwright selector on the right.

Practice: Fill In the Selectors

Fill in the correct Playwright locator method for each interaction.

import { test, expect } from '@playwright/test';

test('user can log in', async ({ page }) => {
await page.goto('https://app.example.com/login');

// Fill the "Email" input field (has a <label>Email</label>)
await page.('Email').fill('user@test.com');

// Fill the "Password" input field (has a <label>Password</label>)
await page.('Password').fill('secret123');

// Click the "Sign In" button
await page.('button', { name: 'Sign In' }).click();

// Verify the welcome heading appears
await expect(
  page.('heading', { name: 'Welcome' })
).toBeVisible();
});

Try It: Log In with Selectors

Knowledge Check

Question 1 of 30 correct