Heuristic:Getgauge Taiko Navigation Wait Strategy
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Testing |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Wait strategy for navigation-related actions using event-based promises with configurable timeout and custom wait events for special scenarios.
Description
Taiko automatically waits for navigation to complete after actions that may trigger page loads (click, goto, reload, etc.). The mechanism listens for XHR events, frame load events, and frame navigation events. Once the action completes, it waits for a configurable waitForStart period (default 100ms) to catch in-flight XHR requests, then waits for all tracked promises to resolve or the navigationTimeout (default 30 seconds) to expire. This eliminates the need for explicit sleep calls in test scripts.
Usage
Apply this heuristic when debugging flaky tests where actions complete before the page is ready, or when dealing with SPAs (Single Page Applications) that use XHR-based navigation instead of full page loads. Also useful when tests interact with pages that open new tabs/windows or trigger heavy resource loading.
The Insight (Rule of Thumb)
- Action: Use `waitForEvents` option to specify additional events when default waiting is insufficient.
- Values:
- `firstMeaningfulPaint` — for pages with heavy images or fonts
- `targetNavigated` — when clicking opens a new tab or window
- `loadEventFired` — for explicit page load completion
- Trade-off: Adding more wait events increases reliability but slows test execution. Setting `waitForNavigation: false` is fastest but risks flaky tests.
- Default Behavior: Taiko listens for `xhrEvent`, `frameEvent`, and `frameNavigationEvent` automatically (except on Firefox).
Reasoning
The 100ms waitForStart default exists because XHR requests take a non-zero time to initiate after a user action. Without this buffer, Taiko might check for pending XHR requests before they start, concluding navigation is complete when it has not yet begun. The value is divided into 5 chunks of 20ms for responsive checking.
The navigationTimeout of 30 seconds covers slow network conditions and heavy pages. The retryTimeout of 10 seconds covers element search after navigation.
Firefox is excluded from XHR/frame event listening because its CDP implementation handles these events differently.
Code Evidence
Default wait events from `lib/doActionAwaitingNavigation.js:31-39`:
if (!defaultConfig.firefox) {
const func = addPromiseToWait(promises);
listenerCallbackMap.xhrEvent = func;
listenerCallbackMap.frameEvent = func;
listenerCallbackMap.frameNavigationEvent = func;
eventHandler.addListener("xhrEvent", func);
eventHandler.addListener("frameEvent", func);
eventHandler.addListener("frameNavigationEvent", func);
}
waitForStart default from `lib/config.js:90`:
options.waitForStart = options.waitForStart || 100;
Custom wait event usage (from docs/frequently_asked_questions.md):
// Wait for new tab to open after click
click(link('open new tab'), {waitForEvents: ['targetNavigated']});
// Wait for heavy page paint
goto('https://heavy-page.example.com', {waitForEvents: ['firstMeaningfulPaint']});