Introduction
WebDriverWait is the most commonly used class for implementing Explicit Wait in Selenium. Unlike Implicit Wait, which applies globally to all element searches, WebDriverWait waits for a specific condition before continuing the execution of the automation script.
It allows Selenium to synchronize with dynamic web applications by waiting only as long as necessary. As soon as the required condition is satisfied, Selenium immediately proceeds with the next step.
In this tutorial, you’ll learn what WebDriverWait is, why it is used, its syntax, practical examples, real-world use cases, common mistakes, and best practices.
What is WebDriverWait?
WebDriverWait is a Selenium class that implements Explicit Wait.
It waits until a specified condition becomes true or until the timeout expires.
Unlike time.sleep() or Implicit Wait, WebDriverWait does not pause for a fixed duration. It continuously checks the condition and proceeds immediately once it is satisfied.
Why Use WebDriverWait?
WebDriverWait helps you:
Wait for dynamic elements.
Wait for specific conditions.
Improve automation reliability.
Reduce unnecessary waiting.
Handle AJAX and JavaScript-based applications.
Reduce flaky test cases.
Improve automation performance.
Syntax
from selenium.webdriver.support.ui import WebDriverWait
wait = WebDriverWait(driver, 10)
Where:
driver→ WebDriver instance.10→ Maximum wait time in seconds.
The wait object can then be used together with Selenium’s Expected Conditions.
Example
The Selenium practice website dynamically loads the “Hello World!” message after clicking the Start button. Since the element is loaded asynchronously, Selenium must wait until the message becomes visible before interacting with it.
Initially, the webpage displays:
Start
After clicking the Start button, JavaScript dynamically loads:
<h4>Hello World!</h4>
Instead of using a fixed delay such as:
import time
time.sleep(10)
WebDriverWait continuously checks whether the required element has become visible and immediately proceeds when the condition is satisfied.
The Selenium code is:
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
# Topic: 22. Explicit Wait - WebDriverWait
# Practice site: https://the-internet.herokuapp.com/dynamic_loading/2
# Run: pytest -s 22_examples/test_01_webdriver_wait.py
#
# WebDriverWait polls the browser until a condition is met or a timeout occurs.
def test_webdriver_wait():
driver = webdriver.Chrome()
try:
driver.get("https://the-internet.herokuapp.com/dynamic_loading/2")
driver.find_element(
By.CSS_SELECTOR,
"#start button"
).click()
wait = WebDriverWait(driver, 10)
heading = wait.until(
EC.visibility_of_element_located(
(
By.CSS_SELECTOR,
"#finish h4"
)
)
)
assert "Hello World!" in heading.text
finally:
driver.quit()
Output
The dynamically loaded
message becomes visible
successfully.
Hello World!
WebDriverWait immediately
continues execution once
the required condition
becomes true.
Understanding the Code
Import WebDriverWait
from selenium.webdriver.support.ui import WebDriverWait
Imports Selenium’s Explicit Wait class.
Import Expected Conditions
from selenium.webdriver.support import expected_conditions as EC
Imports Selenium’s predefined waiting conditions such as:
visibility_of_element_located()
element_to_be_clickable()
presence_of_element_located()
title_contains()
alert_is_present()
Open the Practice Website
driver.get(
"https://the-internet.herokuapp.com/dynamic_loading/2"
)
Launches the Selenium practice website that dynamically loads the Hello World! message.
Click the Start Button
driver.find_element(
By.CSS_SELECTOR,
"#start button"
).click()
Starts the JavaScript-based loading process.
Initially, the required element is not available on the webpage.
Create the WebDriverWait Object
wait = WebDriverWait(
driver,
10
)
Creates an Explicit Wait with a maximum timeout of ten seconds.
Selenium continuously checks whether the specified condition has been satisfied.
Wait Until the Element Becomes Visible
heading = wait.until(
EC.visibility_of_element_located(
(
By.CSS_SELECTOR,
"#finish h4"
)
)
)
Selenium repeatedly polls the browser until:
The element becomes visible.
The timeout expires.
If the element becomes visible after three seconds, Selenium immediately continues execution without waiting for the remaining seven seconds.
Validate the Result
assert (
"Hello World!"
in heading.text
)
Verifies that Selenium successfully synchronized with the webpage and retrieved the dynamically loaded message.
How WebDriverWait Works
Python Script
│
▼
Create WebDriverWait
│
▼
Check Condition
│
▼
Condition Satisfied?
│ │
Yes No
│ │
▼ ▼
Continue Keep Waiting
│
▼
Timeout Reached?
│ │
No Yes
│ │
▼ ▼
Continue Waiting Throw
TimeoutException
WebDriverWait continuously checks the required condition and immediately proceeds once the condition becomes true.
Practical Example
Suppose an E-Commerce website loads products dynamically after receiving an API response.
Without WebDriverWait:
Click Search
│
▼
Locate Product
│
▼
Products Not Loaded
│
▼
Test Fails
Using WebDriverWait:
Click Search
│
▼
Apply Explicit Wait
│
▼
Products Loaded
│
▼
Condition Satisfied
│
▼
Continue Execution
│
▼
Test Passes
This significantly improves automation reliability and performance.
Automation Testing Example
Consider an online banking application.
After clicking the Login button:
User credentials are verified.
Account information is retrieved.
Dashboard widgets are loaded.
Transaction history becomes available.
Instead of using fixed delays, WebDriverWait waits only until the required dashboard element becomes visible before continuing execution.
This makes automation scripts:
Faster.
More reliable.
Easier to maintain.
Real-World Example
WebDriverWait is widely used in:
Banking applications.
E-Commerce websites.
CRM systems.
Healthcare portals.
Airline booking systems.
HR management systems.
SaaS products.
Enterprise web applications.
It is the preferred synchronization mechanism for modern dynamic web applications.
Advantages of WebDriverWait
Waits only when necessary.
Faster than fixed delays.
Waits for specific conditions.
Improves automation reliability.
Reduces flaky test cases.
Highly suitable for modern web applications.
Improves framework maintainability.
Limitations
Requires slightly more code than Implicit Wait.
Requires Expected Conditions.
Incorrect timeout values can increase execution time.
Improper synchronization strategies may still cause failures.
WebDriverWait vs time.sleep()
| Feature | WebDriverWait | time.sleep() |
|---|---|---|
| Waiting Time | Dynamic | Fixed |
| Stops Early | Yes | No |
| Performance | Faster | Slower |
| Suitable for Dynamic Applications | Yes | No |
| Real-World Usage | Extensive | Limited |
| Automation Reliability | High | Lower |
Common Mistakes Beginners Make
Forgetting to Import Expected Conditions
Many beginners write:
from selenium.webdriver.support.ui import WebDriverWait
but forget:
from selenium.webdriver.support import expected_conditions as EC
Without this import, Selenium cannot use its predefined Expected Conditions.
Using Very Large Timeout Values
Avoid:
wait = WebDriverWait(
driver,
120
)
Large timeout values unnecessarily increase execution time if the condition is never satisfied.
Always use reasonable timeout values.
Using WebDriverWait Without until()
The following code does nothing useful:
wait = WebDriverWait(
driver,
10
)
Always use:
wait.until(...)
to wait for the required condition.
Best Practices
Use WebDriverWait for dynamic web applications.
Use reasonable timeout values (typically 5–15 seconds).
Combine WebDriverWait with appropriate Expected Conditions.
Avoid unnecessary use of
time.sleep().Prefer WebDriverWait over Implicit Wait for condition-based synchronization.
Wait only for the required condition instead of adding unnecessary delays.
Use reliable locators together with Explicit Wait.
Conclusion
WebDriverWait is the foundation of Explicit Wait in Selenium. It allows automation scripts to wait for specific conditions instead of using fixed delays, making tests faster, more stable, and better suited for modern web applications.
Because it waits only as long as necessary, WebDriverWait significantly improves automation reliability and reduces flaky test failures. It is one of the most widely used synchronization techniques in professional Selenium automation frameworks.
Understanding WebDriverWait is essential for building stable, maintainable, and efficient Selenium automation projects.
Frequently Asked Questions (FAQs)
What is WebDriverWait in Selenium?
WebDriverWait is a Selenium class used to implement Explicit Wait by waiting for specific conditions before continuing execution.
What is the difference between WebDriverWait and Implicit Wait?
Implicit Wait waits while locating elements and applies globally.
WebDriverWait waits for specific conditions and is applied only where required.
What happens if the condition is not met?
If the condition is not satisfied within the specified timeout period, Selenium throws a TimeoutException.
Is WebDriverWait better than time.sleep()?
Yes.
WebDriverWait waits only until the required condition becomes true, whereas time.sleep() always waits for the entire specified duration.
Is WebDriverWait commonly used in real projects?
Yes.
WebDriverWait is one of the most widely used synchronization techniques in Selenium automation frameworks.
Key Takeaways
WebDriverWait is the core class used for implementing Explicit Wait.
It waits for specific conditions before proceeding.
Selenium immediately continues execution once the condition becomes true.
It improves automation speed, reliability, and maintainability.
It is more efficient than
time.sleep()and more flexible than Implicit Wait.WebDriverWait is the preferred synchronization mechanism for modern Selenium automation frameworks.