filter() and chaining before first(), nth(), or a test id — and treat nth() as a last resort the docs themselves discourage.Strict mode is not an obstacle Playwright puts in your way. It is the framework refusing to guess which of several elements you meant, at the one moment when guessing would be cheapest and most dangerous. The fix is almost never to pick an index. It is to say which element you meant in the same terms a user would.
\n\nA strict-mode failure prints the matched candidates. Most of the debugging information you need is already on your screen:
\n\nError: strict mode violation: getByRole('button', { name: 'Save' }) resolved to 3 elements:\n 1) <button type=\"submit\" class=\"btn-primary\">Save</button> aka getByRole('form', { name: 'Profile' }).getByRole('button')\n 2) <button type=\"submit\" class=\"btn-primary\">Save</button> aka getByRole('form', { name: 'Notifications' }).getByRole('button')\n 3) <button type=\"button\" hidden class=\"btn-primary\">Save</button> aka getByTestId('row-template').getByRole('button')Three things are worth noticing before you change a line of code.
\n\nFirst, Playwright suggests a disambiguating locator for each candidate on the aka line. That suggestion is usually the answer, and it is usually a container scope rather than an index.
Second, candidate 3 is hidden. A hidden row template matching your locator is a different bug from two real forms matching it, and it wants a different fix.
Third, candidates 1 and 2 are genuinely indistinguishable by their own markup. Two buttons with the same accessible name, same role, and same classes. If your test cannot tell them apart from the accessibility tree, neither can a screen-reader user tabbing through the page. That is worth saying out loud in the pull request, because it is a product finding, not a test finding.
\n\nStrictness applies to operations that must resolve to exactly one DOM element. Actions like click(), fill(), and press() throw when the locator matches more than one. Operations that are inherently about sets do not:
const saveButtons = page.getByRole('button', { name: 'Save' });\n\nawait saveButtons.count(); // fine - 3\nawait saveButtons.all(); // fine - three Locator handles\nawait expect(saveButtons).toHaveCount(2); // fine - asserts on the set\n\nawait saveButtons.click(); // throws: strict mode violationThis is why count() is such a useful debugging probe. You can measure the ambiguity before and after a change without triggering the failure you are investigating.
Work down this list. Each step is more specific than the last, and the first four keep the locator anchored to something a user can perceive.
\n\nThe single most common cause is a role locator without a name. getByRole('button') matches every button on the page; it is a category, not an element.
// Ambiguous: matches every button\npage.getByRole('button');\n\n// Specific: role plus accessible name\npage.getByRole('button', { name: 'Save profile' });\n\n// Exact match when one name is a substring of another\n// (by default 'Save' also matches 'Save and close')\npage.getByRole('button', { name: 'Save', exact: true });\n\n// Anchored but case-insensitive: pass a regular expression\npage.getByRole('button', { name: /^save$/i });The exact option is worth understanding precisely, because the default is more permissive than most people expect. With exact unset, name matching is case-insensitive and matches a substring — so { name: 'Save' } matches \"Save and close\" too. Setting exact: true makes it case-sensitive and whole-string. Passing a regular expression ignores exact entirely, which is how you get anchoring and case-insensitivity together. Whitespace is normalised in every case: runs of spaces collapse, newlines become spaces, and leading and trailing whitespace is ignored.
When two controls are legitimately identical because they belong to two different regions, name the region. This is the fix that matches how a user actually disambiguates them — by looking at which form they are in.
\n\nconst profileForm = page.getByRole('form', { name: 'Profile' });\nawait profileForm.getByRole('button', { name: 'Save' }).click();\n\n// The same idea for a table row, which is where this comes up most often\nawait page\n .getByRole('row', { name: 'ada@example.com' })\n .getByRole('button', { name: 'Revoke access' })\n .click();Chaining is the workhorse here. Each link narrows the search to descendants of the previous match, so the final locator stays readable and survives layout changes that an index-based locator would not.
\n\nWhen the container has no accessible name to grab, filter the set by something inside it. filter() accepts hasText, hasNotText, has, and hasNot:
// By text somewhere inside the element, including descendants\nawait page.getByRole('listitem').filter({ hasText: 'Orange' }).click();\n\n// By the presence of a descendant matching another locator\nawait page\n .getByRole('listitem')\n .filter({ has: page.getByTestId('sale-badge') })\n .getByRole('button', { name: 'Add to cart' })\n .click();\n\n// By the absence of one - useful for skipping archived rows\nconst activeRows = page.getByRole('row').filter({ hasNot: page.getByText('Archived') });\nawait expect(activeRows).toHaveCount(2);hasText matches a substring anywhere inside the element, case-insensitively. That is convenient and occasionally too permissive; pass a regular expression when you need to anchor it.
Candidate 3 in our error was a hidden row template. Component libraries, virtualised lists, and carousels routinely keep offscreen or hidden copies in the DOM. If the duplicates are genuinely invisible:
\n\nawait page.getByRole('button', { name: 'Save' }).filter({ visible: true }).click();Use this deliberately rather than reflexively. It is the right fix for a hidden template. It is the wrong fix for a modal that is open when it should not be, because it will hide that bug rather than surface it.
\n\nIf two controls are indistinguishable to assistive technology and you cannot change that today, a test id is a legitimate, explicit escape hatch:
\n\nawait page.getByTestId('profile-save').click();Prefer adding the test id to the container rather than the control, so the locator still reads as \"the save button inside the profile card\" and still breaks if that button disappears:
\n\nawait page.getByTestId('profile-card').getByRole('button', { name: 'Save' }).click();When you do this, file the accessible-naming gap. A test id resolves the test; it does not resolve the ambiguity for the person using a screen reader.
\n\nPlaywright's documentation is unusually blunt about this. You can opt out of strictness with first(), last(), and nth(), but the docs state these \"are not recommended because when your page changes, Playwright may click on an element you did not intend.\"
There is a narrow case where positional selection is honest: when order is part of the specification and you assert that order.
\n\nconst rows = page.getByRole('row').filter({ hasNot: page.getByRole('columnheader') });\n\n// The order is the thing under test, so state it\nawait expect(rows).toHaveCount(3);\nawait expect(rows.nth(0)).toContainText('Most recent');\n\nawait rows.nth(0).getByRole('button', { name: 'Open' }).click();The difference between this and a drive-by .first() is the assertion above it. If sort order changes, this test fails with a message about ordering instead of silently operating on the wrong row.
The cheapest way to keep a locator honest over time is to state its cardinality where you define it. This converts a future strict-mode violation — which surfaces at the click, with a stack trace pointing at an action — into a clear assertion failure pointing at the locator.
\n\nconst saveProfile = page\n .getByRole('form', { name: 'Profile' })\n .getByRole('button', { name: 'Save' });\n\nawait expect(saveProfile).toHaveCount(1);\nawait saveProfile.click();This is also the before-and-after evidence to attach to the change. Record the match count from the failing locator and the match count from the replacement. Two numbers, both reproducible, both meaningful to a reviewer who was not involved in the debugging.
\n\nor() matching both branchesThe or() combinator is a frequent and surprising source of strict-mode violations. It is designed for \"whichever of these appears\" — but if both appear, it matches both:
const newEmail = page.getByRole('button', { name: 'New' });\nconst dialog = page.getByText('Confirm security settings');\n\n// Throws if the dialog and the button are both on screen\nawait expect(newEmail.or(dialog)).toBeVisible();\n\n// The documented fix for this specific case\nawait expect(newEmail.or(dialog).first()).toBeVisible();This is the one place where first() is the documented answer rather than a shortcut, because the intent really is \"either of these, I do not care which.\"
Dialogs rendered through a portal land at the end of <body>, outside the DOM subtree you scoped to. A closed-but-not-unmounted modal from a previous step then matches your locator alongside the live one. Scope to getByRole('dialog') and assert there is exactly one before interacting with its contents.
A page with two <nav> elements and no aria-label on either gives you two navigation roles that nothing can tell apart. The test fix and the accessibility fix are the same edit: label the landmarks.
Rather than iterating on selector guesses, let the tooling enumerate the candidates for you:
\n\n# Step through with the inspector and try locators against the live DOM\nnpx playwright test tests/profile.spec.ts --debug\n\n# Record a locator by pointing at the element\nnpx playwright codegen https://example.com\n\n# Open the trace from a CI failure and read the DOM snapshot at the failing step\nnpx playwright show-trace trace.zipIn the trace viewer, the DOM snapshot at the failing action is authoritative in a way that a local reproduction is not — it is the actual page state in the environment where it failed. When a strict-mode violation only happens in CI, that snapshot almost always shows a second element that never renders locally.
\n\nA model is good at reading a printed candidate list and proposing a scoped replacement locator. That is a pattern-matching task over text you already have, and it is a genuine time-saver.
\n\nIt is not able to tell you which of two identical Save buttons is the one your test means. That is a question about the product's intent, and the answer lives with the person who wrote the requirement. Accepting a model's guess here produces a test that passes and protects nothing — the most expensive failure mode in a suite, because it is invisible.
\n\nA workable boundary: let the model propose, and let toHaveCount(1) plus a human reviewer decide. If a proposed locator cannot be justified in one sentence that mentions the user's task, it is not ready to merge.
Take one strict-mode violation in your suite. Record the match count of the current locator. Rebuild it using the highest step on the list above that works — accessible name, then container scope, then filter. Record the new match count, assert it with toHaveCount(1), and put both numbers in the pull request.
If the only fix that worked was nth(), that is a finding rather than a failure. Write down what made the two elements indistinguishable, and route it to whoever owns that component.
Not globally, and that is deliberate. Strictness is per-operation and you opt out one locator at a time with first(), last(), or nth(). A global switch would convert every future ambiguity into a silent wrong-element interaction.
count() work when click() throws?Playwright distinguishes operations that need exactly one element from operations that are about a set. count(), all(), and toHaveCount() are set operations, so multiple matches are expected rather than ambiguous.
Usually a second element renders there and not locally: a cookie banner, a feature flag defaulting differently, a slower load leaving a skeleton row mounted, or seeded data producing two rows where your local database has one. Read the DOM snapshot in the trace rather than reproducing locally.
\n\ngetByTestId bad practice?No, but it is a different trade. It is stable and explicit, and it is invisible to users, so it cannot tell you when a control has become unreachable by name. Use it when the UI is genuinely ambiguous, and log the naming gap when you do.
\n\nfirst(), last(), and nth()filter(), and(), or(), count(), and all()