Locator Strategies for UI Tests

What makes a locator good

A locator is best judged by what makes it break. A good one changes only when the behaviour a user relies on changes — not when a designer renames a class or a developer adds a wrapper div.

• Unique — it matches exactly one element in the state the test expects. Playwright locators are strict: an action on a locator that matches several elements throws an error, which surfaces ambiguity early.
• Stable — independent of layout, styling, DOM depth, element order and values generated at build or render time.
• Readable — someone reading the test knows which element it means without opening the page.
• Close to user intent — it names the element the way a user or assistive technology perceives it: the “Place order” button, the “Email” field.
• Cheap to fix — when it breaks, the failure message makes the reason obvious.

The priority order: user-facing first, XPath last

Playwright’s documentation recommends role-based locators first, and Testing Library ranks its queries the same way: queries that reflect how users and assistive technology perceive the page come first, and test ids come last among its queries. Adding CSS and XPath for the cases the others cannot reach gives this order:

• 1. Role and accessible name — getByRole("button", { name: "Place order" }). The role comes from the HTML element (button, link, textbox, checkbox, heading) or its ARIA role; the name comes from the label, content or aria-label, computed as the W3C Accessible Name specification describes.
• 2. Label — getByLabel("Email") for form fields associated with a <label> element or aria-labelledby.
• 3. Visible text, alt text, title and input hint text — getByText, getByAltText and getByTitle (plus a matching locator for an input’s hint text) for elements without a useful role and name. Text locators suit non-interactive content such as headings and messages; hint text is a weak substitute for a label.
• 4. Test id — getByTestId("order-total") matches data-testid by default in Playwright (the attribute is configurable); Cypress recommends data-cy or a similar data-* attribute. Use it when user-facing attributes are ambiguous, missing or frequently changed, for example translated text.
• 5. CSS selector — for structural cases: attributes, combinators, form inputs by name. Keep it short and anchored on stable attributes.
• 6. XPath — when you must move to a parent or ancestor, or match text in a tool that has no text locator. Keep it relative and short.

Element: <button type="submit">Place order</button>

Playwright       page.getByRole("button", { name: "Place order" })
Testing Library  screen.getByRole("button", { name: "Place order" })
Selenium (Java)  driver.findElement(By.xpath("//button[normalize-space()='Place order']"))
                 driver.findElement(By.cssSelector("[data-testid=place-order]"))
Cypress          cy.contains("button", "Place order")
                 cy.get("[data-cy=place-order]")

Applying the order in Selenium and Cypress

Selenium has no built-in role locator. Its strategies are id, name, class name, tag name, link text, partial link text, CSS selector and XPath, and Selenium 4 adds relative locators (above, below, to the left of, to the right of, near). In practice the order becomes: a test id or a stable id, then name, then a short CSS selector, then XPath — with visible text reached through link text for links or a text-matching XPath for other elements. Many teams wrap these in page-object methods named after the user-facing element, so tests still read “click Place order”.

Cypress queries with cy.get (CSS) and cy.contains (text). Its best-practices guide recommends dedicated data-* attributes over tag, id and class selectors, and cy.contains for elements whose text is part of the behaviour under test. Teams that want role-based queries in Cypress often add the Testing Library integration, which adds findByRole and the other findBy and findAllBy queries.

Test ids: a contract with developers

A test id is an attribute added to the markup purely for automation, such as data-testid, data-test or data-cy. It is the most stable hook you can have, because nothing but the tests depends on it — as long as the team treats it as a contract rather than a decoration.

• Agree one attribute name for the whole product and configure the tool to use it (for example Playwright’s testIdAttribute setting).
• Name by purpose, not position or style: checkout-place-order, not button-3 or blue-btn.
• Make ids unique within a page. For repeated items, put the id on the container or scope by content, then find the child by role — the row for order ORD-2026-000184, then its “Cancel” button.
• Add test ids in the same pull request as the feature, and review their removal as you would review an API change.
• Do not replace a clear role and name with a test id; the user-facing locator also shows that the element is exposed to assistive technology.
• Whether to strip test ids from production builds is a team decision. Keeping them costs a few bytes and lets you run read-only smoke tests against production.

// Playwright: scope to the row for one order, then find its button by role
const row = page.getByRole("row").filter({ hasText: "ORD-2026-000184" });
await row.getByRole("button", { name: "Cancel" }).click();

// playwright.config.ts: use the attribute your team agreed on
export default defineConfig({ use: { testIdAttribute: "data-test" } });

CSS vs XPath

Both languages express most structural queries; the differences matter at the edges. Neither is “wrong”, but CSS is usually shorter for the common cases, and XPath is the only option for a few others.

• Readability — CSS is shorter for ids, classes and attributes: [data-testid=cart] against //*[@data-testid="cart"].
• Direction — XPath can move up to a parent or ancestor (.., ancestor::tr) and to preceding siblings; CSS traditionally moves only down and forward. The :has() pseudo-class, supported by current major browsers, covers some “parent of” cases.
• Text — XPath can match text (normalize-space()="Pay now", contains(., "Pay")); CSS cannot match text content. Playwright and Cypress add their own text matching on top of CSS.
• Shadow DOM — CSS selectors can be used inside open shadow roots, and Playwright’s CSS and role locators pierce them automatically; XPath does not cross shadow boundaries.
• Version — browsers implement XPath 1.0, so XPath 2.0 functions such as matches() and ends-with() are not available.
• Speed — both are fast enough for UI tests and are rarely the bottleneck. Choose for readability and stability.

Goal                           CSS                          XPath
Element by test id             [data-testid=cart]           //*[@data-testid="cart"]
Input by name                  input[name=email]            //input[@name="email"]
Id starting with a prefix      [id^="order-row-"]           //*[starts-with(@id,"order-row-")]
Attribute contains a value     [class*="error"]             //*[contains(@class,"error")]
Button with exact text         (not possible in CSS)        //button[normalize-space()="Pay now"]
Button in the row of an order  (CSS cannot match the text)  //tr[td[normalize-space()="ORD-2026-000184"]]//button
Parent of an element           (only via :has())            //input[@name="email"]/..

Dynamic ids and generated class names

Many frameworks and component libraries generate attribute values at build or render time: an id="input-4821" that changes on every render, class="Button_primary__3xK9a" from CSS modules, class="css-1q2w3e" from CSS-in-JS libraries. A locator that copies such a value passes today and fails after the next build or the next page load.

• Recognise them — digits or hashes that differ between two loads of the same page. Save the markup from two sessions and compare them to spot the moving parts.
• Prefer a user-facing locator or a test id — the durable fix is a stable hook, not a cleverer selector.
• If you must match, anchor on the stable part — [id^="order-row-"] (starts with), [class*="Button_primary"] (contains) or XPath starts-with(). Keep the pattern tight enough to remain unique.
• Match variable text with a pattern — for example getByText(/Order ORD-\d{4}-\d{6} confirmed/) in Playwright — and test the pattern against real samples before committing it.
• Never hard-code values that come from test data — build the locator from the data the test created, such as the order number returned by the API call that set up the test.

Try it: Regex Tester Try it: Text Diff

Iframes and shadow DOM

An iframe is a separate document, so a locator on the main page cannot see inside it. Payment fields, embedded maps, chat widgets and rich-text editors are often iframes.

Shadow DOM encapsulates a web component’s internal markup. Open shadow roots can be reached by automation tools. Closed shadow roots are hidden by design and are not reachable with standard locators; test them through the component’s public behaviour or ask the developers for a test hook.

• Selenium — switch into the frame with driver.switchTo().frame(…), act, then return with driver.switchTo().defaultContent(). For shadow DOM, find the host element, call getShadowRoot() (Java; shadow_root in Python), then search inside it with CSS selectors.
• Playwright — page.frameLocator(…) or locator.contentFrame() gives a scope for locators inside the frame, with no switching. Playwright locators pierce open shadow roots by default, except XPath.
• Cypress — shadow DOM is supported through the .shadow() command or the includeShadowDom configuration option. Iframes have no dedicated built-in command; the common approach is to reach the frame’s document body from the iframe element, and cross-origin frames add further limits.
• Third-party frames — for a payment provider’s hosted card field, use the provider’s test mode and its published test data, and keep the number of tests that type into the frame small.

// Selenium (Java) — iframe: switch in, act, switch back
driver.switchTo().frame(driver.findElement(By.cssSelector("iframe[title='Card details']")));
driver.findElement(By.name("cardnumber")).sendKeys(testCardNumber);
driver.switchTo().defaultContent();

// Selenium (Java) — open shadow root, then CSS inside it
SearchContext shadow = driver.findElement(By.cssSelector("app-date-picker")).getShadowRoot();
shadow.findElement(By.cssSelector("button.next-month")).click();

// Playwright — frame scope, no switching; open shadow roots are pierced
const card = page.frameLocator("iframe[title='Card details']");
await card.getByLabel("Card number").fill(testCardNumber);
await page.locator("app-date-picker").getByRole("button", { name: "Next month" }).click();

Anti-patterns that make suites brittle

• Absolute XPath — /html/body/div[2]/div/div[3]/form/button breaks when any ancestor changes. The browser’s “Copy XPath” often produces exactly this.
• Index-based selectors — :nth-child(3), (//button)[2] or .first() without a reason. They depend on order and break when an item is added, removed or sorted differently.
• Styling classes — .btn-primary, .mt-4 or .text-red-500 change with every visual redesign or utility-CSS refactor.
• Generated values — ids and class hashes produced at build or render time.
• Long chains — div.container > div.row > div.col-md-6 > form > div:nth-child(2) > input encodes the entire layout.
• Text in the wrong language — a test that locates “Place order” fails when the same suite runs against the Arabic interface («إتمام الطلب»). Either give each locale its own expected strings or use test ids for elements whose text is translated.
• Duplicated locators — the same selector pasted into twenty tests. Keep it in one page or component object.
• Over-broad text matches — getByText("Save") matching the button, a toast and a help paragraph. Scope to a region or use a role.

Automation defects caused by locators (written like bug titles)
- checkout.spec fails after restyle: .btn-primary no longer matches "Place order"
- orders.spec cancels the wrong order when the list is sorted by date: locator (//button[text()="Cancel"])[1]
- login.spec fails on the Arabic build: getByText("Sign in") not found
- profile.spec fails intermittently: #input-4821 is regenerated on every render
- search.spec breaks after a wrapper div is added: /html/body/div[2]/div/div[3]/form/button

Locators and accessibility

Role and label locators use the same information a screen reader announces: the element’s role, from the HTML element or WAI-ARIA, and its accessible name. When getByRole("button", { name: "Delete" }) cannot find an icon-only delete button, the likely reason is that the button has no accessible name — a real accessibility defect, not a test problem. Fix the markup (visible text or aria-label), not the locator.

The same applies when a component library renders a div that behaves like a button: raise a defect for the missing semantics instead of writing CSS locators around it.

This is a side benefit, not an accessibility test. Passing role-based locators do not show that a page is accessible; keyboard, screen reader and automated accessibility checks are still needed.

Worked example: locators for a checkout form

The markup below comes from a fictional checkout page. For each element, the list gives the recommended locator, the Selenium equivalent and what to avoid.

• Email field — getByLabel("Email"). Selenium: By.name("email"). Avoid #email-1293 (generated) and form > input:nth-of-type(1).
• Terms checkbox — getByRole("checkbox", { name: "I accept the terms" }). Selenium: By.cssSelector("input[name=terms]").
• Order total — getByTestId("order-total"); its visible text changes with the amount, so the text is what you assert, not how you locate. Selenium: By.cssSelector("[data-testid=order-total]").
• Submit button — getByRole("button", { name: "Place order" }). Selenium: an XPath on normalised text, or a test id if the team adds one. Avoid .btn-primary and //form/button[1].
• The form itself — do not use #checkout-7f3a or .Checkout_form__x9Kp2. If you need a scope, give the form an accessible name and use getByRole("form", { name: … }), or add a test id.

<form id="checkout-7f3a" class="Checkout_form__x9Kp2">
  <label for="email-1293">Email</label>
  <input id="email-1293" name="email" type="email">
  <label><input type="checkbox" name="terms"> I accept the terms</label>
  <div class="summary">
    <span>Total</span> <span data-testid="order-total">199.20 SAR</span>
  </div>
  <button type="submit" class="btn btn-primary mt-4">Place order</button>
</form>

Try it: HTML Formatter

Locator review checklist

• Does it match exactly one element in the state the test expects?
• Would it survive a restyle, a reordering of items and a change in DOM depth?
• Is it role/label/text first, test id second, CSS third, XPath last — and if not, is the reason written down?
• Is it free of generated ids, hashed classes, indexes and absolute paths?
• Does it live in one page or component object rather than in the test body?
• Will it work in every locale the suite runs in?
• If it failed tomorrow, would the error message say which element was missing?

Frequently asked questions

References

• Locators — PlaywrightMicrosoft (Playwright)How Playwright finds elements, why locators re-resolve and auto-wait, and why role-based locators are recommended first.
• About Queries — Testing LibraryTesting LibraryQuery types and their priority — role and label before text, test ids last — so tests find elements the way users and assistive technology do.
• Locator strategies — SeleniumSelenium ProjectThe locator types WebDriver supports (id, name, CSS selector, XPath, link text and others) and how to choose between them.
• Best Practices — CypressCypress.ioCypress guidance on selecting elements with dedicated attributes, avoiding fixed waits and keeping tests independent.
• Best Practices — PlaywrightMicrosoft (Playwright)Test user-visible behaviour, keep tests isolated, prefer resilient locators and web-first assertions, and debug with traces.
• Accessible Name and Description Computation 1.2W3C · 2026How browsers compute the accessible name and description of an element from labels, ARIA attributes and content (a W3C Working Draft).
• Accessible Rich Internet Applications (WAI-ARIA) 1.2W3C · 2023The W3C Recommendation that defines ARIA roles, states and properties — how custom widgets expose their meaning to assistive technology.