Turn brittle Playwright selectors into locators you can review

A checkout test still passes after the button markup changes, but the selector now points at the coupon form's Save button. Both buttons are visible, both submit something, and the test never checked the order state. A cleaner locator is useful here, but generating one is only the first half of the repair.

Playwright added locator.normalize() in version 1.59 for exactly this kind of maintenance work. It can turn an implementation-shaped locator into a more readable candidate. It cannot recover the business intent that was missing from the test.

What normalization changes, and what it leaves alone

A Playwright Locator is a query, not a stored DOM node. Playwright resolves it when an action or assertion runs, which is why the same locator can survive a React or Vue rerender. Calling normalize() asks Playwright to inspect the element matched by an existing locator and return another Locator that follows its locator-generation preferences. The documented priorities include test IDs, ARIA roles, and user-facing attributes before structural CSS.

That distinction prevents three common misunderstandings.

First, normalization is not whitespace cleanup. Text locators already normalize whitespace during string matching. The normalize() method works on the way an element is referenced, not on the element's text value.

Second, it does not edit a spec file. The returned object exists at runtime. A developer still has to inspect candidate.toString(), decide whether it communicates the intended scope, and replace the old source code deliberately.

Third, it does not turn a weak assertion into a useful one. A normalized locator can click the wrong Save button just as successfully as a long CSS selector. The meaningful proof comes after the click: the order moves to the expected state, the correct row disappears, the right API-backed status is rendered, or another user-visible outcome occurs.

Here is a small test that keeps those responsibilities separate. The markup is local so the example runs without an application server.

import { expect, test } from '@playwright/test';

test('reviews a normalized locator before using it', async ({ page }, testInfo) => {
  await page.setContent(`
    <main>
      <form aria-label="Coupon">
        <button type="button">Save</button>
      </form>
      <form aria-label="Checkout">
        <button type="button" id="checkout-save">Save</button>
      </form>
      <p role="status">Order is draft</p>
      <script>
        document.querySelector('#checkout-save').addEventListener('click', () => {
          document.querySelector('[role=status]').textContent = 'Order submitted';
        });
      </script>
    </main>
  `);

  const legacy = page.locator('main > form:nth-of-type(2) > button');
  await expect(legacy).toHaveCount(1);

  const candidate = await legacy.normalize();
  const review = [
    `before: ${legacy.toString()}`,
    `after:  ${candidate.toString()}`,
    `matches: ${await candidate.count()}`,
  ].join('\n');

  await testInfo.attach('locator-normalization.txt', {
    body: review,
    contentType: 'text/plain',
  });

  await expect(candidate).toHaveCount(1);
  await candidate.click();
  await expect(page.getByRole('status')).toHaveText('Order submitted');
});

Notice what the test does not assert. It does not require toString() to equal one exact generated expression. The human-readable representation is excellent review evidence, but the generation strategy is a Playwright implementation choice that can improve in a later release. Pinning the entire string converts an implementation detail into a noisy snapshot.

The match-count assertion serves a different purpose. Locator actions are strict when an operation needs one element, but an explicit count gives a migration report a clear failure before the action. It tells the reviewer that the candidate became broad, rather than burying the fact inside a click error.

The call also needs a live, representative page. If feature flags, locale, or account permissions change the rendered control, the generated candidate can change with them. Treat the fixture that produced it as part of the review record.

How to prove the starting selector names one intended element

Most failed normalization work begins too late. Someone feeds a legacy selector into normalize() without asking whether that selector still points at the intended element. If it matches zero nodes, the page may not be ready or the selector may already be obsolete. If it matches several nodes, there is no single intent for a generator to preserve.

Capture four pieces of evidence before conversion:

1. The starting locator's toString() value.
2. Its match count after the page reaches the state under test.
3. A compact description of each matched node, such as tag, role, accessible label source, test ID, and nearby business key.
4. The product assertion that will distinguish the right target from a merely clickable one.

The following diagnostic is intentionally read-only. It reports candidates without clicking them and avoids storing ElementHandles.

import { expect, test, type Locator } from '@playwright/test';

async function describeMatches(locator: Locator) {
  return locator.evaluateAll(elements =>
    elements.map((element, index) => ({
      index,
      tag: element.tagName.toLowerCase(),
      id: element.id || null,
      testId: element.getAttribute('data-testid'),
      ariaLabel: element.getAttribute('aria-label'),
      text: element.textContent?.replace(/\s+/g, ' ').trim().slice(0, 80) ?? '',
      connected: element.isConnected,
    })),
  );
}

test('diagnoses a legacy selector before normalization', async ({ page }) => {
  await page.goto('/orders/ORD-1048');
  await expect(page.getByRole('heading', { name: 'Order ORD-1048' })).toBeVisible();

  const legacy = page.locator('.actions > div:last-child button.primary');
  const matches = await describeMatches(legacy);

  console.log(JSON.stringify({
    url: page.url(),
    locator: legacy.toString(),
    count: matches.length,
    matches,
  }, null, 2));

  expect(matches, 'legacy selector must identify one reviewable control').toHaveLength(1);
});

The output answers questions that a screenshot cannot. A screenshot may show one prominent button while a hidden dialog contains another matching node. The report exposes both. It also catches a surprisingly common migration mistake: the selector is evaluated on a list page while the reviewer assumes the browser reached an order detail page.

A typical strictness failure contains a useful locator call log and lists more than one matching element. Read that evidence before adding .first(). An index method silences ambiguity by choosing a position, but it does not establish why that position belongs to the order under test. The same warning applies to .nth().

Trace Viewer adds the missing chronology. Open the failed action, inspect the locator shown for that step, compare the before and after DOM snapshots, and check whether a navigation, dialog, or rerender occurred between page readiness and normalization. The network tab can show that an order request failed even though the page still rendered a generic Save control. Console errors can explain why the intended region never appeared.

Run one focused spec with a retained trace:

npx playwright test tests/orders/checkout.spec.ts --grep "submits ORD-1048" --workers=1 --trace=on
npx playwright show-trace test-results/orders-checkout-submits-ORD-1048/trace.zip

The exact result directory depends on the project and test title, so use the path printed by the reporter. The important evidence is the first failing attempt. A retry may render different data and make the candidate appear sound.

Three conversions that need different judgments

The easiest case is a structural selector for a unique, well-labelled control. Suppose an account page contains one button named Change password. The old selector crosses several layout containers because it was copied from browser DevTools. Normalize it after the page heading is visible, require one match on both locators, and verify that the password dialog opens. If the candidate uses the button role and accessible name, the result describes what a user sees and tolerates layout refactoring.

The cost is coupling to product language. A copy edit from Change password to Update password will break the locator. That may be desirable because the visible contract changed, or it may create translation maintenance in a locale-heavy suite. A test ID is a better contract when the wording changes frequently and the identity does not.

The second case is a repeated action inside a business object. An orders table has twelve Delete buttons. Normalizing table tr:nth-child(4) button.danger without scope can generate an expression that still depends on position or an accessible name shared by every row. Start with the order identity, then normalize the action within that row.

import { expect, test } from '@playwright/test';

test('normalizes inside an order row, not across the page', async ({ page }) => {
  await page.setContent(`
    <table>
      <caption>Open orders</caption>
      <tbody>
        <tr data-testid="order-1047"><th>ORD-1047</th><td><button>Delete</button></td></tr>
        <tr data-testid="order-1048"><th>ORD-1048</th><td><button>Delete</button></td></tr>
      </tbody>
    </table>
    <p role="status"></p>
    <script>
      for (const button of document.querySelectorAll('button')) {
        button.addEventListener('click', event => {
          const row = event.target.closest('tr');
          document.querySelector('[role=status]').textContent =
            'Deleted ' + row.querySelector('th').textContent;
          row.remove();
        });
      }
    </script>
  `);

  const order = page.getByTestId('order-1048');
  await expect(order).toContainText('ORD-1048');

  const structuralAction = order.locator('td:last-child > button');
  const action = await structuralAction.normalize();

  console.log({
    scopedBy: order.toString(),
    generatedAction: action.toString(),
  });

  await expect(action).toHaveCount(1);
  await action.click();
  await expect(page.getByRole('status')).toHaveText('Deleted ORD-1048');
  await expect(page.getByTestId('order-1048')).toHaveCount(0);
  await expect(page.getByTestId('order-1047')).toBeVisible();
});

The extra assertion on ORD-1047 is not decorative. It proves that the action did not remove an arbitrary row. This is the kind of business context a generated locator cannot infer from the word Delete.

The third case is an icon-only control. A button contains an SVG path and has no accessible name, while a tooltip appears only on hover. A normalizer has little durable user-facing information to work with. The correct repair is in the product: add an aria-label, visible text, or a stable test ID chosen with the team. Generating a clever selector from SVG structure merely launders an accessibility and testability problem.

Do not let the test inject an accessible label with page.evaluate() before normalization. That creates a locator against markup real users never receive. It can make the migration green while production remains inaccessible.

An icon control deserves a short product conversation before anyone edits the test. Ask whether sighted users get a persistent label, whether screen-reader users hear a useful name, whether the same icon appears elsewhere, and who owns that wording. If the answer is a test ID, choose one that expresses the action, such as remove-line-item, rather than its current picture, such as trash-icon. Icons change during redesigns; the user task usually does not.

There is a fourth pattern worth reviewing even if it should not become another conversion rule: a control whose identity comes from a changing number. A cart link might be announced as "Cart, 3 items". A generated role locator can legitimately include that accessible name because it is what the page exposes. Hard-coding the full name makes the next add-to-cart action invalidate the locator. A regular expression that ignores every number can become too broad when the header contains a saved-items control as well. The durable answer is often a stable test ID for the cart entry plus a separate assertion on the accessible name. One locator identifies the control; one assertion verifies the count users hear.

That separation also helps with dates, balances, unread-message totals, and user-generated names. Do not ask one selector to carry every assertion. Keep identity stable, then verify dynamic content explicitly. When normalization chooses a dynamic value, the reviewer can retain the semantic locator with a carefully bounded pattern, choose a product-owned test ID, or reject the candidate. Each option documents a real contract instead of blindly accepting generated text.

Finally, compare behavior under the account types that matter. An administrator may see Delete and Suspend beside an order, while a support agent sees only View. Normalizing as the support agent can produce a locator that looks unique because the competing controls were never rendered. The resulting expression may still be valid for the administrator, but the surrounding scope and assertion need to be exercised in that role. This is why a fixture name belongs beside the candidate in the review attachment.

How to separate locator drift from similar failures

A strictness error after normalization is usually scope or uniqueness. A timeout is less specific. The target may be absent, present but hidden, covered by an overlay, continuously rerendered, or located correctly while the product transition never completes. Each cause leaves different evidence.

If the candidate count is zero while the original count is one, compare their string forms and inspect the current DOM snapshot. An accessible name may be supplied by an element that appears only after hydration. The candidate may also depend on a test ID present in one environment but removed by a build transform. The fix is to make the contract consistent, not to increase the action timeout.

If both counts are one and the actionability log says another element intercepts pointer events, the locator is probably correct. An open consent banner, spinner, or sticky header is the competing cause. Check the trace snapshot and the element named in the interception message. Changing the locator can move the click somewhere else and hide the overlay defect.

If the click completes but the assertion fails, inspect the request and response tied to the action. A server rejection, stale test data, or JavaScript exception can leave the same control visible. Normalization affects element targeting only. It does not wait for an arbitrary backend state unless the subsequent assertion observes that state.

If a role-based candidate becomes ambiguous only in one locale, inspect accessible names, not CSS. Two translated actions may collapse to the same phrase. Scope them by region or business object, or agree on a test ID. Using a regular expression broad enough to cover every translation usually makes the ambiguity worse.

There is also a near-miss that produces green tests: a hidden duplicate and a visible control share a contract, but the product action has the same superficial result. For example, both Save buttons produce a Saved toast while only one persists the shipping address. A visible toast cannot identify which form submitted. Assert the saved address after a reload or check the exact rendered order record. That extra state transition earns far more confidence than any selector string.

Avoid diagnosing from toString() alone. It describes the locator, not its resolved element, actionability state, or effect. Pair it with count, trace chronology, and a product assertion.

Read the audit record at the same page checkpoint

A migration record becomes useful when every field describes one rendered state. Put the route, fixture identity, role, locale, original locator string, candidate locator string, both counts, and the enclosing business key beside one another. The business key is the field that prevents two successful queries from looking equivalent when one resolved inside ORD-1048 and the other inside ORD-1047.

A healthy record shows the expected detail route, one original match, one candidate match, and the same enclosing order key for both. Resolve both locators again after the page's normal rerender point. They should still identify that key before the behavior test performs its single action. The result assertion then supplies a different kind of proof: it says the correct order changed, not merely that the queries agreed.

A broken candidate can look simple: the original count is one and the candidate count is zero in the same snapshot. Read the candidate string next. If it contains a role and accessible name, inspect the rendered accessibility source for that name. A missing label on the same element points to a product-contract change. A candidate that names a different region points to lost scope. Increasing a timeout changes neither fact.

The most misleading record shows one and one. Counts alone make it look healthy, while the enclosing keys reveal different objects. This happens when identical controls sit in repeated rows and each locator chooses a different row. The candidate string may still look exemplary because getByRole('button', { name: 'Delete' }) is readable. Readability does not restore the row identity that was dropped.

Capture counts at more than one phase when a timeout appears after a successful audit. If both original and candidate resolve once before hydration and both resolve zero times at the action boundary, the page state disappeared underneath them. That is a rendering or fixture problem, not evidence that normalization produced a worse selector. If the original remains at one while only the candidate falls to zero, the candidate depends on state that did not survive. These two failures can end with the same timeout line naming the candidate. The paired phase counts separate them precisely.

An unexpected route is another misleading value. Zero matches on an authentication page do not evaluate locator quality on the order page. Treat route and visible page identity as prerequisites, not supporting decoration. A screenshot can make an authentication shell look like the application if they share navigation chrome, while the route and heading expose the detour immediately.

How to roll normalization into an existing suite

A mass conversion is tempting because the API is easy to call. It is also the fastest way to approve hundreds of unreviewed assumptions. Roll out by risk and keep each change small enough to inspect.

Start with an inventory of structural selectors. The command below only finds candidates. It is not a quality rule, because some CSS is a legitimate contract and some weak locators do not match these patterns.

rg -n "nth-child|nth-of-type|xpath=|locator\(['\"][^'\"]*[>+~]" tests e2e
rg -n "\.(first|last)\(\)|\.nth\(" tests e2e

Choose a small feature with reliable data. For each locator, add a temporary audit that records the original string, generated string, and counts. Run it against the environments and roles that render materially different markup. Do not commit the runtime call as a permanent indirection unless there is a specific reason to generate locators during execution. In most suites, the reviewed result should become ordinary source code.

Classify each candidate:

• Accept when it expresses the same business scope, stays unique, and passes a meaningful state assertion.
• Amend when it needs a row, dialog, frame, or region boundary.
• Reject when it relies on volatile copy, accidental attributes, or position.
• Escalate to the product when the element lacks an accessible name or stable test contract.

Keep the old and new implementations close during review, but do not execute both actions in one test. Clicking twice changes state and invalidates the comparison. Instead, use one read-only equivalence test for match evidence and a separate behavior test for the accepted locator.

Record disagreements instead of forcing a pass. If the legacy selector finds one element and the candidate finds none, save the DOM snapshot and fixture identity. If both find one element, compare stable facts such as the enclosing order key, form label, or dialog heading. Avoid comparing full outerHTML; frameworks add transient classes and generated attributes that turn the report into noise. If the two locators find different business objects, the old test may already be wrong. That discovery should become a defect or a focused test repair, not an automatic rejection of the new locator.

Run the first batch without retries. A retry can hide a hydration race that affects candidate generation, and it can load a different record after test cleanup. Once the batch is understood, restore the repository's normal retry policy but keep traces from the first attempt. Reviewers then see whether the locator was absent during initial render, ambiguous throughout the run, or correct until another transition changed the page.

Measure migration progress by reviewed call sites, not by the percentage of CSS removed. A short CSS locator tied to a product-owned attribute may be healthier than a long role expression assembled from volatile text. The useful outcome is a suite whose selectors state ownership and whose assertions detect the wrong business action.

Pin Playwright through the lockfile and make the migration job retain first-attempt traces. A focused CI job can protect the reviewed contracts without running an interactive generator:

name: locator-contracts
on:
  pull_request:
    paths:
      - "tests/**"
      - "playwright.config.ts"
      - "package.json"
      - "pnpm-lock.yaml"

jobs:
  verify:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm exec playwright test tests/locator-contracts --trace=retain-on-failure
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: locator-contract-traces
          path: test-results

After the first feature is stable, add a review checklist to pull requests. Ask which user or business identity scopes the element, what a duplicate would look like, what product state proves the action, and whether a test ID or accessible name is owned by the product team. Those questions scale better than a rule that every selector must be normalized.

Land the behavior proof before replacing a locator. If the current test only checks a generic toast, first add the order, account, or record assertion that distinguishes the intended action. That change may expose an old false positive before normalization begins. Next, land read-only audit output for a small feature and stabilize the data and roles needed to reproduce it. Only then replace reviewed call sites. Reversing that order leaves a clean candidate protected by the same weak assertion that allowed the brittle selector to drift.

The first rollout breakages are useful. Shared Save and Delete controls produce count failures. Hidden templates expose duplicate test IDs. Locale variants reveal names that were unique only in English. Permission fixtures reveal controls that were never available to the role encoded by the test. Triage those failures as contract findings instead of immediately adding positional methods. A locator migration that never challenges scope or fixture assumptions probably is not exercising the risky pages.

For the first converted feature, keep failures attributable. Run the feature's deterministic tests on their normal browser targets and preserve first-attempt evidence. Compare the route, role, business key, and product result with the audit record. The change is working when accepted locators remain unique at the action boundary, the intended object changes, neighboring objects do not, and the runtime suite no longer calls normalize() merely to rediscover committed source. A falling CSS-selector count is not proof of success.

Ownership should follow the kind of contract that failed. The test owner owns the business boundary, representative fixtures, and result assertion. The frontend owner owns accessible names, duplicate IDs, and markup that exposes no stable identity. A test-platform owner can own the audit helper, artifact retention, and migration policy, but cannot decide whether ORD-1048 or ORD-1047 was the intended order. Hand off a failing case with the exact route, role, locale, relevant feature state, original and candidate strings, phase-by-phase counts, enclosing business keys, first-attempt trace, and expected product result. A ticket containing only the generated string pushes the central intent question onto the wrong team.

The read-only equivalence stage resolves two locators at each checkpoint instead of one and still needs a separate behavior run because executing both actions would mutate the same state twice. For data-heavy features, that means one page setup for comparison and another for behavior in every supported state under review. The extra browser work and trace storage belong in the migration budget. Remove temporary probes after the reviewed locator becomes ordinary source, since keeping them would add runtime and artifact maintenance without adding product coverage.

Normalization does not test keyboard reachability, focus order, or screen-reader operation. A role-based locator can resolve and click a control that a keyboard user cannot reach. Keep accessibility coverage separate and exercise the input paths the product claims to support.

What this technique costs, and when to leave code alone

Normalization adds a browser-dependent review step. The page must reach a representative state, so authentication, feature flags, seeded records, and locale all affect the candidate. A static lint rule is cheaper because it never launches a browser, but it cannot see the rendered accessibility tree or prove intent.

Generated role and text locators can increase sensitivity to wording. That sensitivity is valuable for critical labels that users rely on. It is expensive for marketing copy, localization, and A/B tests. Stable test IDs reduce copy churn but expose a test-specific contract in markup. Neither choice is universally superior.

Runtime normalization also adds latency and another failure point. Calling it in every test makes the suite derive selectors repeatedly from live state. Once a candidate is reviewed, ordinary locator source is easier to search, review, and debug. Keep runtime generation for tooling, audits, or deliberately dynamic workflows.

Do not normalize a locator that already communicates intent clearly. page.getByRole('button', { name: 'Pay now' }) gains nothing from a conversion round trip. The same applies to a well-scoped test ID whose ownership is documented.

Avoid it as a response to an actionability problem. An overlay, animation, disabled state, or moving element needs product-state evidence. A different selector may click around the symptom and reduce coverage.

Do not use it to rescue a locator that matches many elements. Establish scope first. The chosen scope may be a table row keyed by order number, a dialog with a specific heading, a frame, or a region. Only then is there one element whose reference can be improved.

Finally, leave intentionally structural tests alone. A component test may exist to verify DOM order, grid placement, or a generated wrapper. In that narrow case, structure is the behavior under test. Replacing the selector with a role locator would stop observing the requirement, even though it looks more fashionable.