feat: add global test timeout configuration option

[omer-za]

Summary

This PR adds a new testTimeout configuration option that allows setting a global maximum duration for tests. Unlike existing command-level timeouts (defaultCommandTimeout, responseTimeout, etc.), this option limits the total duration of a test including all its hooks.

Problem

Currently, Cypress has no way to enforce a global test timeout. Each individual command has its own timeout, but a test could theoretically run indefinitely if each command completes within its respective timeout. Users have requested the ability to fail tests that exceed a certain total duration.

Solution

Add a new testTimeout configuration option:

• Default value: 0 (disabled, for backward compatibility)
• Behavior: If a test (including beforeEach/afterEach hooks) exceeds this duration, it fails automatically
• Override level: Can be set globally or per-test via it('test', { testTimeout: 30000 }, ...)
• Diagnostics: When timeout occurs, detailed diagnostic information is logged to help debugging

Example Usage

// cypress.config.js
module.exports = defineConfig({
  testTimeout: 60000, // 60 seconds max per test
})

// Or per-test
it('my test', { testTimeout: 30000 }, () => {
  // test code
})

Diagnostics on Timeout

When a test times out, the following diagnostic information is captured and logged to the browser console:

• Current Command: The command that was executing when timeout occurred
• Command Queue: List of all commands (last 20) that were queued
• Recent Logs: Last 10 log entries with their state
• Current URL: The URL the test was on
• Aliases: All registered aliases

Example console output:

🕐 Global Test Timeout Diagnostics
  Test: should load the page
  Timeout: 5000 ms
  Elapsed: 5001 ms
  Current Command: get
  Command Queue: visit → get → should → click → get
  Current URL: http://localhost:3000/dashboard
  Full diagnostics: { ... }

The diagnostics are also attached to the error object as err.diagnostics for programmatic access.

Changes

File	Change
packages/config/src/options.ts	Added testTimeout config option with default 0
cli/types/cypress.d.ts	Added TypeScript type definition with docs
packages/driver/src/cypress/error_messages.ts	Added error message for timeout with diagnostics hint
packages/driver/src/cypress/runner.ts	Implemented timeout setup/cleanup logic + diagnostics collection

Implementation Details

• Timeout is set when the test starts (when wallClockStartedAt is first set)
• Timeout is cleared when test completes (in testAfterRun)
• On retry, a new timeout is set for the new attempt
• Uses cy.fail() to properly fail the test and trigger cleanup
• Collects diagnostics in a try/catch to ensure timeout failure even if diagnostics collection fails

Testing

• Unit tests for config option
• System tests for timeout behavior
• Documentation update

---

Note: This is a proof-of-concept implementation. Additional testing and edge case handling may be needed for production readiness.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.