Selenium WebDriverWait: How to Wait for Elements

Use an explicit wait to poll for the specific state your next Selenium command needs. Wait for presence when you only need to locate an element, visibility when it must be displayed, and clickability when it must be visible and enabled. Set a finite timeout so a missing or stuck element produces a clear failure instead of a race or an indefinite hang.

A browser and automation script can run at different speeds. A page may still be loading, rendering, or updating when the script tries to use an element. Selenium describes explicit waits as loops that poll for a specific condition and continue when it succeeds. The examples below show the binding-specific syntax; timeout units and available conditions differ by language.

1. Choose the condition that matches the next action

Presence is not a promise that an element can be seen or clicked. Pick the narrowest condition that proves the page is ready for the action you will perform.

2. Python: wait for an element

Install Selenium with python -m pip install selenium and configure a WebDriver for your browser. The following snippet assumes driver is an already-created Selenium WebDriver. It waits up to ten seconds for a result to become visible and returns the element as soon as the condition succeeds:

from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait

wait = WebDriverWait(driver, 10)
result = wait.until(EC.visibility_of_element_located((By.ID, "result")))
print(result.text)

Python’s WebDriverWait takes its timeout in seconds. The Selenium 4.50.0 Python API documents a default polling interval of 0.5 seconds and NoSuchElementException as the default ignored exception. These are Python binding details, not defaults to assume in every language.

Common Python conditions

# Located in the DOM; may be hidden
el = wait.until(EC.presence_of_element_located((By.CSS_SELECTOR, "#result")))

# Displayed
el = wait.until(EC.visibility_of_element_located((By.CSS_SELECTOR, "#result")))

# Displayed and enabled
button = wait.until(EC.element_to_be_clickable((By.ID, "submit")))
button.click()

# Wait until a loading indicator is no longer visible
wait.until(EC.invisibility_of_element_located((By.CSS_SELECTOR, ".loading")))

# Wait until a stored element is detached from the DOM
old_row = driver.find_element(By.CSS_SELECTOR, ".result-row")
wait.until(EC.staleness_of(old_row))

# Wait for text to appear in an element
wait.until(EC.text_to_be_present_in_element((By.ID, "status"), "Complete"))

# Wait for the document title to contain text
wait.until(EC.title_contains("Results"))

Use locator-based conditions when the page may replace the element during an update. A locator is checked again on each poll. Conditions that accept a previously found element are useful for checking that particular node, but a replaced node becomes stale.

Use a custom predicate when needed

When no built-in condition expresses the state your workflow needs, pass a function that returns a truthy value only when it is ready. until returns that successful value, so this predicate returns the element:

from selenium.common.exceptions import NoSuchElementException

result = wait.until(
    lambda d: (
        element
        if (element := d.find_element(By.ID, "result")).is_displayed()
        else False
    )
)

For older Python versions without the assignment expression, a small helper is clearer:

def visible_result(driver):
    try:
        element = driver.find_element(By.ID, "result")
        return element if element.is_displayed() else False
    except NoSuchElementException:
        return False

result = wait.until(visible_result)

Do not catch broad exceptions in a predicate unless the workflow intentionally treats them as “not ready.” Hiding programming errors or invalid sessions behind a retry makes failures harder to diagnose.

3. Java and JavaScript syntax

Use the API for the language binding installed by your project. Selenium’s waiting guide illustrates the same visibility check in Java and JavaScript, but their timeout units differ.

Java

With Selenium Java, a WebDriverWait timeout is expressed as a Duration:

import java.time.Duration;
import org.openqa.selenium.By;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement result = wait.until(
    ExpectedConditions.visibilityOfElementLocated(By.id("result"))
);
System.out.println(result.getText());

JavaScript

With Selenium’s JavaScript binding, driver.wait takes a timeout in milliseconds. This example uses the element-is-visible condition:

const { By, until } = require('selenium-webdriver');

const element = await driver.findElement(By.id('result'));
await driver.wait(until.elementIsVisible(element), 10_000);
console.log(await element.getText());

That JavaScript example finds the element before waiting for visibility. If the element may not exist yet, poll with a locator in a predicate so each check can find the current node:

const { By } = require('selenium-webdriver');

const result = await driver.wait(async d => {
  const matches = await d.findElements(By.id('result'));
  if (matches.length === 0) return false;
  return await matches[0].isDisplayed() ? matches[0] : false;
}, 10_000, 'Result did not become visible');

Expected Conditions and helper APIs are not identical across bindings. Selenium notes that .NET stopped supporting its Expected Conditions in Selenium 4, while Ruby commonly expresses waits with blocks, procs, and lambdas. Check the documentation for the binding and version your project uses.

4. Set a useful timeout and polling interval

A timeout is the maximum time the wait condition is allowed to take; it does not mean the script sleeps for the entire duration. Polling stops as soon as the condition succeeds. Choose a timeout based on the operation and the variability of the environment, rather than treating one value as correct for every page.

• Python: timeout and poll_frequency are in seconds. The documented default poll interval is 0.5 seconds; pass poll_frequency=0.2 for more frequent checks if the condition is inexpensive and faster response matters.
• JavaScript: the driver.wait timeout is in milliseconds; the API also accepts polling options.
• Java: express the timeout using Duration.

# Python: timeout 12 seconds, poll every 250 milliseconds
wait = WebDriverWait(driver, 12, poll_frequency=0.25)

# Python: disable the session-wide implicit wait
 driver.implicitly_wait(0)
wait = WebDriverWait(driver, 10)

old_result = driver.find_element(By.CSS_SELECTOR, ".result")
wait.until(EC.staleness_of(old_result))
new_result = wait.until(
    EC.visibility_of_element_located((By.CSS_SELECTOR, ".result"))
)

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));