Limits of Retrying

## Queries retry; `.then()` does not Cypress splits what you chain off `cy` into kinds, and retry-ability follows that split. **Queries** such as `cy.get()`, `.find()` and `.eq()` link together and re-run as a unit. `.then()` is not one of them: it is a callback step that executes **once**, when the previous step yields it a subject. Nothing before a `.then()` re-runs after it has executed, and the callback itself is never invoked a second time on behalf of a later assertion. That is the whole mechanism behind a failure that reads like a Cypress bug and is not one. ## Walking a chain that cannot pass A library catalogue renders a placeholder in the copies counter and fills in the real number after a request comes back roughly a second later: ```javascript cy.get('[data-testid="copies-available"]') // the <span>, containing a dash .invoke('text') // '-' .then(parseFloat) // NaN .should('be.gte', 1) // retries against NaN, then fails ``` | Step | First execution | On each retry of the final assertion | |---|---|---| | `cy.get('[data-testid="copies-available"]')` | yields the `<span>` | not re-run | | `.invoke('text')` | yields the placeholder text | not re-run | | `.then(parseFloat)` | yields `NaN` | not re-run | | `.should('be.gte', 1)` | fails | re-evaluated against the same `NaN` | The assertion is doing its job perfectly. It retries for the full `defaultCommandTimeout`, and every retry compares the *same frozen value*, because the steps that could have produced a fresher one are behind a `.then()` that already ran. ## The fix: put the work inside `.should(callback)` `.should()` accepts a callback, and Cypress retries the entire chain leading up to it plus every expectation inside it until none of them throws: ```javascript cy.get('[data-testid="copies-available"]').should(($span) => { const copies = parseFloat($span.text()) // re-read on every attempt expect(copies).to.be.gte(1) // Chai's expect }) ``` Two constraints on that callback are worth knowing: - It must be **side-effect free**, because it will run many times. - You **cannot invoke Cypress commands inside it** — no `cy.get()`, no `cy.log()`. Put commands before or after the `.should()`. ## Where this bites in real suites - **Parsing or reshaping a value** — `.invoke('text').then(Number)`, trimming a currency symbol, splitting a "3 of 12" label. All of it freezes at the moment `.then()` ran. - **Asserting on a spy or stub inside `.then()`** — the callback fires before the application has finished calling it. Alias the spy with `.as()` and assert through `cy.get('@alias')` instead, so the assertion retries. - **Doing several actions on an element captured in a `.then()` closure** — the captured element can be replaced by a re-render between them, and `.then()` adds no protection against that. - **Branching on what the page currently shows** — a `.then()` sees one snapshot of the application, taken once, at whatever moment the queue reached it. ## The same chain without the `.then()` Delete the callback and the chain retries end to end, because everything left in it is a query followed by an assertion: ```javascript cy.get('[data-testid="copies-available"]') .invoke('text') .should('match', /^[1-9]/) // Chai's match; the whole chain re-runs ``` A failing assertion here sends Cypress back to `cy.get()`, which re-reads the element, and `.invoke('text')` reads the current text again on every attempt. The only difference between this chain and the one that can never pass is the `.then()` sitting in the middle of it — which is also the cheapest way to convince yourself where the boundary is. Remove the callback and watch the same assertion start passing. When the reshaping genuinely cannot be expressed as an assertion on the raw value — parsing, arithmetic, comparing two numbers read from the page — the callback form of `.should()` is the tool for it, not `.then()`. ## Rules of thumb 1. If the value must be re-read until it settles, it belongs **inside** a `.should(callback)`, not behind a `.then()`. 2. Use `.then()` for work that is genuinely one-shot: reading a value you will pass to another command, or asserting on something that is already final. 3. When a chain "won't wait", look for the first non-query step in it before you reach for a longer timeout — a longer timeout only means retrying the same frozen value for longer.