Heuristic:SeleniumHQ Selenium Explicit Over Implicit Waits
| Knowledge Sources | |
|---|---|
| Domains | Testing, Best_Practices, Performance |
| Last Updated | 2026-02-11 23:00 GMT |
Overview
Prefer explicit waits (FluentWait/WebDriverWait) over implicit waits to avoid hidden performance penalties and unpredictable test behavior.
Description
Selenium provides two wait mechanisms: implicit waits (set globally, apply to every element search) and explicit waits (applied per-condition using FluentWait or WebDriverWait). Implicit waits add delay to every `findElement` call, even when the element is immediately present. This compounds across hundreds of lookups in a test suite, dramatically slowing test execution. Explicit waits target only the specific conditions that need waiting, avoiding unnecessary overhead.
Usage
Apply this heuristic when writing any Selenium test that needs to wait for dynamic page content. Never mix implicit and explicit waits, as their interaction is undefined and causes unpredictable timeout behavior. Use FluentWait with configurable polling intervals for fine-grained control.
The Insight (Rule of Thumb)
- Action: Use `WebDriverWait` or `FluentWait` instead of `driver.manage().timeouts().implicitlyWait()`.
- Value: Default polling interval is 500ms (`DEFAULT_SLEEP_TIMEOUT = 500`); adjust with `.pollingEvery()`.
- Trade-off: Explicit waits require more code per wait condition, but provide precise control and better performance.
- Anti-pattern: Setting a high implicit wait timeout (e.g., 30 seconds) penalizes every element lookup, especially with slow locator strategies like XPath.
Reasoning
The WebDriver specification warns that implicit waits have adverse effects on test run time, especially with XPath locators. The FluentWait Javadoc explicitly notes no thread safety guarantees, meaning each test thread needs its own wait instance. ExpectedConditions in Selenium handle both `NoSuchElementException` and `StaleElementReferenceException` as transient failures, automatically retrying - making explicit waits self-healing for common race conditions.
Code Evidence
Implicit wait performance warning from `java/src/org/openqa/selenium/WebDriver.java:304-305`:
// "Increasing the implicit wait timeout should be used judiciously as it
// will have an adverse effect on test run time, especially when used with
// slower location strategies like XPath."
FluentWait thread safety warning from `java/src/org/openqa/selenium/support/ui/FluentWait.java:64`:
// "This class makes no thread safety guarantees."
Default polling interval from `java/src/org/openqa/selenium/support/ui/FluentWait.java:70`:
protected static final long DEFAULT_SLEEP_TIMEOUT = 500;
Recommended FluentWait pattern from `java/src/org/openqa/selenium/support/ui/FluentWait.java:49-62`:
Wait<WebDriver> wait = new FluentWait<WebDriver>(driver)
.withTimeout(Duration.ofSeconds(30L))
.pollingEvery(Duration.ofSeconds(5L))
.ignoring(NoSuchElementException.class);
WebElement foo = wait.until(new Function<WebDriver, WebElement>() {
public WebElement apply(WebDriver driver) {
return driver.findElement(By.id("foo"));
}
});
Stale element handling in ExpectedConditions from `java/src/org/openqa/selenium/support/ui/ExpectedConditions.java:1061-1068`:
catch (NoSuchElementException | StaleElementReferenceException e) {
error = e;
return false; // Retry on next poll
}