Canned Inputs

## What was removed, and what happens if you call it `cy.exec()` is gone as of Cypress **16.0.0**. It was deprecated in `15.21.0` and removed in the next major. Calling it in a spec no longer runs anything: the driver throws immediately with *"`cy.exec()` was removed in Cypress version 16.0.0. Please update to use `cy.task()` instead, which runs in Node and does not depend on the operating system, shell, or terminal of the machine running Cypress."* The `execTimeout` configuration option went with it. Cypress prints a warning saying it was removed in 16.0.0 and then ignores the value, so a configuration that still carries `execTimeout: 120000` bounds nothing at all. Delete it and reach for `taskTimeout` instead. This is worth knowing precisely, because a large share of published Cypress material still opens its seeding section with `cy.exec('npm run db:reset')`. On Cypress 16 that line is a hard failure at the moment the command runs, not a deprecation notice you can defer. ## Why the shell door was closed `cy.exec()` ran a command **through the shell on the machine running Cypress**, which made a test's setup step depend on things a test has no business depending on: - the operating system, and therefore which quoting and escaping rules apply to the command string - which shell is configured, and whether its login profile has been sourced - whether a terminal is attached — different on a developer laptop than under a CI runner - `PATH` resolution for the binary named in the string - the output contract: you received `stdout` as text and had to parse a value back out of it `cy.task()` has none of that surface. Its handler runs in the **Node process that loaded your Cypress configuration**, so there is no shell, no per-platform quoting, no `PATH` guessing — and the value the handler returns arrives in the spec as a value, not as text. ## The replacement, end to end 1. Register a handler for the `task` event inside `setupNodeEvents`, keyed by an event name of your choosing (`'seedExpenseReport'`, `'resetExpenseLedger'`). 2. Call `cy.task(event)`, `cy.task(event, arg)` or `cy.task(event, arg, options)` from the spec. 3. Consume the yielded value with `.then()`, `.its()` or a chained assertion. From the spec's side, the only contract is the event name and whatever comes back; the handler itself lives with the rest of your Cypress configuration. | Cypress 15 and earlier | Cypress 16 | |---|---| | `cy.exec('node seed-expenses.js')` | `cy.task('seedExpenseReport', payload)` | | yields `{ stdout, stderr, exitCode }` | yields whatever the handler returned | | `execTimeout` bounds it | `taskTimeout` bounds it, default `60000` ms | | runs in a shell on the host machine | runs in Cypress's own Node process | | output is text the spec must parse | value arrives already structured | ## The contract `cy.task()` imposes - **The handler must return something.** Returning `undefined` fails the command with *"The task 'X' returned undefined. You must return a value, null, or a promise that resolves to a value or null to indicate that the task was handled."* Return `null` explicitly when there is nothing to hand back. - **An unregistered event name fails too**, and the error lists every task name that *is* registered, which makes a typo obvious rather than mysterious. - **Exactly one argument crosses the boundary.** `cy.task(name, arg, options)` has room for a single `arg`; pass an object and destructure it on the Node side when you need several values. - **The argument is serialized with `JSON.stringify()`.** Functions, regular expressions and symbols are omitted to `null`, and a `Date` arrives on the other side as a string. ## What if the thing you need to run is not Node? Spawn it from inside the handler. Node's `child_process.execFileSync` with an argument array — `execFileSync('docker', ['exec', 'db', 'reset-script'])` — runs the binary directly and skips the shell, which is exactly the property whose absence made `cy.exec()` unreliable. The difference is that the spawning is now explicit, lives in one place instead of scattered through specs, and the task can hand the spec a real value rather than a blob of stdout. ## What this looks like in an expense-report suite A suite that used to shell out to reset the ledger and then scrape a report id out of stdout now calls `cy.task('resetExpenseLedger')` followed by `cy.task('seedExpenseReport', { employee: 'jane', total: 42.5 })`, and the second call yields the created report object. The spec goes straight to `cy.visit('/reports/' + report.id)` with no string parsing, no `.trim()`, and no guessing about which shell CI happened to give it.