Complete Guide to Selenium WebDriverWait: Eliminate Flaky Tests with Proper Wait Strategies

Most “element not found” and “element not interactable” errors in Selenium come down to waiting strategy problems. Covering them up with time.sleep() is a straight path to Flaky Tests. Using WebDriverWait and expected_conditions correctly gives you stable, reliable tests.

📌 Who This Article Is For

📖 What You’ll Be Able to Do After This Guide

I have worked on browser automation tests using Selenium across multiple real projects.
Waiting strategy problems are one of the most common root causes of Flaky Tests I have encountered.
This guide is a systematic summary of practical waiting patterns that hold up in real-world projects, built from that experience.

Why Selenium Needs Waiting Strategies

Modern web applications run on asynchronous JavaScript (Ajax, SPAs). When a page first loads, most elements don’t exist yet.

To avoid these errors, you need to wait until elements are ready before interacting with them.

Why time.sleep() Is the Wrong Approach

import time
from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://example.com/login")  # sample URL
time.sleep(3)  # ← this is the problem
driver.find_element(By.ID, "email").send_keys("user@example.com")

Three Types of Waits in Selenium

Using Explicit Waits (WebDriverWait)

An explicit wait says “wait up to N seconds until this specific condition is met.” As soon as the condition is satisfied, execution continues immediately — no unnecessary waiting.

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

driver = webdriver.Chrome()
driver.get("https://example.com/login")  # sample URL

# Basic WebDriverWait pattern:
# WebDriverWait(driver, timeout_seconds).until(condition)
wait = WebDriverWait(driver, 10)  # wait up to 10 seconds

# Wait until input field is visible (for text inputs)
email_input = wait.until(
    EC.visibility_of_element_located((By.ID, "email"))
)
email_input.send_keys("user@example.com")

# Wait until button is visible AND enabled (clickable)
submit_btn = wait.until(
    EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='login-button']"))
)
submit_btn.click()

expected_conditions — Key Methods Reference

Code Examples by Situation

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

wait = WebDriverWait(driver, 10)

# ① Click a button (most common)
btn = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='submit-btn']")))
btn.click()

# ② Wait for a loading spinner to disappear
wait.until(EC.invisibility_of_element_located((By.CSS_SELECTOR, ".loading-spinner")))

# ③ Wait for a success message to appear
wait.until(EC.text_to_be_present_in_element(
    (By.CSS_SELECTOR, "[data-testid='status-message']"),
    "Saved successfully"
))

# ④ Wait for page navigation
wait.until(EC.url_contains("/dashboard"))

# ⑤ Wait for a list to load (at least one item)
items = wait.until(
    EC.presence_of_all_elements_located((By.CSS_SELECTOR, ".item-list li"))
)
assert len(items) > 0

# ⑥ Handle an alert dialog
wait.until(EC.alert_is_present())
alert = driver.switch_to.alert
alert.accept()

Implicit Waits (implicitly_wait) and Their Caveats

Implicit waits set a global timeout applied to every find_element call. Configure it once and it applies automatically to all element lookups.

driver = webdriver.Chrome()
driver.implicitly_wait(10)  # wait up to 10s on every find_element
driver.get("https://example.com/login")  # sample URL

# All subsequent find_element calls wait up to 10 seconds
email_input = driver.find_element(By.ID, "email")

WebDriverWait with Detailed Config (Fluent Wait-style)

This is a more detailed configuration of WebDriverWait where you fine-tune the polling interval and ignored exceptions.
Note that Selenium Python does not have a separate FluentWait class like Java does — this behavior is achieved by adjusting timeout, poll_frequency, and ignored_exceptions on WebDriverWait.

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By
from selenium.common.exceptions import NoSuchElementException, StaleElementReferenceException

# Detailed WebDriverWait configuration
wait = WebDriverWait(
    driver,
    timeout=15,              # maximum wait time in seconds
    poll_frequency=0.5,      # check interval in seconds (default: 0.5s)
    ignored_exceptions=[     # exceptions to ignore (keep waiting if these occur)
        NoSuchElementException,
        StaleElementReferenceException,
    ]
)

element = wait.until(
    EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='dynamic-btn']"))
)
element.click()

Writing Custom Wait Conditions

When the built-in expected_conditions don’t cover your case, you can define a custom condition as a function or class.

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.common.by import By

# ① Simple lambda approach
wait = WebDriverWait(driver, 10)

# Wait until an element's attribute changes to the expected value
wait.until(lambda d: d.find_element(By.ID, "status").get_attribute("data-state") == "loaded")

# ② Reusable class approach
class element_has_class:
    """Wait until the specified element has a particular CSS class."""
    def __init__(self, locator: tuple, css_class: str) -> None:
        self.locator = locator
        self.css_class = css_class

    def __call__(self, driver):
        element = driver.find_element(*self.locator)
        return self.css_class in element.get_attribute("class")


# Usage: wait until the button has the "active" class
wait.until(element_has_class(
    (By.CSS_SELECTOR, "[data-testid='submit-btn']"),
    "active"
))

Integrating WebDriverWait with pytest Fixtures

In real projects, wrapping WebDriverWait in a pytest fixture keeps test code clean and consistent.

# conftest.py
import pytest
from selenium import webdriver
from selenium.webdriver.support.ui import WebDriverWait


@pytest.fixture
def driver():
    d = webdriver.Chrome()
    d.implicitly_wait(0)   # explicitly disable implicit waits
    yield d
    d.quit()


@pytest.fixture
def wait(driver):
    return WebDriverWait(driver, 10)

# test_login.py
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC


def test_login_success(driver, wait) -> None:
    driver.get("https://example.com/login")  # sample URL

    wait.until(EC.visibility_of_element_located((By.ID, "email"))).send_keys("user@example.com")
    wait.until(EC.visibility_of_element_located((By.ID, "password"))).send_keys("password123")
    wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='login-btn']"))).click()

    wait.until(EC.url_contains("/dashboard"))
    assert "/dashboard" in driver.current_url

7 Common Waiting Strategy Pitfalls

Frequently Asked Questions (FAQ)

Summary

Writing waits correctly is one of the most effective things you can do to improve Selenium test stability.
A good first step: search your existing test code for time.sleep() and replace each one with the appropriate element_to_be_clickable or visibility_of_element_located.

Selenium vs Playwright: Different Philosophies on Waiting