In Cypress, how do `.find()`, `.filter()` and `.children()` differ on a set of elements?

## Two different moves: descend, or narrow Once a Cypress query has yielded a set of elements, there are only two things the next query can do to it: **go down into the elements**, or **keep some of the elements you already have**. Confusing the two is the most common traversal bug on a list page. - **Descend** — `.find(selector)` searches the descendants of every element in the set, and never matches the elements themselves. `.children(selector)` does the same but stops at direct children. - **Narrow** — `.filter(selector)` keeps the elements of the current set that match, and `.not(selector)` keeps the ones that do not. The set stays at the same level of the tree. On a room list, `cy.get('.room-card')` yields one element per card. `.find('.book-btn')` then yields one button per card, one level down. `.filter('[data-available="true"]')` yields fewer cards, at the same level. Neither can do the other's job. ## The command map | query | direction | matches | typical use | |---|---|---|---| | `.find(sel)` | down, any depth | descendants only | reach a price inside each card | | `.children(sel)` | down, one level | direct children only | rows immediately under a `<tbody>` | | `.filter(sel)` | sideways | elements already in the set | keep only bookable cards | | `.not(sel)` | sideways | elements not matching | drop the sold-out cards | | `.eq(n)` | sideways | one element by index | the third card | | `.first()` / `.last()` | sideways | one element by position | the first card | `.find()`, `.filter()`, `.not()`, `.children()` and `.first()` follow jQuery's semantics exactly, so a jQuery habit transfers — including the one below, which is where it bites. ## The classic mistake ```javascript // yields nothing: .find() never matches the elements it started from cy.get('.room-card').find('.room-card') // yields the cards that are bookable cy.get('.room-card').filter('[data-available="true"]') ``` Because `.find()` excludes the subject set itself, any selector that describes the *current* elements rather than something inside them must go through `.filter()` or `.not()`. The failure is loud — the query times out with `Expected to find element: '.room-card', but never found it` — but the message points at the selector, not at the wrong command, so it reads as a missing element. ## Positional narrowing `.eq(n)` is zero-based, and it also accepts a negative index counted from the end, so `.eq(-1)` and `.last()` pick the same element. Positional narrowing is the cheapest way to satisfy commands that insist on a single element: 1. Action commands such as `.click()` and `.type()` need exactly one element. 2. `.within()` needs exactly one element and says so in its error. 3. `.shadow()` is happiest on a single host. The caveat is that an index encodes render order, so it is only as stable as the order of the list under test. Narrowing by content — `cy.contains('.room-card', 'Deluxe King')` — or by an attribute the component owns says what you mean and survives a re-sort. ## Narrowing is a query, so it re-runs As of Cypress 16 all of these are **queries**: they retry, they honour `defaultCommandTimeout`, and they are safe to chain further commands onto. Two consequences follow: - When an assertion at the end of a chain retries, the *whole* chain of queries re-runs from its start, so `cy.get('.room-card').filter('[data-available]').first()` re-evaluates the filter against the current DOM on every attempt rather than replaying a stale set. - A filter that matches nothing does not fail on the spot; it keeps retrying until the timeout, and the failure surfaces on the assertion or action at the end of the chain. ## The rest of the family: up and across Descending and narrowing are two of three directions. The same set of queries also walks **upward** and **sideways**, and the distinctions there are the ones people most often blur: - `.parent()` goes exactly one level up; `.parents()` goes all the way up and yields every ancestor, optionally filtered by a selector. - `.closest(sel)` walks up and stops at the **first** match — and, unlike `.parents()`, it will match the element itself if the element matches. That is what makes `cy.contains('Deluxe King').closest('.room-card')` the idiomatic way to get from a piece of text back to the card that contains it. - `.siblings(sel)` yields the other children of the same parent, which is how you reach the price cell in the same row as the label you just matched. Put together, the common shape on a list page is *find something identifiable, walk up to its container, then descend again*: `cy.contains('Deluxe King').closest('.room-card').find('.book-btn')`. ## Choosing between them - If the selector describes something **inside** what you have, use `.find()` — or `.children()` when you specifically mean one level and want to exclude deeper matches. - If it describes **which of the things you have** you want, use `.filter()` or `.not()`. - If it describes **how many** or **which position**, use `.first()`, `.last()` or `.eq(n)`. - If you are about to write `.find()` with the same selector you just used in `cy.get()`, you almost certainly wanted `.filter()`.