Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 35 ยท Waiting and Synchronization

Implicit, Explicit and Fluent Waits

Learn Selenium's three kinds of waits: implicit, explicit with WebDriverWait and expected conditions, and fluent waits with polling and ignored exceptions.

The previous lesson showed that a test should wait for a condition, not for a number of seconds. Selenium gives you three ways to do that: an implicit wait that applies to every element search, an explicit wait that you write for one specific condition, and a fluent wait, which is an explicit wait with every setting spelled out. They share one idea. Check the condition, and if it is false, pause briefly and check again until it is true or a time limit runs out.

In this lesson you will learn how each one works, which settings they have (timeout, polling interval, ignored exceptions), the common expected conditions, and why you should not mix implicit and explicit waits. At the end you will build the polling loop yourself, so there is no mystery left in WebDriverWait.

The Selenium code below is read-only: it needs a real browser and driver. The runnable examples are stand-ins. They use a virtual clock (a number that moves forward when the helper "sleeps"), so the output is exact and the examples finish at once, but the polling logic is the same that Selenium's own wait classes use.

The three waits at a glance

Three ways to wait

Implicit One global timeout for every find_element.
Explicit Wait for one condition at one place.
Fluent Explicit wait with tuned polling and ignores.

Prefer explicit waits in new tests.

1 / 2

Implicit wait

An implicit wait tells the driver: "whenever I search for an element and it is missing, keep searching for up to this long before you raise NoSuchElementException." You set it once per session, and it applies to every find_element and find_elements call afterwards.

Python
# Read-only (Python)
driver.implicitly_wait(5)          # seconds
driver.get("https://shop.example/products")
card = driver.find_element(By.CSS_SELECTOR, ".product-card")   # retries for up to 5 s
Java
// Read-only (Java)
driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(5));

It is simple, but limited. It only waits for an element to exist in the page. It does not wait for the element to be visible, enabled or clickable, it cannot wait for text to change, and it cannot wait for something to disappear. A failed search is also slow: with a 5 second implicit wait, every find_elements that correctly returns "nothing" costs 5 seconds.

Explicit wait with expected conditions

An explicit wait names the condition and applies only where you write it. In Python it is WebDriverWait plus a helper from expected_conditions. In Java it is WebDriverWait plus ExpectedConditions.

Python
# Read-only (Python)
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

wait = WebDriverWait(driver, timeout=10)
button = wait.until(EC.element_to_be_clickable((By.ID, "checkout")))
button.click()
Java
// Read-only (Java)
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement button = wait.until(ExpectedConditions.elementToBeClickable(By.id("checkout")));
button.click();

wait.until(condition) calls the condition again and again. It returns the condition's result as soon as the result is "truthy" (for most conditions that is the element itself, which is why you can chain .click()). If the time limit passes first, it raises TimeoutException.

Some expected conditions you will use often:

Condition Waits until
presence_of_element_located the element is in the page (may be hidden)
visibility_of_element_located the element is in the page and visible
element_to_be_clickable it is visible and enabled
invisibility_of_element_located the element is gone or hidden (good for spinners)
text_to_be_present_in_element the element's text contains the given text
url_contains, title_contains the URL or title contains the text
staleness_of the old element reference has gone stale (page refreshed)
alert_is_present a JavaScript alert is showing

Because a condition is just a function, you can also pass your own. In Python, any callable that takes the driver works, for example a lambda:

Python
# Read-only: a custom condition
wait.until(lambda d: len(d.find_elements(By.CSS_SELECTOR, ".product-card")) >= 3)

Pick the condition that matches the next action. Before a click, wait for element_to_be_clickable. Before reading text, wait for visibility. After a click that starts a long operation, wait for a spinner to become invisible. Waiting for presence and then clicking is a common source of ElementNotInteractable.

Fluent wait: every knob visible

WebDriverWait is a ready-made fluent wait with sensible defaults: it polls every 500 milliseconds and ignores NoSuchElementException. In Java you can build a FluentWait by hand and choose each setting. In Python you can pass the same settings to WebDriverWait.

Java
// Read-only (Java)
Wait<WebDriver> wait = new FluentWait<>(driver)
    .withTimeout(Duration.ofSeconds(30))
    .pollingEvery(Duration.ofMillis(250))
    .ignoring(NoSuchElementException.class)
    .ignoring(StaleElementReferenceException.class)
    .withMessage("Order total never appeared");

WebElement total = wait.until(d -> d.findElement(By.id("total")));
Python
# Read-only (Python): the same idea
wait = WebDriverWait(
    driver,
    timeout=30,
    poll_frequency=0.25,
    ignored_exceptions=[StaleElementReferenceException],
)
total = wait.until(EC.visibility_of_element_located((By.ID, "total")))
  • Timeout. The most time the wait may take. Choose a value long enough for your slowest healthy case and short enough that a real failure does not hang the build. Ten to thirty seconds is typical for web apps.
  • Polling interval. How long to pause between checks. A very short interval burns CPU and floods the driver with commands. A very long one adds delay after the page is ready. The default 500 ms is a fine start.
  • Ignored exceptions. Exceptions that mean "not yet" rather than "failed". Python's WebDriverWait ignores NoSuchElementException by default. Adding StaleElementReferenceException helps when the page re-renders while you are polling.

The loop inside every wait

Here is the whole mechanism in one function. It takes a condition, a timeout and a polling interval. It calls the condition, treats an ignored error as "not yet", sleeps, and tries again. The clock is virtual, so you can read exact numbers.

Node.js Build a poll-until helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read the three results. With a 500 ms interval, the element appears at 1,300 ms but the wait only notices it on the check at 1,500 ms, so the polling interval is the largest delay you can add. With a 1,000 ms timeout the wait gives up and says what the last ignored error was, which is how Selenium's TimeoutException messages help you. In the last call, nothing is ignored, so the first NoSuchElement ends the wait at once. That is why Selenium ignores NoSuchElementException by default: without it, an element that is merely late would fail instantly.

Why you should not mix implicit and explicit waits

If you set an implicit wait and use WebDriverWait, the two stack in confusing ways. Each time the explicit wait's condition calls find_element, the driver itself retries for the implicit time before the condition even sees a failure. A 10 second explicit wait with an 8 second implicit wait can therefore run for well over 15 seconds, and the exact total depends on the driver. The Selenium project explicitly advises against combining them.

The stand-in below models that: each failed find inside an explicit wait first burns the implicit time, and the loop only checks the timeout between attempts.

Node.js Implicit plus explicit wait

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The same 10 second explicit wait gives up at 10,000 ms with no implicit wait, but at 13,000 ms with a 4 second implicit wait and at 16,500 ms with an 8 second one. The explicit loop only checks its deadline between attempts, and each attempt now lasts as long as the implicit wait, so the deadline is overshot by up to a whole attempt. A test that should have failed in 10 seconds takes much longer, and the number is hard to predict. The fix is simple: leave the implicit wait at its default of zero and use explicit waits everywhere.

flowchart TD
  A["wait.until(condition)"] --> B{"Condition true?"}
  B -->|yes| C["Return the result"]
  B -->|"no, or ignored error"| D{"Timeout reached?"}
  D -->|no| E["Sleep for the polling interval"]
  E --> B
  D -->|yes| F["Raise TimeoutException"]

Every explicit and fluent wait runs this loop; only the condition and the three settings differ.

Choosing between them

  • Use explicit waits by default. They say what you are waiting for, they work for visibility, clickability, text and disappearance, and a failure message points at the exact line.
  • Use a fluent wait (or extra arguments to WebDriverWait) when you need a custom polling interval or extra ignored exceptions, for example with pages that re-render often.
  • Avoid the implicit wait. It is acceptable in small throwaway scripts, but it hides timing, slows down negative checks, and conflicts with explicit waits.
  • Keep waits short and specific. A long timeout does not slow a passing test, because the wait returns as soon as the condition is true; it only delays a real failure.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does WebDriverWait(driver, 10).until(condition) do when the condition never becomes true?

    The wait polls until the condition is truthy or the timeout passes. At the timeout it raises TimeoutException, optionally with a message that you supply.
  2. 2. Which expected condition fits best right before calling click() on a button?

    A button must be visible and enabled to receive a click. element_to_be_clickable checks both, while presence only checks that the element exists in the page.
  3. 3. Why is mixing an implicit wait with explicit waits discouraged?

    Each element lookup inside the explicit wait first retries for the implicit time, so the timeouts add up in ways that depend on the driver. Use only explicit waits.
  4. 4. What is the role of the polling interval?

    The timeout is the total limit. The polling interval is the pause between attempts; the default in Selenium is half a second.
  5. 5. A page re-renders a table while your wait polls for a row, and sometimes the lookup raises StaleElementReferenceException. What helps?

    Ignoring the stale error makes the wait try again with a fresh lookup instead of failing on one unlucky poll.

Summary

  • A wait repeats a check until it passes or a timeout expires; polling interval and ignored exceptions tune the loop.
  • The implicit wait is global, only waits for presence, and slows down "element not found" checks.
  • WebDriverWait with expected_conditions is the standard explicit wait; until returns the result and raises TimeoutException on failure.
  • A fluent wait lets you set timeout, polling, ignored exceptions and a message in one place.
  • Do not mix implicit and explicit waits; keep the implicit wait at zero.

Next: The Page Object Model.