How does a Cypress spec verify the suspension email the admin console sent?

## What the spec itself cannot see The suspension email is produced by the admin console's backend and handed to a mail provider. None of that happens in the browser. A Cypress spec runs inside the application's own page, so what it can observe is what the page can observe: the DOM, the page's own network activity, its storage, its globals. A mailbox, a message queue, an object store and a database are all outside that circle, and no Cypress setting widens it. This is the honest shape of the limit. It is not that the check is hard; it is that the browser half of Cypress is structurally the wrong place to make it, and every workaround that tries to make it there is a workaround around the wrong thing. ## Why cy.intercept() does not help here `cy.intercept()` is the reflex answer and it is wrong for this case. It sits on the traffic the browser generates. The request that matters — the console's backend calling the mail provider — never leaves the server, so there is no request for a route to match. You can, of course, assert on the request the **page** made: the `POST /environments/staging/suspend` that triggered the flow. That is a legitimate assertion, but it proves the button called the API, not that an email went out. If your suite only ever asserts on that, be honest in the test name about what is covered. ## The two doors, and what each costs | door | where it runs | good when | cost | |---|---|---|---| | `cy.task()` | Node, in the process that loaded the Cypress config | the check needs a client the browser cannot host, or credentials that must stay out of the browser | a handler to write and maintain in `setupNodeEvents`; failures surface in the terminal, not the page | | `cy.request()` | Node, as a plain HTTP call | the application or a test mail service already exposes an inbox endpoint | you depend on that endpoint existing and staying stable | Both run outside the browser, which is exactly the point: no CORS, no same-origin rule, no page to keep alive while you wait. ## Making the wait bounded A message arrives asynchronously, so the check is a poll — and a poll inside a task is the part people get wrong. A task must **end**; Cypress does not support handlers that run indefinitely, and the command fails once `taskTimeout` elapses. 1. Give the poll its **own deadline** inside the handler, shorter than the command timeout, and return `null` or throw a clear error when it expires. 2. Set the command's `timeout` option wider than that deadline — `cy.task('findSuspensionEmail', arg, { timeout: 30000 })` around a 20-second poll — so the failure you read is the handler's ("no message for [email protected] in 20s"), not the runner's generic task timeout. 3. Scope the search: filter by recipient and by a timestamp captured before the action, so a message left by an earlier test cannot satisfy the check. Without step 3 the test passes on someone else's email, which is worse than failing. ## What to return, and what to leave in Node Everything a task returns is serialised, so the payload has to be plain data: - **Return the parsed message** — subject, recipient, a text body, maybe an extracted link — not the provider's response object and never the client. - **Keep the client in module scope** inside `setupNodeEvents` so the connection and its credential live for the run and never enter the payload. - **Return `null`, not `undefined`,** when the handler has nothing to hand back; a handler returning nothing fails the command. - **Convert dates yourself.** A `Date` in the payload arrives in the spec as an ISO string, so decide the representation in the handler rather than discovering it in an assertion. One more thing worth stating plainly: as of Cypress 16 there is no `cy.exec()`. Suites that used to shell out to a mail CLI have to move that call inside a task, spawning the binary with Node's `child_process.execFileSync()` and an argument array. ## When to stop at the seam Having built the door, ask whether this particular check belongs behind it. A browser suite is expensive per test and its failures are read as UI failures. A notification contract is often better covered where the message is produced, with the browser suite asserting only the part the user sees — the confirmation banner and the environment's new state. A reasonable division is: the end-to-end suite proves the button suspends the environment and tells the operator so; a narrower test at the service boundary proves the suspension emits the message. If the team wants one test that spans both, put it behind a task, keep it to one flow rather than every notification, and accept that it will be among the slowest and most fragile tests you own.