In Playwright, what is the difference between locator.and() and locator.or() when combining two locators?

## `and()` is an intersection `locator.and(other)` returns a locator matching the elements that satisfy **both** descriptions at once — the same DOM node has to match each side. It is the tool for pinning an element down by two independent properties when neither alone is unique: ```ts const archive = page.getByRole('button').and(page.getByTitle('Archive issue')); ``` That is "a button that is also titled Archive issue". On an issue detail page carrying several buttons and several elements with that title, the intersection is unique where each half is not. Because both sides describe the *same* element, `and()` cannot express "a card containing a button" — a card is not a button. That is a subtree relationship, and it belongs to `filter({ has })`. ## `or()` is a union `locator.or(other)` matches elements that satisfy **either** description, or both. Its real job is handling a branch you cannot predict: ```ts const newIssue = page.getByRole('button', { name: 'New issue' }); const consent = page.getByText('Confirm workspace settings'); await expect(newIssue.or(consent).first()).toBeVisible(); if (await consent.isVisible()) await page.getByRole('button', { name: 'Dismiss' }).click(); await newIssue.click(); ``` Without `or()` you would wait on one alternative, time out on the runs where the other appeared, and paper over it with a sleep. With it, the test waits for *whichever* arrives and then branches on what it actually got. ## Side by side | | `and()` | `or()` | |---|---|---| | Set operation | intersection | union | | Matches | elements satisfying both | elements satisfying either | | Typical size | narrows a set | widens a set | | Typical use | disambiguate one element | wait for one of two outcomes | | Cross-frame argument | rejected | rejected | Both throw when the argument locator belongs to a different frame — the message is `Locators must belong to the same frame.` Both are ordinary locator builders: they construct a description and query nothing until the result is used. ## The strictness caveat on `or()` When **both** alternatives are present on the page, an `or()` locator matches two elements. Any action on it then hits the one-match rule and fails. That is why the branching pattern above ends in `.first()` for the wait and then acts on the specific locator once the branch is known. Two habits follow: - use `or()` to **wait**, then act on the concrete locator you resolved to; - if you must act through the union directly, narrow it first. ## When `and()` is not the right answer `and()` is genuinely useful, but a lot of reaches for it are really something else: 1. **You want the container, tested by a descendant** — that is `filter({ has })`, not `and()`. 2. **You want the descendant, inside a container** — that is chaining, `container.locator(inner)`. 3. **You want text as one of the two conditions** — `filter({ hasText })` says it more directly, and reads better in a failure message. The honest use for `and()` is two *element-level* properties on one node, such as role plus title, or a role plus a test id owned by a design system. ## Reading them in failure output Both operators show up in the generated locator description, so a failing step names what you asked for. That is a small but real argument for reaching for `and()` or `or()` rather than hand-rolling the same logic in JavaScript with `count()` and an `if`: the intent stays in the locator, where the report can print it, instead of dissolving into control flow the reporter cannot see. ## Nothing is queried until you use it Both are ordinary builder methods. `and()` and `or()` combine two descriptions and return a third; no request reaches the page, no timeout starts, and no error is raised because a match is currently absent. Everything that waits happens later, when the combined locator is clicked, asserted on, or read from. Two practical consequences follow: - You can define combined locators at the top of a test, or in a shared module, without caring whether the page has rendered yet. - A combined locator that matches nothing is not an error at construction time — it becomes a timeout at the step that uses it, and the step's description will show both halves. The one thing checked eagerly is the frame. Because a locator carries the frame it was built against, passing an argument from another frame is rejected at the moment you combine them rather than at first use. ## A worked choice on an issue tracker Suppose the issue detail page has a toolbar of icon buttons, all with the same role, distinguished only by their `title`. Ask the three questions in order: 1. **Is the target a single element with two properties?** Yes — a button that is titled `Archive issue`. Use `and()`. 2. **Is the target a container identified by something inside it?** If instead you wanted the toolbar group holding that button, that is `filter({ has: … })`. 3. **Is the target one of two possible outcomes?** If archiving sometimes opens a confirmation instead, wait on `confirm.or(toast).first()` and branch. Answering those in order keeps you from reaching for a combinator where a filter or a chain says the same thing more plainly.