Locators for Automation
What a locator is, why they matter, best practices, signs of a bad locator and the types ordered by priority, with a focus on accessibility.
In an automated test you must tell the tool how to locate elements in order to interact with them. For example, to test the “Log in” button you need to provide its identifier (locator) to click it.
What is a locator?
It is how an automation tool identifies an HTML element within the DOM to interact with it. People recognize a button or field visually, but the tool needs to rely on attributes and code structure. The DOM (Document Object Model) is the tree-shaped structure representing all elements of a web page.
A good locator allows you to
- Avoid false negatives.
- Reduce flakiness (inconsistency/instability).
- Avoid unnecessary maintenance and keep scripts readable.
- Withstand UI changes.
- Ensure it points to a single element (uniqueness), otherwise the test fails.
Best practices
- Prioritize accessibility-based locators (ARIA attributes): they add stability, readability and reflect real interactions.
- Encapsulate: do not repeat locators in every test, centralize them to ease maintenance.
- Avoid unstable locators: marketing-driven variable text, auto-generated IDs or dynamic classes.
- Request specific attributes like data-testid: a stable, style-independent way to locate elements.
Signs your locator is NOT good
| Bad practice | Recommendation |
|---|---|
| Too long: /html/body/div[1]/main/.../input[1] | getByRole('button', { name: 'Buy' }) |
| Style CSS class: button.btn-success | getByRole('button', { name: 'Buy' }) |
| Index: ul > li:nth-child(3) > a | a[data-nav-item="contact"] |
| Unreadable: div > input:focus + span | getByLabel('Password') |
| Auto-generated ID: button.c-012b-abc-12-a | [data-testid="submit-data-button"] |
Do not use index to locate
Instead of the element’s position, identify it by its content or a stable attribute. If a dev adds a new item, all following ones shift and the test fails.
Locator types (ordered by priority)
1. Visible content
Visible text or attribute (label, placeholder, alt, title). Very readable, but text may change due to refactor or translation. E.g.: getByText, getByLabel, getByPlaceholder.
2. Semantic / ARIA
How users interact with the interface. The most robust and valuable: they validate accessibility. Only work if the element has a correct semantic role. E.g.: getByRole.
3. getByTestId
Custom attribute (data-testid) added only for automation. Extremely stable; requires coordination with development (a stability contract).
4. CSS Selectors
Based on id, class or other selectors. Fast and well supported, but fragile if tied to style classes. Playwright does not recommend them as a first choice.
5. XPath
A very flexible, powerful query language, but the least readable, slowest and most fragile. Consider it a “last resort”.
Benefits of getByRole
- Mimics user interaction: locates elements as a person sees them (a “Sign In” button, not a div with data-testid).
- Inherent robustness: identifies elements by their real function (button, textbox, checkbox, link, heading, list, table).
- Uses ARIA standards: besides validating functionality, it confirms accessibility is preserved.
page.getByRole('button', { name: 'Sign In' })Save or share this content
Download it as PDF or Markdown to save or share it.