Selenium ExpectedConditions in Python (2026)

TL;DR

Import expected_conditions as EC, create WebDriverWait(driver, seconds), and pass a callable such as EC.visibility_of_element_located((By.ID, "status")) to until. Reuse the returned value, choose conditions based on the next action, and write a small custom callable when built-ins cannot express product readiness.

Key Takeaways

• Python expected_conditions is a module of callable factories, conventionally imported as EC.
• Pass a two-item locator tuple such as (By.ID, "save") to locator-based conditions.
• WebDriverWait.until returns the successful condition value, often a WebElement, list, Alert, or Boolean.
• Presence, visibility, and clickability represent progressively stronger but still distinct readiness contracts.
• Locator-based conditions are usually safer for nodes that appear late or are replaced by front-end rendering.
• Custom Python conditions should be read-only callables that return a useful truthy value on success and False while waiting.

The selenium ExpectedConditions python pattern combines WebDriverWait with callable factories from selenium.webdriver.support.expected_conditions, normally imported as EC. A reliable wait looks like WebDriverWait(driver, 10).until(EC.visibility_of_element_located((By.ID, "status"))). It polls until the condition returns a truthy value or raises TimeoutException.

Python's API is similar in purpose to Java's, but the syntax and return behavior deserve their own treatment. Conditions are functions that create callables, locators are two-item tuples, and custom conditions can be plain functions or classes with call. This guide covers those details with runnable pytest examples and production troubleshooting patterns.

TL;DR

wait = WebDriverWait(driver, 10)

save = wait.until(
    EC.element_to_be_clickable((By.CSS_SELECTOR, "[data-testid='save']"))
)
save.click()

status = wait.until(
    EC.visibility_of_element_located((By.CSS_SELECTOR, "[role='status']"))
)
assert status.text == "Saved"

1. Selenium ExpectedConditions Python: The Callable Model

The expected_conditions module contains factory functions. EC.visibility_of_element_located(locator) returns a predicate. WebDriverWait.until calls that predicate with the driver, sleeps for its polling interval when the result is false, and tries again until the result is truthy or the timeout expires.

This explains two Python details that often confuse new SDETs. First, creating the condition does not run a wait. You must pass it to until or until_not. Second, the result is not always Boolean. Element conditions often return a WebElement, collection conditions return a list, alert_is_present returns Alert, and combination helpers can return an element or list of results. Store and use that value.

The wait ignores NoSuchElementException by default, so a locator-based condition can poll while a node is absent. Other exceptions generally end or influence the wait according to its configuration and the condition's own implementation. Do not add every Selenium exception to ignored_exceptions. Ignoring a context or selector error can turn a precise failure into a vague timeout.

Python does not have a class named ExpectedConditions that you instantiate. The conventional import is:

from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

Using EC keeps conditions readable without wildcard imports. It also makes code review clear about which callable comes from Selenium and which is custom.

2. Create Locator Tuples Correctly

Locator-based Python conditions expect a tuple containing a By strategy and value:

save_locator = (By.CSS_SELECTOR, "button[data-testid='save']")
save = WebDriverWait(driver, 10).until(
    EC.element_to_be_clickable(save_locator)
)

The extra parentheses matter. EC.visibility_of_element_located(By.ID, "status") passes too many arguments. EC.visibility_of_element_located((By.ID, "status")) passes one locator tuple. Store important locators as named tuples in page components to avoid repeating punctuation and selector strings.

Do not call driver.find_element before a locator-based condition unless you specifically need that exact existing node. This code can fail before the wait starts:

# Weak when the element may appear later:
element = driver.find_element(By.ID, "late-content")
wait.until(EC.visibility_of(element))

Prefer:

element = wait.until(
    EC.visibility_of_element_located((By.ID, "late-content"))
)

The preferred version performs lookup within each condition evaluation. It handles initial absence and can pick up a replacement node after a render. EC.visibility_of(element) is still valuable when the lifecycle of a specific WebElement matters, such as proving that an existing element becomes visible without replacement.

Keep selectors unique. A wait cannot decide which of several matching nodes represents the user's target. Responsive pages often contain hidden desktop or mobile duplicates, so scope the locator to the active component or use distinct semantic test IDs.

3. Configure WebDriverWait, Polling, and Ignored Exceptions

The common constructor is WebDriverWait(driver, timeout_in_seconds). Current Selenium Python also accepts poll_frequency and ignored_exceptions:

from selenium.common.exceptions import NoSuchElementException

wait = WebDriverWait(
    driver,
    10,
    poll_frequency=0.2,
    ignored_exceptions=(NoSuchElementException,),
)

Use defaults unless the product state justifies customization. Very frequent polling sends many WebDriver commands, especially expensive on a remote Grid. Very slow polling delays successful tests and can miss short-lived state. A durable UI outcome should not require catching a tiny temporal window.

The timeout is a maximum. until returns as soon as the predicate produces a truthy value. Avoid time.sleep before or after the wait. A fixed sleep does not add readiness information and can make failures much slower.

Do not combine a long implicit wait with explicit waits. Each poll can call find_element, which may itself wait implicitly. The effective timing becomes hard to calculate. Frameworks that rely on explicit conditions commonly set implicit wait to zero.

Use the message parameter of until to describe the business state:

receipt = wait.until(
    EC.visibility_of_element_located(
        (By.CSS_SELECTOR, "[data-testid='receipt']")
    ),
    message="Receipt did not appear after successful checkout",
)

This message supplements the TimeoutException. It does not replace screenshots, DOM evidence, or network diagnostics, but it tells the reader what transition the test expected.

4. Presence, Visibility, and Clickability in Python

Select conditions by the next operation rather than habit.

Presence is intentionally weak. A hidden modal template can satisfy it forever. Visibility adds rendered presence. Clickability in Selenium's expected condition means visible and enabled, not guaranteed clickable under every layout. If an overlay covers the center, WebDriver can still raise ElementClickInterceptedException.

Do not perform three sequential waits for presence, visibility, and clickability. The final condition already locates and checks the element. Redundant polling adds noise without strengthening the contract.

For typing, visibility is often the starting condition, but application-specific read-only or disabled states may need a custom predicate. For clicking, wait for a known loading mask to become invisible before element_to_be_clickable if that mask is part of the product lifecycle.

The Selenium ElementNotInteractableException guide explains what to inspect when the matched node still cannot receive input.

5. A Runnable pytest Example

This self-contained example renders a disabled button, enables it after a short browser timer, then updates a status asynchronously after the click. The test uses conditions on both sides of the action.

import base64

import pytest
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait


@pytest.fixture
def driver():
    browser = webdriver.Chrome()
    yield browser
    browser.quit()


def test_waits_for_button_and_saved_status(driver):
    html = """
    <!doctype html>
    <button id="save" disabled>Save profile</button>
    <p id="status" role="status"></p>
    <script>
      const save = document.querySelector('#save');
      setTimeout(() => { save.disabled = false; }, 300);
      save.addEventListener('click', () => {
        setTimeout(() => {
          document.querySelector('#status').textContent = 'Saved';
        }, 200);
      });
    </script>
    """
    encoded = base64.b64encode(html.encode("utf-8")).decode("ascii")
    driver.get(f"data:text/html;base64,{encoded}")

    wait = WebDriverWait(driver, 5)
    save = wait.until(EC.element_to_be_clickable((By.ID, "save")))
    save.click()

    wait.until(EC.text_to_be_present_in_element((By.ID, "status"), "Saved"))
    status = driver.find_element(By.ID, "status")
    assert status.text == "Saved"

The wait before clicking proves that the button reached the state required for input. The wait after clicking proves that asynchronous application behavior reached the user. A click command returning successfully is not itself a business assertion.

The data URL removes an external website dependency. In a real suite, pin Selenium through your dependency process, run the example against supported browsers, and let your fixture capture artifacts before quit when the test fails.

6. Wait for Text, URLs, Titles, Selections, and Collections

Expected conditions cover several durable states:

• EC.text_to_be_present_in_element(locator, text) checks a substring of element text.
• EC.text_to_be_present_in_element_value(locator, text) checks a control's value.
• EC.title_is and EC.title_contains check the document title.
• EC.url_to_be, EC.url_contains, EC.url_matches, EC.url_changes check navigation.
• EC.element_to_be_selected and EC.element_located_to_be_selected check selection.
• EC.presence_of_all_elements_located returns a nonempty list of present matches.
• EC.visibility_of_any_elements_located returns visible matches when at least one is visible.
• EC.visibility_of_all_elements_located requires all current matches to be visible.

Collection names need careful interpretation. presence_of_all_elements_located becomes truthy when find_elements returns a nonempty list. It does not know the final expected count. If controlled test data requires five rows, write a custom condition that returns the list only when len(elements) == 5.

visibility_of_all_elements_located means every element in the located result is visible. If hidden templates share the selector, the condition may never succeed. Fix the selector instead of extending the timeout. visibility_of_any_elements_located is suitable when one or more visible matches are enough and returns the visible list.

URL conditions are case-sensitive according to their string or regular-expression semantics. url_changes only confirms that the current URL differs from the supplied value, not that navigation reached the correct destination. Prefer url_to_be or url_matches when the final route matters.

Use selection conditions for checkboxes, radio buttons, and selectable options, then assert the business outcome when selection triggers additional behavior.

7. Frames, Alerts, and New Windows

EC.frame_to_be_available_and_switch_to_it waits for a frame and performs the switch. The argument can be a locator tuple, name or ID string, or WebElement according to the Python API.

wait.until(
    EC.frame_to_be_available_and_switch_to_it(
        (By.CSS_SELECTOR, "iframe[title='Payment']")
    )
)
card_number = wait.until(
    EC.visibility_of_element_located((By.NAME, "cardnumber"))
)
card_number.send_keys("4111111111111111")
driver.switch_to.default_content()

The condition returns a truthy result, not the frame element. After the inner work, return to the expected parent or default context explicitly. A later document-level locator will otherwise search inside the frame.

EC.alert_is_present returns the Alert object:

alert = wait.until(EC.alert_is_present())
assert alert.text == "Delete item?"
alert.accept()

For new windows, capture existing handles before the trigger. EC.new_window_is_opened(old_handles) confirms the count increased. EC.number_of_windows_to_be(2) checks an exact count. Neither condition switches automatically. Identify the new handle and call driver.switch_to.window(new_handle).

A wrong context is not a slowness problem. Increasing a wait inside the top document will not find an element that exists only in a frame. Keep context switching next to the condition that depends on it.

8. Use staleness_of and Locator-Based Re-Lookup

Front-end frameworks commonly replace nodes after data refresh. A stored WebElement then raises StaleElementReferenceException. Model the transition instead of catching the exception around unrelated code.

old_results = driver.find_element(By.ID, "results")
driver.find_element(By.ID, "refresh").click()

wait.until(EC.staleness_of(old_results))
new_results = wait.until(
    EC.visibility_of_element_located((By.ID, "results"))
)
assert "Updated" in new_results.text

staleness_of deliberately accepts a WebElement because it asks whether that exact node has detached. After success, use a locator-based condition to obtain the replacement. Do not continue using the old variable.

For an element that may appear late or be replaced before it stabilizes, a locator-based condition already performs fresh lookup on each call. This is usually better than finding early and passing the WebElement to EC.visibility_of.

Avoid a generic decorator that catches StaleElementReferenceException and repeats every page action. A click, submission, or drag may already have taken effect before the exception is observed. Repeat only read-only waits automatically. For non-idempotent actions, determine application state first.

See the Selenium stale element Python guide for component-level recovery patterns.

9. Combine Python Conditions With any_of, all_of, and none_of

Current Selenium Python provides combinators with useful return values. EC.any_of returns the first truthy condition result. EC.all_of returns a list containing each condition's successful result. EC.none_of returns True only when none succeeds.

outcome = wait.until(
    EC.any_of(
        EC.visibility_of_element_located((By.ID, "dashboard")),
        EC.visibility_of_element_located((By.ID, "login-error")),
    )
)

if outcome.get_attribute("id") == "login-error":
    raise AssertionError(f"Login failed: {outcome.text}")

This is appropriate when the product has explicit alternative outcomes. It is not a shortcut for accepting any page state. The test must inspect which branch succeeded and assert accordingly.

all_of can coordinate independent readiness signals:

loader_gone, status_ready = wait.until(
    EC.all_of(
        EC.invisibility_of_element_located((By.ID, "loader")),
        EC.text_to_be_present_in_element((By.ID, "status"), "Ready"),
    )
)
assert loader_gone and status_ready

Keep combinations small. When several predicates represent one domain concept, a named custom callable produces a better message and can return a useful domain value. Prefer a built-in invisibility condition over a confusing inversion with until_not or none_of when a direct name exists.

10. Write Custom Expected Conditions in Python

Any callable that accepts the driver and returns False while waiting can serve as a condition. On success, return True or, better, the useful object. A class makes parameters and repr-style diagnostics clear:

class element_data_state_to_be:
    def __init__(self, locator, expected_state):
        self.locator = locator
        self.expected_state = expected_state

    def __call__(self, driver):
        element = driver.find_element(*self.locator)
        actual = element.get_dom_attribute("data-state")
        return element if actual == self.expected_state else False

    def __repr__(self):
        return (
            f"element_data_state_to_be(locator={self.locator!r}, "
            f"expected_state={self.expected_state!r})"
        )


editor = wait.until(
    element_data_state_to_be(
        (By.CSS_SELECTOR, "[data-testid='editor']"),
        "ready",
    ),
    message="Editor never reached its ready state",
)

A closure is shorter for a condition used once:

def exactly_n_visible(locator, expected_count):
    def predicate(driver):
        elements = driver.find_elements(*locator)
        visible = [element for element in elements if element.is_displayed()]
        return visible if len(visible) == expected_count else False
    return predicate

Conditions must be idempotent and read-only. Do not click a button, refresh a page, create data, or mutate JavaScript state inside a predicate. until may call it many times, making the number of side effects depend on timing. Trigger once outside, then observe.

Catch only exceptions that truly mean not ready. A broad except Exception: return False hides invalid selectors, lost windows, and programming errors until timeout.

11. Use until_not Carefully

WebDriverWait.until_not evaluates a callable until its result becomes false. It can express negative state, but a named expected condition is often clearer:

wait.until_not(
    EC.visibility_of_element_located((By.ID, "temporary-banner"))
)

For elements, prefer EC.invisibility_of_element_located when that is the real intent. It explicitly treats absence, invisibility, and staleness as successful non-visibility according to Selenium's implementation. The named condition is easier to understand in a failure report.

until_not is useful for a custom Boolean that has no built-in negative equivalent. Ensure you understand its return behavior and exceptions. A condition returning an empty list, None, or False is considered false even when that value has domain meaning. Design predicates so truthiness maps cleanly to readiness.

Do not wait for an error message to be not visible as proof of success. It may never have appeared. Wait for the actual success state. Likewise, loader invisibility alone proves only that loading UI ended, not that correct data arrived. Pair it with a result state when the scenario needs that guarantee.

Negative conditions can succeed immediately if the locator is wrong. Validate stable locators through component tests or pair the wait with a positive destination landmark. This is one reason post-action success evidence matters more than the disappearance of an intermediate element.

12. Build a Maintainable Python Wait Layer

Put locators and immediate readiness inside page components, not in universal sleep replacements. A component method can express a coherent transaction:

class ProfileForm:
    SAVE = (By.CSS_SELECTOR, "button[data-testid='save-profile']")
    SAVED = (By.CSS_SELECTOR, "[role='status'][data-state='saved']")

    def __init__(self, driver, timeout=10):
        self.driver = driver
        self.wait = WebDriverWait(driver, timeout)

    def save(self):
        self.wait.until(EC.element_to_be_clickable(self.SAVE)).click()
        return self.wait.until(EC.visibility_of_element_located(self.SAVED))

The method waits for the control and its immediate saved state, then returns the status element. The test can assert exact text or verify persistence. A global wait_and_click(locator) helper cannot know whether a frame switch, overlay wait, confirmation, or post-click result belongs to a component.

Create wait objects where their timeout purpose is clear. A fixture can supply the standard timeout, while a report export component can use a named longer business budget. Avoid dozens of arbitrary values.

At the pytest hook or fixture boundary, capture screenshot, page source or focused HTML, URL, window handles, and safe logs before driver.quit when TimeoutException occurs. Parallel workers need unique artifact paths.

For architecture examples, see the pytest Selenium framework guide. A clean wait layer should make product state visible, not hide it behind retry magic.

13. Selenium ExpectedConditions Python Review Checklist

Review each explicit wait against these questions:

1. Does the condition guarantee what the next operation needs?
2. Is the locator a correct two-item tuple and unique in the active context?
3. Should lookup happen during polling because the node appears or changes later?
4. Is the truthy return value reused directly?
5. Is presence being mistaken for visibility or interaction readiness?
6. Does a known overlay need its own invisibility condition?
7. Does the test wait for the result after the action?
8. Is custom polling read-only, fast, and safe to repeat?
9. Are only expected not-ready exceptions suppressed?
10. Are implicit waits avoided or kept from distorting timing?
11. Does TimeoutException include a useful business message and artifacts?
12. Are alternative outcomes identified and asserted after any_of?
13. Are exact collection counts modeled when final count matters?
14. Are retries limited to observations rather than non-idempotent actions?

If a fixed sleep remains, name the observable state it is trying to approximate. Replace the delay with that state. This change usually makes a test both faster on healthy runs and more informative on broken ones.

Interview Questions and Answers

Q: What are expected_conditions in Selenium Python?

They are factory functions that return callables for common browser states. WebDriverWait.until repeatedly calls the predicate with WebDriver until it returns a truthy value or times out. Successful values can be elements, lists, alerts, or booleans.

Q: Why is a Selenium locator written with double parentheses?

The inner pair creates a tuple such as (By.ID, "save"). The outer parentheses belong to the function call. Locator-based expected conditions receive that tuple as one argument and unpack it during polling.

Q: How do presence and visibility differ?

Presence proves a node exists in the DOM. Visibility also requires displayed state and nonzero dimensions. A hidden template can satisfy presence, so visibility is the better contract for user-facing content.

Q: What does element_to_be_clickable check?

It checks that the target is visible and enabled and returns the WebElement. It does not prove that another element is not covering the click point. I separately synchronize with known overlays or transitions.

Q: How would you create a custom condition?

I write a callable that accepts the driver and returns a useful truthy value on success, otherwise False. It must be fast, read-only, and safe to invoke repeatedly. I catch only exceptions that genuinely mean the state is not ready.

Q: How do any_of and all_of differ?

any_of returns the first truthy condition result, which is useful for explicit alternative outcomes. all_of returns a list of successful results only when every condition succeeds. The test should still interpret and assert the returned branch or values.

Q: How do you wait for a React component replacement?

I wait for EC.staleness_of(old_element), then use a locator-based visibility or presence condition for the replacement. I do not reuse the old WebElement and do not automatically retry side-effecting actions.

Q: How do you debug TimeoutException?

I check the predicate, selector, active frame and window, triggering action, screenshot, DOM evidence, URL, and application logs. I determine whether the state is slow, impossible, or incorrectly described before changing the timeout.

Common Mistakes

• Passing separate locator arguments: Locator-based conditions expect one (By, value) tuple.
• Calling find_element before waiting: The early lookup can fail before WebDriverWait begins polling.
• Using presence for a visible action: A hidden node can be present forever.
• Ignoring the condition's return value: until often returns the exact element, list, or alert needed next.
• Stacking redundant conditions: Choose the condition that fully describes readiness.
• Assuming clickability means unobstructed: Visible and enabled does not exclude overlays.
• Using broad exception handling in custom predicates: Invalid selectors and lost contexts become vague timeouts.
• Putting actions inside a predicate: Polling can repeat a click or submission many times.
• Mixing large implicit waits: Each explicit poll can take unexpectedly long.
• Using until_not when a named invisibility condition exists: Direct conditions communicate semantics better.
• Accepting any_of without checking the winner: Alternative error and success outcomes must be distinguished.
• Waiting only before the click: The asynchronous result needs its own condition and assertion.

Conclusion

Reliable selenium ExpectedConditions python code is built from small, truthful predicates. Use locator tuples, select presence, visibility, clickability, staleness, or a domain-specific callable according to the next step, and reuse the successful value from until. Keep actions outside polling and collect useful evidence when a condition times out.

Choose one flaky sleep in your pytest suite and replace it with the exact user-visible state the test needs. That single change is the best way to internalize the callable model and improve failure quality immediately.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Selenium DevTools in Selenium 4 in Python (2026)
• How to Use Selenium DevTools in Selenium 4 in Java (2026)
• Selenium fluent wait in Python (2026)
• How to Debug a failing test in VS Code in Selenium (2026)
• How to Run tests in headed mode in Selenium (2026)
• How to Use Selenium ExpectedConditions in Java (2026)