Robust Locator Strategy

The className locator fails for a reason worth stating precisely: classes are styling contracts. A redesign renames btn-primary to button--brand, the visual result is identical, and every test keyed on the class breaks — for a change that altered nothing a user could perceive. Test selectors and CSS classes answer to different owners, and conflating them is the root cause of a large share of maintenance toil. data-testid exists to break that coupling: an attribute whose only purpose is to be a stable handle for tests.

<!-- markup -->
<button class="btn button--brand" data-testid="checkout-submit">Place order</button>

// Playwright
await page.getByTestId('checkout-submit').click();
// Selenium
await driver.findElement(By.cssSelector("[data-testid='checkout-submit']")).click();

Now the redesign renames every class; the test is untouched. That is the entire pitch — and it is not uncontested, so an interview answer must carry both sides.

The case for test ids: complete decoupling from styling and copy (rename Place order → Pay now freely); one unambiguous handle per interaction target, which kills positional and nth-child hacks; and a naming convention (checkout-submit, user-menu-toggle) that documents intent for both QA and new developers. Frameworks agree: Playwright ships data-testid as the getByTestId default (configurable via testIdAttribute), and the wider ecosystem (Testing Library's data-testid, Cypress's data-cy convention) standardized on the same idea.

The case against: test ids are dead markup — invisible to users, adding noise to the DOM and to component snapshots; they can lie (the id says submit, the button now cancels); and if tests use the id while humans use role and label, nobody notices when the accessible name is emptied. Teams in regulated or accessibility-sensitive domains therefore prefer roles first and reserve test ids for elements with no stable semantic identity — data grids, canvas widgets, decorative-but-interactive components.

The synthesis that wins arguments: prefer the user's own contract (role + accessible name) when the element has one; add a test id when it does not, or when the accessible name is intentionally volatile (a dynamic label like Delete Acme Corp). Also note the honest cost: test ids must be maintained. An id pointing at a removed feature is as stale as a bad class selector, so some teams lint orphaned test ids the same way they lint orphaned locators.

Where you land matters less than landing it once, in writing. The convention worth adopting for a typical web app:

Priority 1: getByRole(role, { name })      semantic, a11y-checked
Priority 2: getByLabel(text)               form controls
Priority 3: getByTestId(id)                only where 1–2 cannot express the target
Forbidden:  generated classes, absolute XPath, bare nth-child positions

The last line is where the leverage is: a team that agrees only on "prefer good selectors" still ships brittle ones; a team that bans three specific forms does not. Note also who should own the ids: when QA and developers share a component library, adding data-testid becomes part of building a component — reviewed in the same pull request as the markup — rather than a follow-up ticket that quietly never happens. Ownership is what keeps ids from appearing only on the screens somebody happened to test, an inconsistency that reads as chaos to the next engineer. The mechanism for holding the line across the suite — role-based location — is the next chapter, because roles do double duty as accessibility verification.

Playwright's role-based locators are presented as a convenience and are actually a test strategy: locating by what the element is to assistive technology means every green test has also confirmed that a screen-reader user could find and operate that control. A test suite written this way audits accessibility on every run without an accessibility scanner in sight.

// The big five, in the order they cover most UI:
await page.getByRole('button', { name: 'Place order' }).click();
await page.getByRole('link', { name: 'Pricing' }).click();
await page.getByRole('textbox', { name: 'Email address' }).fill('qa@example.com');
await page.getByRole('heading', { name: 'Order confirmed' }).toBeVisible();
await page.getByRole('checkbox', { name: 'Remember me' }).check();

name matches the accessible name — the text an assistive tech announces — which is computed from visible text, aria-label, aria-labelledby, an associated <label>, or an image alt. That computation is the accessibility standard itself, so getByRole('button', { name: 'Close' }) fails if a developer strips the label from a button; the failure message reads like an accessibility bug report. Two clarifications interviewers like to probe: a <button> element maps to role=button implicitly (no ARIA needed — good markup gives roles for free), and name matching is case-insensitive and whitespace-normalized by default, so exact string anxiety is unnecessary.

Roles also force an important question when a locator cannot be expressed: "what role does this element advertise?" Finding that the modal's close control has no role, no label, and no keyboard path is a defect discovered by writing a test, which is the strategy working as intended. Where semantics genuinely do not apply — a canvas-drawn chart, a virtualized grid cell, an SVG handle — fall back to test ids rather than resurrecting positional selectors.

Contrast with the alternatives to make the trade-off explicit:

When the visible text is dynamic (Delete Acme Corp), match partially with name regexes or use getByRole('button', { name: /delete/i }) — the pattern keeps the semantic anchor while tolerating the variable part, and it beats string-concatenating selectors. For lists and tables, pair the row's text with the action inside it (getByRole('row').filter({ hasText: 'Acme' }).getByRole('button', { name: 'Delete' })) — relational locators in fluent form, no XPath required.

For Selenium teams the same principle applies through the standard attributes: locate by By.name, By.id, or CSS on [aria-label='…'] / [role='button'], and prefer aria-label/aria-labelledby targets where you control the markup. The principle travels even when the helper does not: locate by meaning, and let styling be free. Holding that line across a team is a documentation problem, which is the third piece of this topic.

Two engineers on one team can each write perfectly stable locators and still produce a suite that reads like two dialects: one uses getByRole everywhere, the other concatenates [data-testid] strings with XPath for everything. Neither is broken — but every reviewer pays a translation tax, and new members copy whichever file they opened first. The fix is not more talent; it is a one-page convention, agreed once, enforced by review and linting.

What the page actually contains. Not philosophy — an ordered list, with examples from your codebase:

# Locator Convention — web-ui

1. getByRole(role, { name })        → buttons, links, headings, inputs, dialogs
2. getByLabel(text)                 → labeled form controls
3. getByTestId(id)                  → dynamic-named or non-semantic targets
4. getByText / text=                → assert-only (rare), never for actions

Forbidden:
- absolute XPath            /html/body/…
- generated classes         .sc-bdfBwQ, .css-1x2j5u, emotion/styled hashes
- bare positional           //div[3], ul > li:nth-child(4) as identity

Test-id naming: <area>-<element>[-<qualifier>]   checkout-submit, user-menu-toggle
Adding a test id: PR to the component + note in the PR why roles could not cover it.

Specificity is the point: "prefer semantic selectors" is not enforceable; "list starts at getByRole, three forbidden forms, ids named area-element" is. Include the why in one sentence per rule — reviewers enforce rules they understand, and a new hire learns the system by reading the page once.

Enforcement has three layers. First, review: the PR checklist item is one line — "locators follow the convention" — cheap to check because the convention is a short list. Second, static linting: rules like eslint-plugin-playwright's no-conditional-in-test siblings, or a custom rule that flags nth-child, absolute // paths with /html, and known generated-class prefixes in locator strings. Third, runtime: strict mode (Playwright) turning ambiguity into errors, and a periodic locator audit — grep the suite for xpath, nth-child, and getByTitle to find stragglers and measure your progress as a percentage. Numbers make conventions stick: "we are down from 41 brittle selectors to 6" is a reviewable metric.

Handle the two hard cases explicitly in the document, because they are where conventions die: what if the accessible name is unstable (dynamic content: Delete Acme Corp) — answer: partial-name regex on role, or test id; what if there is no semantic element (custom widget, canvas) — answer: test id, with a note requesting the component add proper roles when feasible. Named escape hatches prevent ad-hoc ones.

When markup changes, the convention should make the repair mechanical: roles and labels changing means the user-facing contract changed and tests should be updated deliberately; a test id disappearing means someone removed a component's contract and the test update is part of the same PR by definition. Either way the change lands in the page-object layer from Page Object Basics — locators live there, tests reference intent — so the convention effectively governs two files per screen instead of two hundred test lines. Get the strategy right first, and the page object becomes a thin, stable map rather than a copy of the DOM.

The convention also decides what happens when a locator breaks in review: if a PR adds a second element that makes a locator ambiguous, the failing strict-mode test is a conversation about semantics — which of these two controls is the real one — not a hunt for a cleverer selector. Teams that internalize this stop treating locator failures as test-fragility evidence and start treating them as design feedback, which is precisely the shift from writing scripts to owning a framework.