What are selectors in Playwright?
A selector is the description Playwright uses to find an element on the page: "the button called Enrol", "the input labelled Email", "the element with data-testid="cart-count"". In modern Playwright you rarely write raw selector strings. You build a locator with methods such as page.getByRole(), and the locator finds the element fresh every time you use it, waiting for it to appear.
The built-in locators, in order of preference
The Playwright docs recommend locators that match what a user sees, because they survive markup changes better than class names do.
| Locator | Finds | Example |
|---|---|---|
getByRole | Elements by ARIA role and accessible name | getByRole('button', { name: 'Enrol' }) |
getByLabel | Form fields by their label | getByLabel('Email') |
getByPlaceholder | Inputs by placeholder text | getByPlaceholder('you@example.com') |
getByText | Non-interactive text | getByText('Order placed') |
getByAltText | Images by alt text | getByAltText('Uncodemy logo') |
getByTitle | Elements by title attribute | getByTitle('Close') |
getByTestId | Elements by data-testid | getByTestId('cart-count') |
When none of these fit, page.locator() accepts CSS ('li.card') or XPath ('xpath=//li[@class="card"]'; a string starting with // is also treated as XPath).
Example: a course listing page
// tests/enrol.spec.ts
import { test, expect } from '@playwright/test';
test('enquire about the Data Science course', async ({ page }) => {
await page.goto('/courses');
// narrow down: the list item that mentions Data Science, then its button
const card = page.getByRole('listitem').filter({ hasText: 'Data Science' });
await card.getByRole('button', { name: 'Details' }).click();
await page.getByLabel('Email').fill('student@example.com');
await page.getByRole('button', { name: 'Send enquiry' }).click();
await expect(page.getByText('We will contact you')).toBeVisible();
});
Chaining (card.getByRole(...)) searches inside the first locator. filter({ hasText }) and filter({ has: otherLocator }) pick the right item from a list without relying on its position. Use .first(), .last() or .nth(i) only when position really is the thing you are testing.
Strict mode
Actions such as click() and fill() expect the locator to match exactly one element. If two buttons are both named "Enrol", the click fails at once with an error that starts:
locator.click: Error: strict mode violation: getByRole('button', { name: 'Enrol' }) resolved to 2 elements
The error lists both elements and suggests a more precise locator. This is deliberate: clicking "whichever one comes first" hides real bugs. Narrow the locator by chaining or filtering instead.
Shadow DOM and iframes
- CSS and the
getBy*locators reach into open shadow roots automatically. XPath does not. See how Playwright handles shadow DOM. - Elements inside an iframe need
page.frameLocator('#payment')(orlocator.contentFrame()) first. See Playwright's approach to iframes.
Tips
- If your team uses a different attribute than
data-testid, settestIdAttributein the config. - Avoid long CSS chains such as
div > div:nth-child(3) > span. They break with any layout change. - Run
npx playwright codegenor use the "Pick locator" button in the inspector to see which locator Playwright itself would choose. See recording tests in Playwright. - Locators wait automatically before acting, so you seldom need waitForSelector() any more.
Want to master Playwright hands-on?
Join Uncodemy's Playwright Automation Testing Course in Noida — Dedicated Placement Support.
Explore the Course →