A Cypress cy.task() seeding a database times out after 60 seconds - what do you do?

## What the timeout actually is `cy.task()` is bounded by `taskTimeout`, which defaults to **60000 ms**. When the handler has not settled by then, Cypress fails the test with *"`cy.task('seedExpenseLedger')` timed out after waiting `60000ms`."* Nothing is retried: `cy.task()` runs its chained assertions once and does not retry, and the timeout is not `defaultCommandTimeout` — a task has its own budget precisely because it is doing work in Node rather than re-querying the DOM. There are four places to change it, in increasing scope: 1. `cy.task('seedExpenseLedger', payload, { timeout: 120000 })` — a per-call `options` object, which is what the third argument to `cy.task(event, arg, options)` is for. 2. A test configuration object on a block: `describe('reimbursement run', { taskTimeout: 120000 }, () => { ... })`. It applies for the duration of that suite or test and reverts afterwards. 3. `Cypress.config('taskTimeout', 120000)` inside a spec, which holds for the rest of that spec. 4. `taskTimeout` in the Cypress configuration file, which changes it for every task everywhere. ## Diagnose before you raise it A number that only fails in CI is usually telling you something about the environment, not about the number. Work through this before touching the config: - **Is the work the same size?** A local database with fifty expense reports and a CI database restored from a large snapshot are not the same job. Seed the minimum the test needs. - **Is it waiting on something, not working?** A task that opens a database connection to a service that is still starting will sit there until the timeout, then blame itself. That is a startup ordering problem. - **Does it ever end?** Cypress does not support tasks that do not end — starting a web server, watching for file changes, or anything you would normally stop by hand. The documentation calls starting a web server an anti-pattern explicitly. A never-ending task will always hit the timeout, and raising the number just makes the failure slower. - **Is it one task or many?** A `beforeEach` that fires three tasks pays each timeout separately, and the wall-clock cost lands on every test in the file. - **Is it failing or hanging?** If the handler throws, Cypress reports the error with a `From Node.js Internals` section on the stack instead of a timeout. A timeout means it never settled. ## Why a long task is expensive beyond itself Cypress will not run any other command while `cy.task()` is outstanding. The command queue is drained serially, so a ninety-second seed is ninety seconds of a test doing nothing, multiplied by however many tests and however many spec files run it. The documentation is direct about this: it does not recommend executing tasks that take a long time to exit. That is the real reason to treat a raised `taskTimeout` as a last resort rather than a fix. | symptom | likely cause | what to change | |---|---|---| | times out in CI, fine locally | larger dataset or cold dependency | seed less; wait for the dependency to be ready | | times out everywhere, always | the task never ends | restructure it; do not start servers from a task | | slow but passes | genuine heavy setup | move it to a `before` hook, or raise the per-call timeout | | fails fast with a Node stack | the handler threw | fix the handler; the timeout is not involved | ## Choosing the smallest scope that works Prefer the **narrowest** override that solves the problem. A per-call `{ timeout: 120000 }` on the one snapshot-restore task documents which step is slow and leaves every other task on the default, where a genuine hang still fails in a minute. A global `taskTimeout: 300000` in the configuration file does the opposite: it hides hangs across the whole suite and turns every stuck task into a five-minute stall in CI. - Per-call for one known-slow step. - Suite-level test configuration when a whole file shares heavy setup, such as a reimbursement run. - Global only when the default is genuinely wrong for your project as a whole. ## Restructuring beats raising Where the work is genuinely large, the useful moves are structural rather than numeric: - Run the expensive restore once in Mocha's `before` for the file instead of `beforeEach`, so the cost is paid once rather than per test. - Split one do-everything task into a cheap per-test seed and a rare heavy reset. - Have the task return early when the state it would create already exists, so reruns are cheap. - If the slow part is an external tool, spawn it inside the handler with Node's `child_process.execFileSync` and return only what the spec needs, rather than streaming output through the boundary.