In Cypress, what happens if a .then() callback returns a Cypress.Promise?

## The queue is not a promise chain The first thing to be clear about is what Cypress's `.then()` is **not**. Cypress commands and queries look promise-like because of the method name, but they are serial steps passed into a central queue and drained by the runner. The documentation says so explicitly, and adds that commands cannot be awaited. `.then()` is a queued step that happens to take a callback. So the queue's ordering is not produced by promise resolution at all. It is produced by the runner walking its list. Any promise you create in the test body settles on its own schedule, and the queue is not watching it. ## What `Cypress.Promise` actually is Cypress bundles the **Bluebird** promise library and exposes it as `Cypress.Promise`. Two things follow from that: - You construct one with `new Cypress.Promise((resolve, reject) => { ... })`. - It lives on the `Cypress` object, not on `cy`. `new cy.Promise(...)` errors, because `cy` carries the chainable command API while `Cypress` carries the utilities and configuration — `Cypress.Promise`, `Cypress.$`, `Cypress._`, `Cypress.config()` and the rest. Because it is Bluebird, it also carries Bluebird's own API surface beyond the promise standard, which matters for the rejection story below. ## A promise returned from inside a queued step Here is the part that does affect ordering. **Cypress is promise-aware inside a step.** If the callback you pass to a queued command like `.then()` returns a promise, Cypress will not start the next queued command until that promise settles. That gives you one legitimate seam for genuine asynchronous work in a spec: - Work that is not a Cypress command — a call into a library, a browser API, a helper in your own test code — can be wrapped in a promise and returned from a step. - The queue then holds at that step, and the following commands stay in their positions behind it. - A native `Promise` behaves the same way; `Cypress.Promise` is simply the build Cypress ships, so you do not have to add one. The distinction that catches people is **where** the promise is returned from. A promise created at the top of the test body is created during the body phase and settles whenever it likes; nothing in the queue defers to it. The same promise returned from inside a step is something the runner is holding, and the drain waits. | where the promise lives | does the queue wait for it? | |---|---| | created in the test body, not returned anywhere | no — it settles on its own | | returned from a `.then()` callback | yes — the next step waits for it to settle | | created inside a step but not returned | no — the step finishes without it | | rejected anywhere outside a step's return value | no — and the test is not failed either | ## Rejections outside the queue do not fail the test This is the operationally important corner, and it is the one that produces a green suite that proves nothing. **If test code has an unhandled rejected promise, Cypress does not automatically fail the test.** A helper that was supposed to prepare the catalogue can reject, do nothing it claimed to do, and leave the spec passing on assertions that happened to hold anyway. There are two documented ways to surface it, and both are registrations you make once rather than per test: 1. For promises built with `Cypress.Promise`, register Bluebird's handler: `Cypress.Promise.onPossiblyUnhandledRejection((error) => { throw error })`. 2. For native promises, add the browser's own listener on the test window: `window.addEventListener('unhandledrejection', (event) => { throw event.reason })`. The second one comes with a wrinkle worth knowing: because it is registered on the test window, such listeners are **not** reset before every test, so you register it a single time — Mocha's `before` hook in the spec file is the usual place — rather than adding a duplicate for each test. ## When to reach for it, and when not to - **Do** use it to bridge one piece of genuinely asynchronous non-Cypress work into the queue's ordering, returned from a step so the runner owns it. - **Do not** use it to rebuild control flow that the command queue deliberately does not offer. Wrapping a chain in a promise does not give you error recovery, and it does not let you run two commands at once. - **Do not** reach for it where a Cypress command already exists. A step the runner understands is visible, timed and reported; a promise you hand-rolled is none of those. - **Be suspicious of raw promises accumulating in a spec.** Every one that the queue does not own is a place where the suite can report success without having done the work.