What Are Locators in Playwright?
A Playwright locator is not a reference to a specific DOM node captured at the moment you write the code — it is a lazy, chainable description of how to find an element, re-resolved against the live page every single time you call an action or assertion on it. This is fundamentally different from older Selenium-style WebElement handles, which snapshot a node once and go stale the instant the DOM changes underneath them. Because locators auto-wait and re-query, a test written with page.locator(...) survives re-renders, animations, and asynchronous updates far better than code built around cached element references.
Cricket analogy: A Playwright locator is like a fielding captain repositioning fielders before every ball rather than fixing them once at the toss — when you call locator.click(), Playwright re-scans the DOM at that instant, the way Rohit Sharma resets his slip cordon based on the bowler and batter each over.
getByRole: The Recommended First Choice
page.getByRole('button', { name: 'Submit' }) locates an element by its accessible role and accessible name, the same information a screen reader would use. Because this reflects semantic meaning rather than DOM structure, getByRole locators keep working through CSS refactors, class renames, and markup restructuring as long as the element's role and label stay the same. Playwright's own documentation recommends getByRole as the default locator for most interactive elements — buttons, links, checkboxes, textboxes, and headings all expose ARIA roles that make role-based targeting both resilient and self-documenting.
Cricket analogy: getByRole('button', {name: 'Submit'}) targets an element by its functional role, much like a scorer logs 'the number 4 batter' rather than 'the player wearing shirt number 18' — the role stays meaningful even if Virat Kohli's shirt number or jersey design changes.
// Role-based locators mirror the accessibility tree
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
await page.getByRole('checkbox', { name: 'Accept terms' }).check();
await expect(page.getByRole('heading', { name: 'Welcome', level: 1 })).toBeVisible();getByText and Other Built-in Locators
getByText('Man of the Match') matches an element by its rendered visible text, using either an exact match or a substring match depending on whether you pass exact: true. It is well suited to non-interactive content like headings, status messages, or labels, but because it matches literal wording, any copy change in the UI breaks the test. Playwright also ships getByLabel() for form fields associated with a <label>, getByPlaceholder() for inputs identified by their placeholder text, and getByTestId() for elements tagged with a stable data-testid attribute when no reliable role or text exists.
Cricket analogy: getByText('Man of the Match') simply matches whatever text is rendered on the scoreboard, similar to a commentator reading out the award title verbatim rather than inferring it from context — but use exact: true when text like 'India 250' could also partially match 'India 250/3'.
When no accessible role or reliable text exists — for example, a decorative icon-only button — fall back to getByTestId('save-icon') with a stable data-testid attribute, and prefer exact: true whenever your target text could be a substring of another element's text.
CSS and XPath Locators — When and Why to Avoid Them
page.locator('css=.btn-primary') or the shorthand page.locator('.btn-primary'), along with page.locator('xpath=//div[3]/button'), locate elements through raw DOM structure or CSS class names. These are the most brittle locator strategies available because they couple your test to implementation details — a class rename during a styling refactor, or a new sibling element inserted above your target, silently breaks the test even though the feature itself still works correctly for real users. Playwright's official guidance treats CSS and XPath as a last resort, to be used only when getByRole, getByText, getByLabel, and getByTestId genuinely cannot express what you need, and even then it's often better to combine a role-based locator with .filter() than to write structural CSS.
Cricket analogy: Relying on a CSS class like .css-x7f3a2 to find the 'Submit' button is like identifying a bowler purely by which end of the pitch they're bowling from this over — that assignment changes every over, just as auto-generated class names change on every deploy, breaking the locator.
Avoid locators tied to auto-generated, hashed CSS classes produced by CSS-in-JS libraries (e.g. .sc-bdVaJa or .css-1a2b3c). These strings regenerate on nearly every build, so a test suite anchored to them becomes flaky or fails on every deploy, regardless of whether the underlying feature actually changed.
- Locators are lazy and re-query the DOM on every action, unlike stale ElementHandle references.
- getByRole is the recommended default — it targets accessible role and name, mirroring assistive technology.
- getByText matches visible text content and supports exact or substring matching.
- getByLabel, getByPlaceholder, and getByTestId cover cases where role or text alone isn't specific enough.
- CSS and XPath locators are brittle because they depend on DOM structure and class names.
- Avoid locators tied to auto-generated, hashed CSS class names — they change on nearly every deploy.
- Prefer combining a role-based locator with .filter() over writing structural CSS selectors.
Practice what you learned
1. Why does Playwright recommend getByRole() as the default locator strategy?
2. What is the key difference between a Playwright locator and an older Selenium-style ElementHandle?
3. Which locator strategy is most likely to break after a purely cosmetic CSS refactor?
4. When should you reach for getByTestId()?
Was this page helpful?
You May Also Like
Auto-Waiting and Actionability Checks
Understand how Playwright automatically waits for elements to become actionable before interacting with them, eliminating most manual sleeps and flaky waits.
Interacting with Forms and Inputs
Master Playwright's methods for filling text inputs, selecting options, checking boxes, and uploading files in real-world forms.
Assertions with expect()
Learn Playwright's web-first assertions — how expect(locator) auto-retries until conditions are met, and how that differs from generic value assertions.