Heuristic:Webdriverio Webdriverio Exponential Backoff Retry
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Optimization |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
WebDriver protocol requests use exponential backoff retry (250ms base, 10s cap, 3 retries default) to handle transient network and driver failures.
Description
The WebDriver request layer in WebdriverIO implements an exponential backoff strategy for failed HTTP requests to the WebDriver server. When a request fails (network error, timeout, or server error), the system waits an exponentially increasing amount of time before retrying: 500ms, 1000ms, 2000ms, 4000ms, etc., capped at 10 seconds. The base formula is `min(10000, 250 * 2^retryCount)`. By default, 3 retries are allowed with a connection retry timeout of 120 seconds.
Usage
This heuristic is automatically applied to all WebDriver protocol requests. Configure it when:
- Flaky CI environments: Increase `connectionRetryCount` (default 3) for unreliable network connections.
- Slow driver startup: The 120s `connectionRetryTimeout` accommodates slow Selenium/WebDriver server starts.
- Cloud testing: Cloud providers may have intermittent latency; the backoff prevents overwhelming the server.
The Insight (Rule of Thumb)
- Action: Failed WebDriver requests are retried with exponential backoff.
- Value: Base delay = 250ms * 2^retryCount, capped at 10,000ms. Default 3 retries with 120s total timeout.
- Trade-off: Retries add latency to failing tests. A test that would fail immediately now waits up to ~14 seconds (500 + 1000 + 2000 + 4000 + ... capped). Adjust `connectionRetryCount` to balance reliability vs speed.
- Configuration:
- `connectionRetryCount: 3` — number of retries (in `wdio.conf`)
- `connectionRetryTimeout: 120000` — max total wait time in ms
Reasoning
Transient failures are common in browser automation: the WebDriver server may be starting up, the browser may be busy processing, or the network may have momentary issues. A fixed retry interval would either be too aggressive (overwhelming a struggling server) or too conservative (wasting time). Exponential backoff strikes a balance by starting with short retries and progressively backing off, giving the server time to recover without unnecessary delays on quick recovery.
Evidence from code:
From `packages/webdriver/src/request/request.ts:195-200`:
if (retryCount > 0) {
/*
* Exponential backoff with a minimum of 500ms and a maximum of 10_000ms.
*/
await sleep(Math.min(10000, 250 * Math.pow(2, retryCount)))
}
Default configuration from `packages/wdio-config/src/constants.ts:27-28`:
connectionRetryTimeout: 120000,
connectionRetryCount: 3,