In Cypress, how does `cy.contains()` choose which element to yield, and what does a selector argument change?

## The rule: first deepest, then promoted `cy.contains('Book now')` searches the current subject for the text — the whole `document` when it starts a chain — and yields **exactly one** element. The base rule is *first deepest match*: of the elements containing that text, Cypress walks to the deepest one, since `<html>`, `<body>` and every wrapper technically contain it too. Then it applies one override. If that deepest element sits inside one of four preferred tags, Cypress yields the **wrapper** instead: - `input[type='submit']` - `button` - `a` - `label` So for a room card marked up as `<button class="book"><span>Book now</span></button>`, Cypress yields the `<button>`, not the `<span>`. That is almost always what you wanted, because the next thing you write is a click, and clicking the span inside a button is a worse test than clicking the button. ```html <li class="room-card"> <h3>Deluxe Double</h3> <button class="book"><span>Book now</span></button> </li> ``` ```js cy.contains('Book now') // yields <button class="book"> cy.contains('span', 'Book now') // yields <span>, preference switched off cy.contains('.room-card', 'Deluxe Double') // yields the <li> ``` ## What the selector argument changes The two-argument form is `cy.contains(selector, content)` — **selector first, text second**, which is the order people most often get backwards. It does two things at once: 1. It filters the candidates to elements matching the selector. 2. It **turns the tag preference order off**, because you have now said explicitly which element you want. That is how you keep a shallower element as the subject. `cy.contains('.room-card', 'Deluxe Double')` yields the whole card, so the next command in the chain operates on the card rather than on the `<h3>` buried inside it. | form | yields | preference order | |---|---|---| | `cy.contains('Book now')` | first deepest match, promoted to a preferred wrapper | applied | | `cy.contains('.book', 'Book now')` | first match that is also `.book` | ignored | | `cy.get('.room-card').contains('Book now')` | first deepest match **inside that card** | applied | ## Matching: case, whitespace and regular expressions - Matching is a **case-sensitive substring** match by default, over normalized whitespace. `{ matchCase: false }` relaxes it: `cy.contains('deluxe double', { matchCase: false })` finds the card. - A `RegExp` gives you anchoring and patterns: `cy.contains('.room-card', /^Deluxe/)` matches only cards whose text begins with *Deluxe*. - The two combine, with one rule. If you pass `{ matchCase: false }` and the regex has no `i` flag, Cypress adds it for you. If you pass `{ matchCase: true }` alongside a regex that already carries `i`, Cypress rejects the call — those options contradict each other, so it asks you to choose one. - A number is allowed and is treated as text: `cy.contains(2)` finds the guest-count badge. - `<pre>` is the exception to whitespace normalization: leading, trailing and repeated spaces inside a `<pre>` are significant, and your search string has to match them. There is no negated form. Asking for the elements that do *not* contain a piece of text is a different job, done by filtering a set you already hold rather than by `cy.contains()`. ## Only ever the first match This is the half people forget. `cy.get()` yields every match; `cy.contains()` yields **one**. On a room list where three cards mention *Sea view* in their description, `cy.contains('Sea view')` yields the first one in document order and says nothing about the other two. It cannot fail with "matched three elements", because matching three elements is not an error condition for it — which means a text query that is less specific than its author believed produces a green test that acted on the wrong card rather than a loud failure. One special case is worth knowing: an `<input type="submit">` with no `value` attribute renders a browser-supplied, locale-dependent label. Its `value` is the empty string, and Cypress has no way to read the label the user sees, so `cy.contains('Submit')` will not find it. Set an explicit `value` on the element, or assert `cy.get('input').should('have.value', '')` and target it another way. ## The chaining trap `.contains()` behaves differently depending on whether it starts a chain or continues one, and this is where suites go wrong: ```js // wrong: the second contains searches INSIDE the Book now button cy.contains('Book now').click().contains('Confirm booking').click() // right: cy starts a fresh search from the document again cy.contains('Book now').click() cy.contains('Confirm booking').click() ``` Chained off a subject, `.contains()` searches within that subject. After a click on the *Book now* button, the subject is still that button, and *Confirm booking* is nowhere inside it — so the command fails on a confirmation dialog that is plainly on screen. Starting a new `cy` chain resets the search to the document. ## What to say in an interview Three sentences cover it: `cy.contains()` yields one element, the first deepest match promoted to a wrapping submit input, button, anchor or label; the two-argument form is selector-then-text and turns that promotion off; and chaining it off an existing subject scopes the search to that subject rather than the page. The follow-up is nearly always about case sensitivity — the default is sensitive, and `{ matchCase: false }` or a regex is how you loosen it.