In Playwright, why does page.getByRole('button', { name: 'Save' }) also match a button named 'Save and close'?

By default the `name` option of `page.getByRole` is a **case-insensitive substring** test against the computed accessible name, so `{ name: 'Save' }` matches a button whose name is `Save`, one whose name is `save`, and one whose name is `Save and close`. This is deliberate: labels change case and gain suffixes, and a substring match survives that. It is also the single most common source of a locator that matches more elements than the author expected. ## The three matching modes | `name` value | Matching | Case | |---|---|---| | `'Save'` | substring | insensitive | | `'Save'` with `exact: true` | whole string | sensitive | | `/^Save$/` | whatever the pattern says | pattern's own flags | - `exact: true` flips **both** switches at once — there is no option that makes matching case-sensitive while keeping it a substring. - `exact` is ignored when `name` is a `RegExp`; the pattern already expresses everything, including anchoring and the `i` flag. - `exact` also governs the `description` option, which matches the accessible *description* in the same way. ## Whitespace is normalised either way Before comparing, Playwright normalises whitespace on both sides: it trims the ends and collapses internal runs of whitespace to a single space. So a comment composer button written as ```html <button> Add comment </button> ``` has the accessible name `Add comment`, and `{ name: 'Add comment', exact: true }` matches it. `exact: true` means "the whole normalised string", not "the raw characters in the source". ## What goes wrong on a real page An issue board that renders `Save`, `Save and close` and `Save as draft` gives `page.getByRole('button', { name: 'Save' })` three matches. Playwright will happily count or assert over the set, but an action on it fails with an error listing the candidates rather than clicking the first one. The fixes, in order of preference: 1. Tighten the name: `{ name: 'Save', exact: true }` picks only the button named exactly `Save`. 2. Anchor with a pattern when the label is dynamic: `{ name: /^Save( \(\d+\))?$/ }`. 3. Scope the query to a container first, so the extra candidates are outside the search root. ## Choosing between exact and a pattern - Prefer the **default substring** when the label carries a volatile decoration — a count badge, a trailing icon whose text is part of the name, a trailing ellipsis. - Prefer **`exact: true`** when a shorter label is a prefix of a longer one on the same screen; that is precisely the `Save` / `Save and close` case. - Prefer a **`RegExp`** when you need anchoring plus tolerance, for example `/^Issue \d+$/` for a heading whose number changes per test run. - Avoid `exact: true` for user-visible copy that a product team rewords; the whole-string test is what breaks first when `Save` becomes `Save changes`. ## Case-insensitivity is a real behaviour, not a nicety Because the default is case-insensitive, `{ name: 'save' }` and `{ name: 'SAVE' }` behave identically. A candidate who assumes the string is compared with `===` will be surprised by extra matches and, worse, will "fix" an ambiguity by changing the case of the string, which changes nothing. The two knobs that actually change the match are `exact` and switching to a pattern. ## Reading the name, not the text One more trap sits behind this option: the value being compared is the **accessible name**, not `textContent`. An icon-only button labelled with `aria-label="Save"` has the name `Save` even though it contains no text at all, and a button whose visible text is `Save` but which carries `aria-label="Persist draft"` has the name `Persist draft` — the label wins, so `{ name: 'Save' }` does not match it. When a name-based match surprises you, the first thing to check is which of `aria-labelledby`, `aria-label`, a native label or the content actually produced the name.