Heuristic:Cypress io Cypress Timeout Tuning
| Knowledge Sources | |
|---|---|
| Domains | Testing, Debugging, Performance |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Cypress uses distinct timeout values for different operations (command: 4s, request: 5s, response: 30s, page load: 60s). Understanding and tuning these prevents flaky tests and false failures.
Description
Cypress has four primary timeout categories, each with a different default value tuned for its use case. The defaultCommandTimeout (4000ms) controls how long `cy.get()` and other DOM commands retry. The requestTimeout (5000ms) is how long to wait for an XHR/fetch request to leave the browser. The responseTimeout (30000ms) is how long to wait for a server response. The pageLoadTimeout (60000ms) is how long to wait for `window.load`. Additionally, the server-side request module uses its own retry intervals of `[3000, 3000, 4000]` ms for internal HTTP requests.
Usage
Apply this heuristic when tests are timing out intermittently (flaky tests), testing slow APIs or SPAs, running in resource-constrained CI environments (Docker, shared runners), or debugging "timed out waiting for" errors. Incorrect timeout values are the #1 cause of flaky Cypress tests.
The Insight (Rule of Thumb)
- Action: Increase `responseTimeout` for slow APIs and `defaultCommandTimeout` for slow-rendering SPAs. Do NOT increase timeouts globally — use per-test overrides.
- Value: Defaults: commandTimeout=4000, requestTimeout=5000, responseTimeout=30000, pageLoadTimeout=60000
- Trade-off: Higher timeouts reduce flakiness but increase the time to detect genuine failures. Per-test overrides are preferable to global changes.
Reasoning
The default values are calibrated for typical web applications. SPAs with heavy client-side rendering may need higher `defaultCommandTimeout`. APIs with cold starts or heavy processing may need higher `responseTimeout`. CI environments with limited CPU/memory may need all timeouts increased by 2-3x. The server-side retry intervals (`[3000, 3000, 4000]`) provide built-in resilience for the internal proxy's connection to the application under test.
Code Evidence
Timeout defaults from `packages/config/src/options.ts`:
// defaultCommandTimeout - line ~180
{ name: 'defaultCommandTimeout', defaultValue: 4000 }
// requestTimeout - line 364-365
{ name: 'requestTimeout', defaultValue: 5000 }
// responseTimeout - line 377-378
{ name: 'responseTimeout', defaultValue: 30000 }
// pageLoadTimeout - line 336
{ name: 'pageLoadTimeout', defaultValue: 60000 }
Server-side retry intervals from `packages/server/lib/server-base.ts:738`:
retryIntervals: [3000, 3000, 4000],
Chrome focus/blur timeout bug from `packages/driver/src/cypress/error_messages.ts:157`:
timed_out: {
message: `${cmd('blur')} timed out because your browser did not receive any \`blur\` events. This is a known bug in Chrome when it is not the currently focused window.`,
}