Heuristic:Webdriverio Webdriverio Default Timeout Configuration
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Optimization |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
WebdriverIO's default timeout values (10s test, 5s waitFor, 100ms polling, 120s connection) are carefully tuned — avoid setting implicit timeouts as they conflict with WebdriverIO's internal behavior.
Description
WebdriverIO defines a layered timeout system with distinct values for different concerns: test execution timeouts (10s default across Mocha, Jasmine, and Cucumber), element wait timeouts (5s with 100ms polling interval), connection retry timeouts (120s), and reporter sync timeouts (5s). The test framework timeout applies per `it()` block, the `waitforTimeout` applies to `waitUntil` and implicit element waits, and `connectionRetryTimeout` governs WebDriver protocol request retries. Importantly, the WebDriver-level `implicit` timeout should not be set as it conflicts with WebdriverIO's own waiting mechanisms.
Usage
Tune these values when:
- Tests timing out: Increase `mochaOpts.timeout` (or equivalent) for slow pages.
- Slow element rendering: Increase `waitforTimeout` for SPAs with long render times.
- Flaky CI: Increase `connectionRetryTimeout` for unreliable WebDriver connections.
- Too many retries: Set `specFileRetries: 0` (default) to fail fast, or increase for flaky suites.
The Insight (Rule of Thumb)
- Action: Configure timeouts in `wdio.conf.js` according to your application's performance characteristics.
- Values:
- `waitforTimeout: 5000` — max wait for `waitUntil` and element queries (ms)
- `waitforInterval: 100` — polling interval during waits (ms)
- `connectionRetryTimeout: 120000` — max wait for WebDriver connection (ms)
- `connectionRetryCount: 3` — number of connection retries
- `mochaOpts.timeout: 10000` — per-test timeout for Mocha (ms)
- `jasmineOpts.defaultTimeoutInterval: 10000` — per-test timeout for Jasmine (ms)
- `cucumberOpts.timeout: 10000` — per-step timeout for Cucumber (ms)
- `reporterSyncTimeout: 5000` — max wait for reporter to finish writing (ms)
- `specFileRetries: 0` — number of times to retry a full spec file on failure
- Trade-off: Higher timeouts increase reliability but slow down failure detection. The `waitforInterval` of 100ms balances CPU usage vs responsiveness.
- Warning: Do not set WebDriver `implicit` timeouts — they interfere with WebdriverIO's explicit waiting strategy and cause unpredictable behavior.
Reasoning
The 10-second default test timeout accommodates most page loads and interactions without being so long that failing tests waste CI time. The 5-second `waitforTimeout` with 100ms polling gives elements ample time to appear while keeping feedback loops tight. The 120-second `connectionRetryTimeout` handles slow Selenium grid startups and cold browser launches. Setting the WebDriver `implicit` timeout causes double-waiting (WebDriver waits + WebdriverIO waits) and masks real test failures.
Evidence from code:
From `packages/wdio-config/src/constants.ts:3-55`:
const DEFAULT_TIMEOUT = 10000
export const DEFAULT_CONFIGS: () => WebdriverIO.Config = () => ({
waitforInterval: 100,
waitforTimeout: 5000,
connectionRetryTimeout: 120000,
connectionRetryCount: 3,
specFileRetries: 0,
specFileRetriesDelay: 0,
reporterSyncInterval: 100,
reporterSyncTimeout: 5000,
mochaOpts: { timeout: DEFAULT_TIMEOUT },
jasmineOpts: { defaultTimeoutInterval: DEFAULT_TIMEOUT },
cucumberOpts: { timeout: DEFAULT_TIMEOUT },
})
Implicit timeout warning from `packages/webdriverio/src/commands/browser/setTimeout.ts:11`:
/**
* It is not recommended to set `implicit` timeouts as they impact WebdriverIO's behavior
*/