Heuristic:Getgauge Taiko Implicit Wait Tuning
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Optimization |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Tuning guide for Taiko's implicit wait system including timeout defaults, retry intervals, element match limits, and configuration validation rules.
Description
Taiko uses an implicit wait system where all element searches retry for a configurable duration before failing. The three key parameters are retryTimeout (how long to keep trying), retryInterval (pause between attempts), and navigationTimeout (how long to wait for page navigation). These can be set via environment variables, `setConfig()`, or per-action options. Understanding the interaction between these values is critical for balancing test speed and reliability.
Usage
Apply this heuristic when tests are too slow (reduce timeouts), tests are flaky (increase timeouts), or when fine-tuning CI pipeline performance. Also useful when migrating from Selenium where explicit waits are the norm.
The Insight (Rule of Thumb)
- Default Values:
- `navigationTimeout`: 30,000ms (env: `TAIKO_NAVIGATION_TIMEOUT`)
- `retryTimeout`: 10,000ms (env: `TAIKO_RETRY_TIMEOUT`)
- `retryInterval`: 100ms (no env var, code-only)
- `waitForStart`: 100ms (hardcoded default, per-action override)
- `noOfElementToMatch`: 20 (max elements before "too many matches" error)
- `criConnectionRetries`: 50 (env: `TAIKO_CRI_CONNECTION_RETRIES`)
- Config Type Safety: `setConfig()` enforces strict type matching. Passing a string where a number is expected throws an error. Environment variables are converted via `Number()`.
- Per-Action Override: Most functions accept `{navigationTimeout: N, retryTimeout: N}` in their options object, overriding global config for that call only.
- Trade-off: Lower timeouts speed up tests but increase flakiness. Higher timeouts improve reliability but slow down failure detection.
Reasoning
The 100ms retryInterval balances CPU usage with responsiveness. Too low (10ms) wastes CPU cycles; too high (1000ms) misses transient elements.
The 100ms waitForStart gives XHR requests time to initiate before Taiko checks if navigation is complete. Without this buffer, fast actions might be checked before any network activity starts, causing Taiko to incorrectly conclude the page is ready.
The 20 element match limit prevents Taiko from spending excessive time evaluating large result sets. If a selector matches 100 elements, only the first 20 are considered. This is especially relevant for text-based selectors on content-heavy pages.
Type safety in setConfig() prevents subtle bugs where `setConfig({retryTimeout: "5000"})` would set a string instead of a number, causing comparison operators to behave unexpectedly.
Code Evidence
Default config with environment variable overrides from `lib/config.js:1-15`:
const defaultConfig = {
navigationTimeout: Number(process.env.TAIKO_NAVIGATION_TIMEOUT) || 30000,
observeTime: 3000,
retryInterval: 100,
retryTimeout: Number(process.env.TAIKO_RETRY_TIMEOUT) || 10000,
noOfElementToMatch: 20,
observe: false,
waitForNavigation: true,
waitForEvents: [],
ignoreSSLErrors: true,
headful: false,
criConnectionRetries: process.env.TAIKO_CRI_CONNECTION_RETRIES || 50,
};
Strict type validation from `lib/config.js:30-46`:
const setConfig = (options) => {
for (const key in options) {
if (Object.prototype.hasOwnProperty.call(defaultConfig, key)) {
if (typeof defaultConfig[key] !== typeof options[key]) {
throw new Error(
`Invalid value for ${key}. Expected ${typeof defaultConfig[key]} received ${typeof options[key]}`,
);
}
defaultConfig[key] = options[key];
} else {
throw new Error(
`Invalid config ${key}. Allowed configs are ${Object.keys(defaultConfig).join(", ")}`,
);
}
}
};
Headless default behavior from `lib/config.js:66-69`:
options.headless =
options.headless === undefined || options.headless === null
? true
: options.headless;