Heuristic:DevExpress Testcafe Browser Connection Timeouts
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Testing |
| Last Updated | 2026-02-12 03:30 GMT |
Overview
Browser connection management uses differentiated timeouts: 2 minutes for local browser init, 6 minutes for remote, 2-minute heartbeat interval, and 1-minute restart timeout.
Description
TestCafe uses a hierarchy of timeouts to manage browser connections. Local browsers (Chrome, Firefox on the same machine) get 2 minutes to initialize, while remote browsers (connected from other machines or devices) get 6 minutes. Once connected, a heartbeat signal is sent every 2 seconds with a 2-minute timeout for missed heartbeats. Browser restart gets 1 minute, and browser close gets 30 seconds. Status request retries use a 300ms delay with up to ~399 retry attempts. These timeouts are shared between the client (browser) and server (Node.js) sides.
Usage
Apply this knowledge when debugging browser connection failures, configuring remote browser testing, or tuning CI timeouts. If tests fail with "browser connection timeout" errors, the cause is usually insufficient `browserInitTimeout`. For remote browsers (e.g., mobile devices via QR code), the 6-minute default is usually sufficient but can be customized.
The Insight (Rule of Thumb)
- Action: Override with `--browser-init-timeout` CLI flag if defaults are insufficient. Ensure network stability for remote browsers.
- Value: Local init: 120s. Remote init: 360s. Heartbeat interval: 2s. Heartbeat timeout: 120s. Restart timeout: 60s. Close timeout: 30s.
- Trade-off: Increasing init timeout delays failure detection but allows for slower machines/networks. Heartbeat timeout of 2 minutes provides tolerance for brief network interruptions.
- Interaction: The heartbeat timeout (2 min) is independent of the init timeout. A browser that connects but then loses heartbeat will be marked as disconnected after 2 minutes.
Reasoning
The differentiated timeout strategy reflects real-world conditions: local browsers start fast (seconds) but may be delayed by resource contention, while remote browsers involve network latency, manual device connection, and QR code scanning. The 2-second heartbeat interval balances connection health monitoring with network overhead. The status request retry mechanism (300ms delay, ~399 retries) provides robustness against transient network issues during test execution.
Code Evidence
From `src/utils/browser-connection-timeouts.js:1-20`:
// WARNING: this file is used by both the client and the server.
// Do not use any browser or node-specific API!
export const HEARTBEAT_TIMEOUT = 2 * 60 * 1000; // 2 minutes
export const BROWSER_RESTART_TIMEOUT = 60 * 1000; // 1 minute
export const BROWSER_CLOSE_TIMEOUT = BROWSER_RESTART_TIMEOUT / 2; // 30 seconds
export const LOCAL_BROWSER_INIT_TIMEOUT = 2 * 60 * 1000; // 2 minutes
export const REMOTE_BROWSER_INIT_TIMEOUT = 6 * 60 * 1000; // 6 minutes
export const HEARTBEAT_INTERVAL = 2 * 1000; // 2 seconds
export const CHECK_IFRAME_DRIVER_LINK_DELAY = 500;
export const CHECK_CHILD_WINDOW_DRIVER_LINK_DELAY = 500;
export const SEND_STATUS_REQUEST_TIME_LIMIT = 5000;
export const SEND_STATUS_REQUEST_RETRY_DELAY = 300;
export const SEND_STATUS_REQUEST_RETRY_COUNT = Math.floor(HEARTBEAT_TIMEOUT / SEND_STATUS_REQUEST_RETRY_DELAY - 1);
export const CHECK_STATUS_RETRY_DELAY = 1000;