Selenium Wait: Implicit, Explicit & Fluent Wait Commands

Why Do We Need Selenium Waits?

The primary challenge in test automation is ensuring the application is appropriately configured to execute a specific Selenium command as intended. One of the most common issues with test automation is race conditions. In a race condition, either the browser reaches the right state first (which results in the desired functionality), or the Selenium code gets executed first (which leads to unintended results). This race condition is one of the main reasons test results are unreliable.

The reason for such race conditions depends on many aspects, like network speed, content size, and the frontend technology/framework used. For Instance, Javascript frameworks like React or Angular take some time to load the different objects on the web page due to the dynamic update to the Document Object Model (also known as DOM).

Without an appropriate wait mechanism, automation tests produce inconsistent results: the same test passes on a fast run and fails on a slow one. Unstable test execution sends developers chasing failures that are not real bugs. Selenium waits fix this by making each command wait for the page state it depends on.

Why Not Use Thread.sleep() in Selenium?

Short answer: don't. Thread.sleep() is a Java construct that stops the program's execution for a specified period (the same idea as time.sleep() in Python, Thread.Sleep() in C# and a setTimeout() pause in JavaScript). It can give automation test scripts the pause they need, but it brings problems that discourage its use:

• Make Test Scripts Inefficient: Invocation of Thread.sleep() method waits for the specified period irrespective of any situation. This static behavior leads to unnecessary delays in executing the test scripts. Regardless of the load time of the elements while testing, the script will wait for a static duration and increase the test execution time.
• Requires Explicit addition after every Selenium Command: While adding waits in the test scripts using Thread.sleep(), it requires adding it all the places, even though there is a requirement of a constant wait before accessing any element of the web page. This makes the test scripts difficult to maintain with time.
• Sleep Duration Calculation: Determining the correct values for the sleep duration would become an essential and challenging task for every Selenium command.

Selenium waits solve these problems by waiting for a condition instead of a fixed time, so a step continues as soon as the page is ready.

What are Selenium Waits?

Selenium Waits is a test automation concept defined as three commands: Implicit Waits, Explicit Waits, and Fluent Waits, that facilitate synchronization between script actions and dynamic web elements.

Each wait polls for a condition and continues as soon as it holds, so the test moves at the speed of the page rather than at a fixed delay. A slow response then costs a few extra polls instead of a failed step.

Types of Selenium Wait Commands

Selenium provides three primary types of wait commands to handle different timing scenarios and enhance the reliability of the automated tests as follows:

• Implicit Wait: Implicit Wait in Selenium is a global wait that applies to all elements in the script. It sets a maximum wait time for any element to become available before interaction. If the element appears within the specified time, the script continues; otherwise, the lookup throws a NoSuchElementException.
• Explicit Wait: Explicit Wait in Selenium is a more granular approach that allows you to wait for a specific condition or element. Explicit waits are applied to individual elements and provide better control and precision. It often uses the WebDriverWait class and expected conditions to define custom waiting criteria. Explicit waits are useful for efficiently handling dynamic web elements with different load times.
• Fluent Wait: Fluent Wait in Selenium allows one to wait for a specific condition to be met with a custom frequency of checking the condition. Fluent waits are particularly useful when dealing with elements that may take varying times to load or change state. This wait is created using the FluentWait class and configured with options like timeout, polling frequency, and exceptions to ignore.

Watch the video to learn about different Selenium wait methods.

What Is Explicit Wait in Selenium?

Explicit wait in Selenium pauses one step of a test until a condition you name is true, such as an element becoming visible or clickable, and throws a TimeoutException if that does not happen within the timeout. In Java, a Selenium explicit wait is a Selenium WebDriverWait object you create where you need it, not a setting applied to the whole driver.

The Selenium documentation describes explicit waits as loops that poll the application for a specific condition and move on to the next command as soon as it evaluates to true. Unlike an implicit wait, which applies to every element lookup, each explicit wait covers one condition on one element.

Puppeteer's closest equivalent is page.waitForSelector(), and Puppeteer timeout covers how its limit is set and what it throws. Cypress has no wait object to create: Cypress timeout covers how its queries retry and how to give one step more time.

For a quick visual walkthrough of this concept, watch the video below from TestMu AI.

Subscribe to the TestMu AI YouTube channel for more tutorials on testing and automation.

The basic form takes the driver and a timeout, then passes a condition to until(), which returns the element once the condition holds:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement element = wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("exampleId")));

This snippet assumes no implicit wait is in play. If one is set, its global timeout stacks on top of this condition and the wait you actually get is neither 10 seconds nor the implicit value.

How Selenium Explicit Wait Works

The until() method evaluates the condition again and again. Per the FluentWait API reference, which WebDriverWait extends, it stops when one of these happens:

• The condition returns a value - anything other than null or false ends the wait, and until() returns that value. That is why the visibility condition above hands back a WebElement.
• The timeout expires - until() throws a TimeoutException.
• The condition throws an exception the wait does not ignore - the exception propagates at once. WebDriverWait ignores NotFoundException by default, the parent class of NoSuchElementException, so an element that does not exist yet is retried instead of failing the step.
• The thread is interrupted - rare in a test, but it also ends the wait.

Between checks, WebDriverWait sleeps for its polling interval, 500 milliseconds by default. Both behaviors show up in the failure message. This wait ran on the TestMu AI cloud grid against an element id that does not exist on the page:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(3));
try {
    wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("profile")));
} catch (TimeoutException e) {
    e.getMessage().lines().limit(2).forEach(System.out::println);
}

Output:

Expected condition failed: waiting for visibility of element found by By.id: profile, but... org.openqa.selenium.NoSuchElementException: no such element: Unable to locate element: {"method":"css selector","selector":"#profile"}.
(tried for 3 seconds with 500 milliseconds interval)

The NoSuchElementException in that message is the last error the wait ignored while polling, not the reason the step failed. The step failed because the condition never held within 3 seconds, so check the locator and the condition before you raise the timeout.

Explicit Wait Syntax in Selenium 4

The older new WebDriverWait(driver, 10) constructor, which took a plain number of seconds, was removed in Selenium 4. The WebDriverWait API reference lists the current constructors, and each one takes a Duration:

• WebDriverWait(driver, timeout) - the usual form, polling every 500 milliseconds.
• WebDriverWait(driver, timeout, sleep) - the second Duration sets the polling interval.
• WebDriverWait(driver, timeout, sleep, clock, sleeper) - also takes the Clock and Sleeper the wait uses to measure time and pause. Test code rarely needs it.

Because WebDriverWait extends FluentWait, it also inherits withMessage(), ignoring(), pollingEvery() and withTimeout(). The condition can be any lambda that returns a value or null, which covers checks that ExpectedConditions does not have. This wait polls every 250 milliseconds, carries its own failure message, and returns the loaded text from a TestMu AI Selenium Playground page:

WebDriverWait custom = new WebDriverWait(driver, Duration.ofSeconds(10), Duration.ofMillis(250));
custom.withMessage("random user never loaded")
      .ignoring(StaleElementReferenceException.class);

driver.findElement(By.id("save")).click();
String text = custom.until(d -> {
    String t = d.findElement(By.id("loading")).getText();
    return t.contains("First Name") ? t : null;
});
System.out.println(text.replace("\n", " ").trim());

Output (the name changes on every run):

First Name : Vickie  Last Name : Murray

The withMessage() text goes into the TimeoutException, so a CI log names the step that timed out. The ignoring() call covers a page that re-renders the element between the lookup and getText(), which would otherwise end the wait with a StaleElementReferenceException.

How to Wait for an Element in Selenium?

To wait for an element in Selenium, create a WebDriverWait and pass until() the condition the next step depends on: visibility before reading text, clickability before a click, invisibility before acting on whatever a spinner covered. There is no single "element loaded" state, so the condition you choose decides what the wait proves.

Waiting for an element to load works the same way. Wait for the content the next step reads, such as the text or the image, not for the container that holds it. The Selenium Playground example below shows what goes wrong otherwise.

Wait Conditions by Goal

Java's ExpectedConditions class and Python's expected_conditions module ship ready-made conditions for the common goals. Pick the row that matches what the next line of the test does:

For an element count in Python, pass a lambda such as lambda d: len(d.find_elements(By.CSS_SELECTOR, "li")) == 3. For worked examples of each condition in both languages, read ExpectedConditions in Selenium.

Wait for an Element on the Selenium Playground

The Dynamic Data Loading demo in TestMu AI's Selenium Playground shows why the condition matters. Clicking Get Random User writes "loading..." into the div with the id loading straight away, then replaces it with a photo and a name once the data arrives.

This Java test waits on that div twice, first for presence and then for the photo, and prints how long each wait took after the click. It runs on the TestMu AI cloud grid with your LT_USERNAME and LT_ACCESS_KEY:

import java.net.URL;
import java.time.Duration;
import java.util.HashMap;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

public class WaitForElementDemo {
    public static void main(String[] args) throws Exception {
        ChromeOptions options = new ChromeOptions();
        options.setBrowserVersion("latest");
        HashMap<String, Object> ltOptions = new HashMap<>();
        ltOptions.put("username", System.getenv("LT_USERNAME"));
        ltOptions.put("accessKey", System.getenv("LT_ACCESS_KEY"));
        ltOptions.put("platformName", "Windows 11");
        ltOptions.put("build", "Selenium Waits");
        ltOptions.put("name", "Wait for element");
        options.setCapability("LT:Options", ltOptions);

        WebDriver driver = new RemoteWebDriver(new URL("https://hub.lambdatest.com/wd/hub"), options);
        try {
            driver.get("https://www.testmuai.com/selenium-playground/dynamic-data-loading-demo/");
            WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(15));

            driver.findElement(By.id("save")).click();
            long start = System.currentTimeMillis();

            // Too early: #loading is already in the DOM, showing a placeholder
            WebElement box = wait.until(ExpectedConditions.presenceOfElementLocated(By.id("loading")));
            System.out.printf("present after %d ms: %s%n",
                    System.currentTimeMillis() - start, box.getText());

            // Right condition: the photo only arrives with the user data
            wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("#loading img")));
            System.out.printf("loaded after %d ms: %s%n",
                    System.currentTimeMillis() - start, box.getText().replace("\n", " ").trim());
        } finally {
            driver.quit();
        }
    }
}

Output on Chrome 156 and Windows 11 (the name changes on every run):

present after 425 ms: loading...
loaded after 2596 ms: First Name : Christian  Last Name : Olsen

The presence wait returned in under half a second with the placeholder text, because the div was in the DOM before the data arrived. A test that read the name at that point would pass or fail depending on how fast the data came back. The visibility wait on the photo returned the real name after about 2.6 seconds.

Across three runs on the TestMu AI grid, presence returned in 165 to 425 ms and the data took 2.0 to 2.6 seconds. Set the timeout well above the slowest normal response, as the 15 seconds here does, so a busy CI runner does not turn a slow response into a failure.