Fix unstable selectors in Playwright.

A selector problem is one possible cause of an intermittent failure. Before rewriting it, compare a passing and failing run under the same intended setup.

1. Keep the conditions.

   Record the test, browser project, account, data, and worker settings. Keep both traces when available, including the failed attempt that a retry passed.

2. Compare the actual target.

   At the failing action, inspect the matched element, surrounding rows, and page state. Did sorting move the record? Did another control appear? Did an attribute change?

3. Test one explanation.

   Recreate that difference and change only the relevant locator assumption. Keep the same outcome assertion so the before and after results are comparable.

Start with the locator-failures guide if you still need to distinguish a missing match, a strictness error, or a blocked action. Playwright’s Trace Viewer provides evidence from the automated run.

The test should open INV-1042. A locator using nth(1) instead chooses the second matching button. Change the list below, then compare that rule with a locator scoped to the invoice.

const invoices = page.getByRole('table', {
  name: 'Invoices', exact: true,
});

// Assumes the intended invoice is always second.
await invoices
  .getByRole('button', { name: 'Open', exact: true })
  .nth(1)
  .click();

The example models a known dependency on order. It is not a measured failure rate. See Playwright’s guidance on positional locators.

In the example, changing syntax alone is not enough: the brittle locator already uses getByRole. The meaningful change is identifying the invoice before choosing its Open button.

<tr data-testid="invoice-1042">
  <td>INV-1042</td>
  <td><button type="button">Open</button></td>
</tr>

const invoice = page.getByTestId('invoice-1042');
await expect(invoice).toHaveCount(1);
await invoice
  .getByRole('button', { name: 'Open', exact: true })
  .click();
await expect(page.getByRole('heading', {
  name: 'Invoice INV-1042', exact: true,
})).toBeVisible();

Use the locator comparison guide to weigh role, test ID, and CSS dependencies. The goal is an explicit, maintained target.

Repeat the focused test with retries disabled for the investigation, so each attempt’s result remains clear. Capture traces and keep the original project and environment settings.

npx playwright test tests/invoices.spec.ts \
  --retries=0 --repeat-each=5 --trace=on

Replace tests/invoices.spec.ts with your test file. Add the relevant project or test filter. Five runs are a starting sample, not a reliability guarantee; preserve the concurrency that matters to the failure. Command-line options.

• Recreate the original data, account, browser project, and worker settings.
• Try the relevant ordering, extra rows, and repeated controls that exposed the problem.
• Check the intended record and the application result after the click.
• Run the focused case again, then the neighboring tests and original suite conditions.
• Keep any remaining failure and its trace. Record the number of runs and what varied.

If the same target still behaves inconsistently, follow the broader flaky-test investigation. A selector change will not repair unrelated setup or service failures.

Keep a short review note beside the test change. Explain what varied, why the new locator follows the right identity, and which conditions you checked.

Selector change review

Test and original conditions: [file, project, data, workers]
Expected target and result: [record, action, confirmation]
Passing / failing evidence: [trace links and relevant step]
Changed assumption: [what differed between the runs]
Replacement and reason: [locator and maintained identity]
Verification: [conditions tested, results, remaining failures]
Owner: [who maintains the UI or test contract]

Add the actual results and evidence links. An investigation outline is useful only when it describes what you observed.