Heuristic:Nightwatchjs Nightwatch Timeout And Retry Tuning
| Knowledge Sources | |
|---|---|
| Domains | Testing, Optimization |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Tuning guide for Nightwatch's layered timeout and retry system spanning waitFor commands, assertions, HTTP requests, and WebDriver process management.
Description
Nightwatch has a multi-layered timeout architecture where different timeout values apply at different levels: element wait polling, assertion retries, HTTP request timeouts, and WebDriver process startup timeouts. Understanding which timeout applies where is critical to avoiding flaky tests (timeouts too low) or slow feedback loops (timeouts too high). The default values are designed for general use but often need tuning for specific CI environments, slow applications, or cloud testing.
Usage
Apply this heuristic when tests are flaky due to timing issues, when tests are slow due to excessive waiting, or when switching between local and CI/cloud environments. The most common symptom is intermittent `element not found` or `assertion failed` errors that pass on retry.
The Insight (Rule of Thumb)
- waitForConditionTimeout (default: 5000ms): Controls how long `waitFor*` commands and `expect` assertions wait before failing. Increase to 10000-15000ms for slow applications or CI environments.
- waitForConditionPollInterval (default: 500ms): Controls how frequently the element is checked during waiting. Lower to 100-200ms for faster feedback on fast applications; keep at 500ms for remote/cloud testing to avoid excessive requests.
- retryAssertionTimeout (default: 5000ms): Failed assertions are automatically retried until this timeout. Set to 0 to disable retry behavior for strict assertion checking.
- asyncHookTimeout (default: 20000ms): Maximum time for `before`/`after`/`beforeEach`/`afterEach` hooks to call `done()`. Increase for hooks that perform database setup or API calls.
- WebDriver timeout (default: 90000ms): HTTP request timeout for WebDriver commands. Increase for cloud testing (BrowserStack, SauceLabs) where latency is higher.
- WebDriver retry_attempts (default: 2): Retries for failed WebDriver HTTP requests. Keep at 2 for local; consider increasing for unreliable networks.
- element_command_retries (default: 3): Interactive commands like `click` and `setValue` retry up to 3 times on errors like "element not interactable".
- CLI --timeout flag: Overrides both `waitForConditionTimeout` and `retryAssertionTimeout` simultaneously. Useful for quick CI adjustments.
Reasoning
The layered timeout design addresses the fundamental challenge of browser automation: DOM state is asynchronous and non-deterministic. Elements may not appear immediately after navigation, animations may delay interactability, and network latency varies between environments.
The default 5000ms `waitForConditionTimeout` is sufficient for most local testing but too low for:
- Applications with heavy JavaScript initialization (SPAs)
- CI environments with shared resources and variable load
- Cloud testing services with additional network round-trip time
The 500ms polling interval balances responsiveness against WebDriver server load. Each poll generates an HTTP request, so polling too aggressively against a remote server creates unnecessary traffic.
Key evidence from defaults:
// lib/settings/defaults.js:73-102
waitForConditionPollInterval: 500, // ms between checks
waitForConditionTimeout: 5000, // total wait budget
asyncHookTimeout: 20000, // hook completion timeout
unitTestsTimeout: 2000, // unit test done() timeout
retryAssertionTimeout: 5000, // assertion auto-retry budget
// lib/settings/defaults.js:247-249
timeout_options: {
timeout: 90000, // WebDriver HTTP timeout
retry_attempts: 2 // WebDriver request retries
}
HTTP request retry logic from `lib/http/request.js:22-28`:
const __defaultSettings__ = {
timeout: 60000,
retry_attempts: 0,
internal_server_error_retry_interval: 1000 // wait 1s between 500-error retries
};
Assertion retry scheduler from `lib/api/_loaders/assertion-scheduler.js:24,104-108`:
this.shouldRetry = this.opts.timeout > 0;
// ...
if (!passed && elapsedTime < this.opts.timeout) {
this.reschedule(); // retry assertion until timeout
}