Filtering and Chaining

## What `filter` actually returns `locator.filter(options)` takes a locator that **already matches a set of elements** and returns a **new locator** matching a subset of that same set. It never descends. If `page.getByRole('listitem')` matches every issue card in a board column, then `.filter({ hasText: 'Blocked' })` still matches *list items* — there are just fewer of them. The element you end up holding is the card, not the status pill inside it that carried the word. Locators in Playwright are immutable **descriptions**, not results. `filter` builds a longer description and hands it back; the locator you called it on is unchanged and still usable, and nothing has touched the DOM yet. The page is queried only when you act on the locator, assert against it, or read from it. That is why the following is safe and idiomatic: ```ts const cards = page.getByTestId('issue-card'); const blocked = cards.filter({ hasText: 'Blocked' }); const mine = cards.filter({ hasText: 'Assigned to me' }); ``` `cards` still matches all of them. ## How `hasText` matches `hasText` searches the element's **entire rendered subtree**, not just its own text node. An issue card whose label deep inside reads `Blocked` matches `filter({ hasText: 'Blocked' })` even though the card element owns no text of its own. With a **string** argument: - matching is **case-insensitive**, so `'blocked'` finds `Blocked`; - matching is a **substring** test, so `'Block'` finds `Blocked by #412`; - whitespace is normalized, so markup line breaks and indentation do not defeat a match. With a **RegExp** argument you get exactly your pattern's semantics — anchors, character classes, and case sensitivity unless you add the `i` flag. That is the escape hatch when the loose string rules match too much. | What you want | What to pass | |---|---| | any card mentioning the word | `filter({ hasText: 'blocked' })` | | a card whose text is exactly that | `filter({ hasText: /^Blocked$/ })` | | a case-sensitive substring | `filter({ hasText: /Blocked/ })` | | cards that never mention it | `filter({ hasNotText: 'Blocked' })` | `hasNotText` is the exact complement: same subtree search, same case-insensitive substring rules, inverted verdict. ## Stacking conditions `filter` is chainable, and each call intersects with the previous one. Reading an issue board, the two calls below compose into "cards that mention Blocked and do not mention Draft": 1. start from the widest honest set — `page.getByTestId('issue-card')`; 2. narrow by what the card says — `.filter({ hasText: 'Blocked' })`; 3. narrow again by what it must not say — `.filter({ hasNotText: 'Draft' })`. Order does not change the result set, because each step is a set intersection. It does change how the locator reads in a failure message, so put the most meaningful condition first. ## The nesting trap Because `hasText` looks at the whole subtree, an **ancestor also matches**. On a board where the column element wraps the cards, `page.locator('div').filter({ hasText: 'Blocked' })` matches the card *and* the column *and* the board wrapper — every ancestor contains that text. The fix is not a better text pattern; it is a tighter starting locator. Filter narrows what you already chose, so a sloppy starting set stays sloppy. ## Where candidates go wrong - Believing `filter` mutates the locator it was called on — it returns a new one. - Expecting `filter({ hasText })` to hand back the matching text node rather than the outer element. - Assuming a string is an exact, case-sensitive comparison; it is a case-insensitive substring test. - Filtering a set that was never narrow enough, then blaming the text match for the extra ancestors. - Reaching for `filter` when the goal is to reach an element *inside* the match — that is chaining, not filtering. Everything above is a description-building step, so it costs nothing at construction time and carries no timeout of its own. The waiting, retrying and timing out happen later, when the locator is finally used.