Expectation Styles

## The subject the callback receives Every Cypress command yields a **subject** to the next step in the chain. `.then(cb)` is the escape hatch that hands that subject to plain JavaScript: whatever the previous command produced arrives as the callback's first argument. After `cy.get('[data-cy=room-card]')` on a hotel room list, that argument is a **jQuery collection** wrapping every matched element — not a single element, and not a raw DOM node. After `cy.request()` it is the response object, after `cy.fixture('rooms')` the parsed fixture, after `.invoke('text')` a string. Inside the callback you are in ordinary synchronous JavaScript, so anything you could do to that value in a console you can do here. Cypress names the two assertion styles after the subject. A chained `.should('have.length', 4)` is an **implicit** assertion: Cypress supplies the subject for you. Writing `expect($rooms).to.have.length(4)` inside a callback is an **explicit** assertion: you name the subject yourself. This is the second form. ## Chai is already in the spec — both `expect` and `assert` You do not import an assertion library into a Cypress spec. Cypress bundles **Chai** and installs both of its interfaces as globals on the spec window: - `expect(value)` — Chai's BDD interface, the one nearly every Cypress example uses: `expect(rates).to.deep.equal([180, 210, 240, 320])`. - `assert` — Chai's TDD interface, so `assert.equal(actual, expected, message)` and its siblings work in the same callback if your team prefers that style. Two extensions ride along. **Chai-jQuery** teaches Chai about jQuery objects, which is why `expect($rooms).to.have.length(4)` and `expect($rooms.first()).to.contain('Deluxe King')` read naturally; **Sinon-Chai** adds the spy and stub chainers. A failing `expect` throws an `AssertionError`; Cypress catches the throw, fails the test at that command and renders the assertion in the Command Log. There is no accumulate-and-report mode — the first throw ends the test. Chai's `expect` also takes an optional message as its second argument, and Cypress surfaces it: `expect($rooms, 'four rooms listed').to.have.length(4)` labels that entry so a failure names the check instead of only printing two values. In a block with several assertions it is the cheapest possible diagnostics. ## Getting from a jQuery subject to the value you want | what you want | how you get it | |---|---| | how many rooms matched | `expect($rooms).to.have.length(4)` | | the text of one card | `expect($rooms.eq(0).text()).to.contain('Deluxe King')` | | a raw DOM node | `$rooms[0]`, then `.className`, `.dataset.rate`, `.textContent` | | every rate as a number | jQuery's `.toArray()`, then a plain `.map()` | | one attribute | `$rooms.eq(0).attr('data-rate')` — jQuery's `.attr()` | Two habits keep these blocks readable. Convert to plain JavaScript early: jQuery's `.toArray()` returns a real array, so `.map()`, `.filter()` and `.sort()` behave the way you expect. And assert on the computed value rather than on the collection, because Chai's failure output for a number or an array of strings is far easier to read than its output for a jQuery object. ## When an explicit block earns its place Reach for one when the check is not expressible as a single chainer: 1. **A computed value.** The nightly rate renders as `$210.00`, the assertion is about the number 210, and the parse has to live somewhere. 2. **A relationship between values.** The booking total equals the nightly rate times the number of nights the date picker spans — no built-in chainer relates two subjects. 3. **A group of checks on one snapshot.** Length, the first card's name, and the full list of room types, all asserted against the same query result. 4. **A shape the chainers do not cover.** Sort order, a numeric tolerance, a regular expression over a derived string. For anything a chainer already says — visibility, class, attribute, exact text — the chained form is shorter and reads better. Explicit blocks are the tool for the cases the vocabulary misses, not a replacement for it. ## The one cost to keep in mind `.then()` invokes its callback **once**. The moment the subject is available Cypress calls it, the assertions inside get a single attempt, and nothing above `.then()` in the chain re-runs. That is the right trade when the page has settled and the wrong trade when the value you are computing is still arriving — which is why the identical code moved into a `.should()` callback behaves differently.