Practical QA guide · 10 min
Playwright Locators: Best Practices and Examples
Choose reliable Playwright locators with practical guidance for getByRole, labels, text, test IDs, CSS selectors, strictness, and accessibility-aware automation.
Written and reviewed by ShiftQA Labs QA Education Team · Updated October 6, 2026
Browse Lessons modules
Use semantics before DOM structure
A role-and-name locator expresses the user-facing contract. If a button moves into a different wrapper or CSS class changes, the test can still pass as long as the button remains the same accessible control.
This makes locator quality partly a product-quality signal. Ambiguous or unnamed controls are harder for both assistive technology and maintainable automation.
Know when test IDs are appropriate
A dedicated test ID can be the right contract for elements whose user-facing text changes frequently, is localized, or is not unique. Keep IDs stable and meaningful rather than encoding layout or implementation details.
Do not use test IDs to avoid fixing basic accessibility problems. A primary button that users cannot distinguish by name should usually get an accessible name even if automation also uses a test ID.
Treat strictness failures as feedback
Playwright locators are strict when an action expects one element. If a locator matches multiple elements, refine the product-facing condition rather than immediately reaching for nth(0). Positional selectors often hide ambiguity.
Scope to a meaningful region, row, card, dialog, or label first. Use positional selection only when position itself is part of the tested requirement.
Worked example
Locating an Add to cart button inside one product card
A catalogue contains many cards, each with an Add to cart button.
- 1Locate the card using the visible product name or a stable product identifier.
- 2Scope the next locator to that card.
- 3Within the card, locate the button by role and accessible name Add to cart.
- 4Assert the button is visible and enabled before clicking.
- 5Avoid page.getByRole('button', { name: 'Add to cart' }).first() unless the first position is itself a requirement.
Frequently asked questions
Questions testers ask
Is getByRole always the best locator?
It is often a strong first choice for interactive UI because it mirrors accessibility semantics, but labels, text, placeholders, or test IDs can be more appropriate depending on the element and the product contract.
Should I use XPath in Playwright?
Only when it is genuinely the clearest stable contract available. User-facing locators and stable test IDs are usually easier to read and maintain than DOM-path expressions.
Why does Playwright say strict mode violation?
The locator matched more than one element when the operation expected exactly one. Refine or scope the locator so it describes the intended element uniquely.