In Cypress, what happens when you make a spec's `it()` body an `async` function?

"Why can't I just use `async/await`?" is the question the Cypress docs answer with a whole section, because every engineer arriving from a promise-based runner tries it in the first hour. The honest answer has three parts: what an `async` body changes, what it does not change, and what people were actually reaching for. ## What an `async` body changes Cypress wraps every Mocha test function so it can decide what to give back to Mocha. The decision looks roughly like this: 1. Run the test body and capture its return value. 2. If the body returned a **promise-like** value, mark the test as having returned a custom promise, warn if commands were also enqueued, and return **that** promise to Mocha. 3. Otherwise, if commands were enqueued, return **Cypress's own command-queue promise** so Mocha waits for the queue to drain. An `async` function always returns a promise, so step 2 always wins. The consequence is the one that matters: **Mocha is now waiting on your `await` chain, not on Cypress's queue.** Cypress has given up its own end-of-test signal, which is exactly why the runner calls the pattern an anti-pattern rather than a style choice. The warning text is fixed and worth recognising in a console log: > Cypress detected that you returned a promise in a test, but also invoked one or more cy commands inside of that promise. It fires whether the commands were enqueued before the first `await` or after it resumes — as soon as the two are mixed, the warning appears. ## What an `async` body does not change - **Enqueue order is untouched.** `await cy.visit('/catalogue')` followed by `cy.get('[data-cy=book-row]')` runs in exactly the same order as the same two lines without `await`. - **Nothing becomes a real promise.** A Cypress command returns a chainer whose `.then` is itself a queued command, not a native promise reaction. There is no promise identity for `Promise.all` or `Promise.race` to work with. - **Retryability is unaffected by the keyword.** The retrying is done by queries and assertions inside the chain, and `await` neither adds nor removes it. - **The failure surface stays the same.** A failing command still fails the test through Cypress's own error path, not through a rejected promise you can inspect at the `await`. ## Cypress's chain versus a promise-based API | Concern | Cypress chain | What people expect from `await` | |---|---|---| | What a call returns | a chainer, queued for later | a promise settling with a value | | When the work happens | after the spec body yields | at the `await`, in written order | | How you read a value | inside `.then()` or an assertion | assigned straight to a variable | | What Mocha waits on | Cypress's command-queue promise | the test function's own promise | | Composition | more commands appended to the chain | `Promise.all`, `race`, `catch` | The right-hand column is not a missing feature; it is a different design. Cypress runs in the browser alongside the application and re-evaluates queries as the page changes, and a value pulled out into a variable at an `await` boundary is frozen at a single instant. ## Writing what you meant, in the chain Almost every `await` a newcomer writes is one of three intentions, and each has a chain form: - *"Wait for this before continuing"* — you already have it. Commands are serial by construction; delete the `await`. - *"Read this value"* — chain `.then(($el) => { … })` and use the value inside the callback. - *"Assert on this value"* — chain `.should('have.text', '3 copies available')` and let Cypress re-run the query until it holds. ## One place `await` is genuinely fine If a spec's `before` or `beforeEach` calls a plain asynchronous Node-free helper that touches **no** cy commands at all — say an imported function that builds a fixture object in memory — awaiting it is harmless, because no commands are enqueued and the mixing condition never arises. The moment a single `cy.` call joins that function, the warning is back and the queue-versus-promise split is back with it. Keeping those two worlds apart, rather than interleaving them, is the practical rule.