What Are ExpectedConditions in Selenium WebDriver?
Rohit Rajpal
Learn what ExpectedConditions in Selenium WebDriver are, how they work with explicit waits, common methods, custom conditions, and best practices.
Selenium WebDriver is widely used for automating web applications, but test execution often runs into timing issues. A page may take longer to load, or an element may not be visible immediately. If the script tries to interact with the element before it is ready, the test fails. This is where ExpectedConditions come in.
ExpectedConditions define specific conditions that must be met before the next step in the test continues. Instead of relying on fixed sleep times, testers can wait for elements to become visible, clickable, or present in the DOM.
This article explains what ExpectedConditions are in Selenium WebDriver and how they work with explicit waits.
What is ExpectedConditions in Selenium WebDriver?
ExpectedConditions in Selenium WebDriver are predefined conditions that help manage synchronization between the test script and the web application. When you run an automated test, the script can execute much faster than the application can respond.
For example, an element may take time to appear or become clickable. If the script does not wait for this, it results in NoSuchElementException or ElementNotInteractableException.
ExpectedConditions work with explicit waits. Instead of halting execution for a fixed time, they wait until a particular condition is true. This makes test runs more efficient and reduces unnecessary delays.
Types of ExpectedConditions
Selenium provides several categories of ExpectedConditions that help testers handle different synchronization challenges. Each type targets a specific scenario in web automation, so you can choose the right one based on the behavior of the application under test.
Below are the main types of ExpectedConditions you will come across in Selenium WebDriver:
- Presence Conditions: Used when you want to confirm that an element is present in the DOM, regardless of whether it is visible. This is useful when elements load in the background and you need to validate their availability before further actions.
- Visibility Conditions: These ensure that an element is present and displayed on the page. They are helpful when you need to perform actions like typing text or clicking, which require the element to be visible.
- Clickability Conditions: These go beyond visibility by checking if an element is both visible and enabled. This is essential when buttons or links appear on the page but are disabled for a short duration.
- Text Conditions: Applied when you need to verify that a specific string of text appears in an element or in the page title. They are often used for validating page loads, alerts, or dynamic content updates.
- Frame and Alert Conditions: These are used when switching the driver’s focus to a frame or waiting for an alert box to appear. Handling such conditions is important to avoid script failures caused by context changes.
- Invisibility or Absence Conditions: Sometimes you need to wait until an element disappears from the page. These conditions help ensure that your script does not proceed until transient elements like loading spinners or overlays are gone.
How ExpectedConditions Work with Explicit Waits
ExpectedConditions are applied through explicit waits, which pause script execution until a defined condition is met. Unlike implicit waits that apply a fixed time to check for elements, explicit waits focus on a specific state of the application. This makes them more accurate when handling dynamic content.
With explicit waits, you set two parameters: the maximum wait time and the condition to monitor. Selenium then checks the page repeatedly until either the condition is satisfied or the timeout is reached. If the condition is met, execution continues. If it is not met, Selenium raises a TimeoutException.
The workflow is simple:
- Create a WebDriverWait with a timeout value.
- Pass an ExpectedCondition to it.
- Selenium keeps polling until the condition returns true.
- If true, the script proceeds. If false after timeout, the test fails.
This targeted waiting mechanism makes automation more stable and reduces failures caused by unpredictable load times.
Common ExpectedConditions Methods and Examples
Selenium provides a wide range of built-in ExpectedConditions that testers can apply in real projects. These methods cover the most common scenarios, from waiting for elements to load to handling alerts and frames. Using them correctly prevents synchronization errors and improves the stability of your tests.
Below are the commonly used ExpectedConditions along with examples:
1. elementToBeClickable
Waits until the element is both visible and enabled, making it safe to click.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement button = wait.until(ExpectedConditions.elementToBeClickable(By.id("submitBtn")));
button.click();
This ensures you do not attempt a click before the button is active.
2. visibilityOfElementLocated
Waits until the element is present in the DOM and visible on the page.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement username = wait.until(ExpectedConditions.visibilityOfElementLocated(By.name("username")));
username.sendKeys("test_user");
Useful for text fields or other elements that appear after a page load.
3. presenceOfElementLocated
Checks if the element exists in the DOM, regardless of visibility.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement element = wait.until(ExpectedConditions.presenceOfElementLocated(By.className("loader")));
Commonly used when you only need confirmation that an element is available in the DOM.
4. titleIs and titleContains
Used for verifying page navigation or content updates.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.titleIs("Dashboard"));
This prevents moving forward until the expected page has fully loaded.
5. alertIsPresent
Waits until a JavaScript alert appears.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
Alert alert = wait.until(ExpectedConditions.alertIsPresent());
alert.accept();
Essential when applications trigger alerts that must be handled immediately.
6. frameToBeAvailableAndSwitchToIt
Waits until a frame is available, then switches to it automatically.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.frameToBeAvailableAndSwitchToIt("frameName"));
Helps when elements are inside frames that load asynchronously.
7. invisibilityOfElementLocated
Waits until an element disappears from the DOM or is hidden.
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.invisibilityOfElementLocated(By.id("loadingSpinner")));
This is useful for waiting out loaders or popups before interacting with the page.
Writing a Custom ExpectedCondition
While Selenium provides many built-in ExpectedConditions, there are situations where they may not cover the exact behavior you need to validate. In such cases, you can write a custom ExpectedCondition. This gives you full control over the condition logic, allowing you to target application-specific scenarios.
A custom ExpectedCondition is created by implementing the ExpectedCondition<T> interface and overriding its apply method. The method should return the value that you want Selenium to wait for, or null if the condition is not yet met.
Here is an example where we wait for an element’s attribute to contain a specific value:
public class AttributeContains implements ExpectedCondition<Boolean> {
private By locator;
private String attribute;
private String value;
public AttributeContains(By locator, String attribute, String value) {
this.locator = locator;
this.attribute = attribute;
this.value = value;
}
@Override
public Boolean apply(WebDriver driver) {
WebElement element = driver.findElement(locator);
String attrValue = element.getAttribute(attribute);
return attrValue != null && attrValue.contains(value);
}
}
You can use this custom condition with WebDriverWait like this:
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(new AttributeContains(By.id("status"), "class", "active"));
This example ensures that the script continues only when the element with the given ID has a class attribute containing “active”.
Custom ExpectedConditions are useful when you need more precise synchronization, such as waiting for CSS changes, AJAX requests to finish, or application-specific states that are not covered by Selenium’s default set.
Advantages of Using ExpectedConditions
Relying on static waits like Thread.sleep() makes test scripts slower and less reliable. ExpectedConditions address this by introducing intelligent, condition-based waiting. Instead of waiting blindly, scripts proceed only when the application is ready. This leads to several practical benefits.
Here are the main advantages of using ExpectedConditions:
- Improved test reliability: Conditions ensure the application reaches the expected state before actions are performed, reducing the chances of flaky failures caused by timing issues.
- Faster execution: Explicit waits exit immediately once the condition is satisfied. Unlike fixed waits, they do not block the script for unnecessary extra time.
- Better resource usage: By polling the application instead of idling, Selenium makes more efficient use of time and computing resources.
- Flexibility: You can choose from a wide range of built-in conditions or create custom ones to handle unique synchronization challenges.
- Clear intent in code: Using conditions like elementToBeClickable or alertIsPresent makes scripts easier to read and understand, since the wait logic describes exactly what is expected.
Best Practices for Using ExpectedConditions
ExpectedConditions are powerful, but using them incorrectly can still lead to unstable tests. Following best practices ensures you get the most out of them without adding unnecessary complexity.
Here are some guidelines that experienced testers apply when working with ExpectedConditions:
- Use explicit waits only where needed: Do not wrap every action in an explicit wait. Apply them selectively for elements or events that are known to load dynamically.
- Prefer specific conditions over generic ones: For example, use elementToBeClickable instead of presenceOfElementLocated when you intend to click. This ensures the condition matches the actual action.
- Set realistic timeout values: Very short timeouts can cause false failures, while very long ones can slow down test runs. Base your wait times on application performance patterns.
- Combine with page object model: Encapsulate wait logic inside page classes. This keeps your test code clean and makes synchronization reusable across multiple test cases.
- Handle exceptions gracefully: Always account for possible TimeoutException or NoSuchElementException. Logging these errors with clear messages helps in debugging failures.
- Avoid unnecessary waits for static elements: If an element always loads instantly, applying waits only increases overhead. Use waits where timing is unpredictable.
Why Run Selenium Tests on Real Devices
Testing on real devices is important because web applications do not behave the same way across browsers, operating systems, and hardware. Elements may render differently, performance may vary, and certain device-specific issues only appear in real-world environments. Relying only on emulators or simulators misses these factors, which can result in bugs slipping into production.
BrowserStack solves this challenge by giving teams instant access to a wide range of real devices and browsers in the cloud. With Selenium tests running on BrowserStack Automate, you can validate functionality, layout, and responsiveness across actual devices without managing an in-house device lab.
This ensures that the issues your users would face in real usage conditions are detected early in the testing process.
Conclusion
ExpectedConditions in Selenium WebDriver provide a reliable way to handle synchronization challenges that often cause flaky test results. By waiting for specific states like visibility, clickability, or disappearance of elements, tests interact with the application at the right time.
Beyond the built-in conditions, custom ExpectedConditions allow teams to handle application-specific scenarios, making the approach flexible enough for complex projects. When paired with best practices and executed on real devices through platforms like BrowserStack, ExpectedConditions play a central role in delivering accurate and consistent test outcomes.
Written by
Rohit Rajpal
Rohit Rajpal is a B2B Content Strategist at BrowserStack, helping SaaS brands build AI-first strategies that drive authority and revenue. He writes about content, strategy, and the future of search in the zero-click era.
Contents
- What is ExpectedConditions in Selenium WebDriver?
- Types of ExpectedConditions
- How ExpectedConditions Work with Explicit Waits
- Common ExpectedConditions Methods and Examples
- 1. elementToBeClickable
- 2. visibilityOfElementLocated
- 3. presenceOfElementLocated
- 4. titleIs and titleContains
- 5. alertIsPresent
- 6. frameToBeAvailableAndSwitchToIt
- 7. invisibilityOfElementLocated
- Writing a Custom ExpectedCondition
- Advantages of Using ExpectedConditions
- Best Practices for Using ExpectedConditions
- Why Run Selenium Tests on Real Devices
- Conclusion
Subscribe for latest updates
Share this article
Related posts
Endpoint ft. Mahdi Taghizadeh: A CTO’s guide to product thinking, observability, and growth
Engineering leader Mahdi Taghizadeh shares insights on agile thinking, AI’s impact on development, and the underrated skills that define great engineers
Dinesh Thakur
October 7, 2025
A Beginner’s Guide to WCAG Testing Checklist
Discover the essential WCAG testing checklist for ensuring web accessibility, covering key areas like contrast, keyboard navigation, and mobile responsiveness.
Azma Banu
October 6, 2025
How to Use Maestro for Flutter Testing
Learn how to use Maestro for Flutter testing including setup steps, test strategies, component validation, performance checks, and accessibility compliance.
Rohit Rajpal
October 6, 2025