When should a Cypress suite seed through cy.request() rather than cy.task()?

## Two doors, and what each one costs Cypress gives a spec exactly two ways to arrange state without driving the interface, and they are not interchangeable. - **`cy.request()`** speaks HTTP to a running server from Cypress's Node process. Whatever it creates goes through the application's own routing, validation and authorization, and any cookies the response sets land on the browser. - **`cy.task()`** hands an event name and one serializable argument to a handler running in the Node process that loaded your Cypress configuration. That handler can do anything Node can do: write to a database directly, drop a file on disk, call a cloud CLI, restore a snapshot. The judgement is not "which is faster". It is **how much of the application you are willing to route around, and what you take on by routing around it**. ## The case for the HTTP door Prefer `cy.request()` when an endpoint can express the state you need. - The record it creates is a record the application believes in. Required fields, defaults, derived totals and side effects such as an approval event all happen the way production does them. - It cannot drift out of step with the schema, because it does not know the schema. A migration that renames a column breaks the application and the seed at the same time, rather than leaving a seed that quietly writes rows nobody reads any more. - It carries the session: cookies the browser holds are attached, and `Set-Cookie` responses are written back, so the seeded state belongs to the identity the test will use. - The only knowledge it needs is the API surface, which the team already documents and versions. The costs are real but bounded: it can only reach states the API exposes, it is subject to whatever rate limits and validation the application enforces, and a multi-step setup becomes several round trips. ## The case for the Node door Reach for `cy.task()` when no endpoint can get you there, or when the setup is not HTTP at all. - States the product deliberately does not expose: an expense report already six months old, a reimbursement half-written by a job that crashed, a receipt whose file is corrupt. - Work that is not a request: restoring a snapshot, truncating tables, clearing a queue, invoking a database CLI, reading back what a download produced. - Anything that must persist between spec files, since the handler lives in one long-running Node process rather than in the browser. The costs are also real, and they are the ones teams underestimate: 1. **You bypass every invariant the application enforces.** A row written directly can be a shape the application can never produce, and the test then proves the application handles a state that cannot occur. 2. **It couples the suite to internals.** The handler knows the schema, the connection string, the file layout. Those change without an API version bump. 3. **It is a permanent extension point.** Each event name is a small piece of shared infrastructure somebody maintains, registered in Cypress's Node-events configuration. 4. **One serializable argument crosses the boundary**, so a rich setup becomes an ad-hoc payload format you now own. ## A rule of thumb worth defending | the state you need | door | why | |---|---|---| | something a user could create | `cy.request()` | the API already knows how, and enforces it | | something only time or a job produces | `cy.task()` | no endpoint exists to ask for it | | session or cookies for the test identity | `cy.request()` | cookies land on the browser automatically | | wholesale reset between runs | `cy.task()` | not an HTTP concern at all | | anything the interface must be proven to do | neither | drive it, or you are not testing it | The last row matters as much as the others. A backdoor that creates the very thing under test turns the test into a check that the read path renders a row. ## Standard-setting, not case-by-case choice Left to individual authors, both doors sprawl: one spec posts to five endpoints in sequence, the next writes rows directly because it was quicker that day, and nobody can say which states the suite is actually asserting on. The decision worth owning at team level is a default — *HTTP unless the state cannot be expressed through it* — plus a short, reviewed list of task names that are allowed to reach past the application, each with a stated reason. That keeps the Node surface small enough to understand and puts the burden of proof on the door that skips the application's own rules.