Selenium Waits Complete Explanation
Posted inJava Selenium

Complete Guide to Explicit Waits in Selenium

No Comments

All ExpectedConditions methods covered

If you’ve ever written a Selenium test that fails randomly because an element “wasn’t there yet,” you already know why explicit waits matter. Selenium ExpectedConditions is the class that makes explicit waits actually useful — instead of guessing with Thread.sleep(), you tell WebDriver exactly what condition to wait for before moving on. This article is Complete Guide to Explicit Waits in Selenium.

What Is ExpectedConditions in Selenium?

ExpectedConditions is a utility class in the org.openqa.selenium.support.ui package. It provides pre-built conditions you can pass into a WebDriverWait, so Selenium polls the page until that condition becomes true (or a timeout is reached).

Here’s the basic setup you’ll reuse throughout this post:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

Once you have a wait object, you call wait.until(...) and pass in any of the conditions below.

ExpectedConditions Methods That Take a By Locator

These methods look up the element themselves using a By locator, so you don’t need to call driver.findElement() first.

// 1. presenceOfElementLocated - element exists in DOM (not necessarily visible)
WebElement el = wait.until(ExpectedConditions.presenceOfElementLocated(By.id("username")));
// 2. presenceOfAllElementsLocatedBy - at least one element present, returns list
List<WebElement> els = wait.until(ExpectedConditions.presenceOfAllElementsLocatedBy(By.className("item")));
// 3. visibilityOfElementLocated - present AND visible (displayed, size > 0)
WebElement el2 = wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("login-btn")));
// 4. visibilityOfAllElementsLocatedBy - all matching elements visible
List<WebElement> els2 = wait.until(ExpectedConditions.visibilityOfAllElementsLocatedBy(By.cssSelector(".row")));
// 5. invisibilityOfElementLocated - element not visible or not present (e.g., spinner disappearing)
boolean gone = wait.until(ExpectedConditions.invisibilityOfElementLocated(By.id("spinner")));
// 6. invisibilityOfElementWithText - element with specific text is invisible
boolean goneText = wait.until(
    ExpectedConditions.invisibilityOfElementWithText(By.id("msg"), "Loading..."));
// 7. elementToBeClickable(By) - visible AND enabled
WebElement btn = wait.until(ExpectedConditions.elementToBeClickable(By.id("submit")));
// 8. elementSelectionStateToBe(By, boolean) - checkbox/radio matches expected state
boolean state = wait.until(
    ExpectedConditions.elementSelectionStateToBe(By.id("agree"), true));
// 9. elementToBeSelected(By) - element is selected
boolean selected = wait.until(ExpectedConditions.elementToBeSelected(By.id("radio1")));
// 10. textToBePresentInElementLocated - element's text contains given string
boolean textOk = wait.until(
    ExpectedConditions.textToBePresentInElementLocated(By.id("status"), "Success"));
// 11. textToBePresentInElementValue - value attribute contains given string
boolean valOk = wait.until(
    ExpectedConditions.textToBePresentInElementValue(By.id("input"), "John"));
// 12. numberOfElementsToBe - exact count of matching elements
List<WebElement> exact = wait.until(
    ExpectedConditions.numberOfElementsToBe(By.cssSelector("li.item"), 5));
// 13. numberOfElementsToBeMoreThan
List<WebElement> more = wait.until(
    ExpectedConditions.numberOfElementsToBeMoreThan(By.cssSelector("li.item"), 3));
// 14. numberOfElementsToBeLessThan
List<WebElement> less = wait.until(
    ExpectedConditions.numberOfElementsToBeLessThan(By.cssSelector("li.item"), 10));
// 15. presenceOfNestedElementLocatedBy(By parent, By child)
WebElement nested = wait.until(
    ExpectedConditions.presenceOfNestedElementLocatedBy(By.id("parent"), By.className("child")));
// 16. attributeToBe(By, String attribute, String value) - attribute equals value
boolean attrEq = wait.until(
    ExpectedConditions.attributeToBe(By.id("field"), "value", "Hello"));
// 17. attributeContains(By, String attribute, String value) - attribute contains value
boolean attrContains = wait.until(
    ExpectedConditions.attributeContains(By.id("div1"), "class", "active"));
// 18. frameToBeAvailableAndSwitchToIt(By) - switches driver into the frame
WebDriver frame = wait.until(
    ExpectedConditions.frameToBeAvailableAndSwitchToIt(By.id("iframeId")));

ExpectedConditions Methods That Take a WebElement

Use these when you’ve already located the element with driver.findElement() and simply need to wait for a state change on that specific reference.

WebElement element = driver.findElement(By.id("username"));
// 1. visibilityOf(WebElement) - element already found, wait till visible
WebElement v = wait.until(ExpectedConditions.visibilityOf(element));
// 2. invisibilityOf(WebElement) - wait till it disappears
boolean invisible = wait.until(ExpectedConditions.invisibilityOf(element));
// 3. elementToBeClickable(WebElement)
WebElement clickable = wait.until(ExpectedConditions.elementToBeClickable(element));
// 4. elementSelectionStateToBe(WebElement, boolean)
boolean sel = wait.until(ExpectedConditions.elementSelectionStateToBe(element, true));
// 5. elementToBeSelected(WebElement)
boolean isSelected = wait.until(ExpectedConditions.elementToBeSelected(element));
// 6. textToBePresentInElement(WebElement, String text)
boolean hasText = wait.until(ExpectedConditions.textToBePresentInElement(element, "Welcome"));
// 7. stalenessOf(WebElement) - element removed from DOM / page refreshed
boolean stale = wait.until(ExpectedConditions.stalenessOf(element));
// 8. attributeToBe(WebElement, String attribute, String value)
boolean attrEq2 = wait.until(ExpectedConditions.attributeToBe(element, "disabled", "true"));
// 9. attributeToBeNotEmpty(WebElement)
boolean notEmpty = wait.until(ExpectedConditions.attributeToBeNotEmpty(element));
// 10. attributeContains(WebElement, String attribute, String value)
boolean contains = wait.until(ExpectedConditions.attributeContains(element, "class", "highlighted"));
// 11. presenceOfNestedElementLocatedBy(WebElement parent, By childLocator)
WebElement child = wait.until(
    ExpectedConditions.presenceOfNestedElementLocatedBy(element, By.tagName("span")));

ExpectedConditions Methods That Take Neither By Nor WebElement

Some conditions apply to the page or browser as a whole, rather than a single element.

// Title / URL checks
wait.until(ExpectedConditions.titleIs("Dashboard"));
wait.until(ExpectedConditions.titleContains("Dashboard"));
wait.until(ExpectedConditions.urlToBe("https://example.com/home"));
wait.until(ExpectedConditions.urlContains("/home"));
wait.until(ExpectedConditions.urlMatches("^https://example\\.com/.*$"));
// Alerts
Alert alert = wait.until(ExpectedConditions.alertIsPresent());
// Window/tab count
wait.until(ExpectedConditions.numberOfWindowsToBe(2));
// JavaScript
wait.until(ExpectedConditions.javaScriptThrowsNoExceptions("return document.readyState"));
// Composition helpers
wait.until(ExpectedConditions.not(ExpectedConditions.titleIs("Loading...")));
wait.until(ExpectedConditions.refreshed(ExpectedConditions.presenceOfElementLocated(By.id("data"))));

Best Practices for Using ExpectedConditions

A few practical tips to keep your explicit waits reliable:

  • Prefer elementToBeClickable before clicking. It checks visibility and the enabled state in one call, which covers the most common failure case in UI tests.
  • Don’t confuse presence with visibility. presenceOfElementLocated only confirms the element exists in the DOM — it could still be hidden with display:none. Use visibilityOfElementLocated when you need it actually rendered on screen.
  • Use stalenessOf after page reloads. If an AJAX call or navigation replaces the DOM, the old WebElement reference becomes stale. Waiting for staleness before re-locating avoids StaleElementReferenceException.
  • Wrap flaky elements with refreshed(). This helper re-evaluates a condition against a fresh element reference, which is useful when the DOM node gets re-rendered mid-test.
  • Keep timeouts reasonable. A 10-second WebDriverWait is a common default — long enough to absorb network lag, short enough that a genuinely broken test still fails quickly.

Frequently Asked Questions

What package is ExpectedConditions in? It lives in org.openqa.selenium.support.ui.ExpectedConditions.

What’s the difference between presenceOfElementLocated and visibilityOfElementLocated? presenceOfElementLocated only checks that the element exists in the DOM. visibilityOfElementLocated additionally requires the element to be displayed and have a non-zero size.

Do method signatures change between Selenium versions? Some overloads were deprecated in Selenium 4, so if you’re pinned to a specific version, check that version’s Javadoc if a method doesn’t compile as shown here.

Final Thoughts

ExpectedConditions covers almost every situation you’ll run into with dynamic, JavaScript-heavy pages — from waiting for a spinner to disappear to confirming a URL redirect completed. Once you get comfortable with the By-based and WebElement-based variants shown above, you’ll rarely need Thread.sleep() again.

Related Links

Selenium Locators Tutorial
Selenium Waits Explained
Page Object Model in Selenium
Selenium Framework Design
Selenium Grid Explained
Jenkins Pipeline for Selenium Tests
Complete Selenium Tutorial

Claim your Free Selenium UI Test Framework Template HERE

Discover more from Rotebit

Subscribe to get the latest posts sent to your email.

Tags:

Comments

No comments yet. Why don’t you start the discussion?

Leave a Reply