selenium-expect

Playwright-style expect() assertions with auto-retry for Selenium Python. Standalone, no framework required.

Features

• Auto-retry — no explicit WebDriverWait needed; assertions poll until timeout
• Fluent API — expect(el).to_be_visible().not_.to_be_disabled()
• Negation — every assertion supports .not_ out of the box
• Soft assertions — accumulate failures, assert all at once
• Custom matchers — extend expect() with your own assertions via @extend
• Locator re-find — expect(driver, by=By.ID, value="x") re-finds on each poll
• Polling — fixed interval or backoff schedule
• 150+ assertions — elements, lists, cookies, alerts, JS state, shadow DOM, select, iframe, window
• Descriptive errors — timeline, HTML snippet, poll count, custom messages
• Zero dependencies — only requires Selenium 4.10+
• Fully typed — py.typed included, strict mypy clean

Why?

Selenium's WebDriverWait + expected_conditions is verbose and inconsistent. Playwright's expect() is ergonomic and auto-retries. selenium-expect brings that experience to Selenium Python:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium_expect import expect

driver = webdriver.Chrome()

# Auto-retry — no explicit WebDriverWait needed
expect(driver).to_have_title("Dashboard")
expect(driver).to_have_url_contains("/dashboard")

button = driver.find_element(By.ID, "submit")
expect(button).to_be_visible()
expect(button).to_be_enabled()
expect(button).to_have_text("Submit")

# Negation
expect(button).not_.to_be_disabled()

# Lists
items = driver.find_elements(By.CSS_SELECTOR, ".item")
expect(items).to_have_count(5)
expect(items).to_have_texts(["Apple", "Banana", "Cherry", "Date", "Elderberry"])

# Locator-based (re-finds on each poll — no StaleElementReferenceException)
expect(driver, by=By.ID, value="dynamic-content").to_have_text("Loaded!")

Installation

pip install selenium-expect

Requires:

• Python >= 3.11
• selenium >= 4.10

Quickstart

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium_expect import expect, set_default_timeout

# Optional: configure global defaults
set_default_timeout(10)  # 10s timeout for all assertions

driver = webdriver.Chrome()
driver.get("https://example.com")

# Page-level assertions
expect(driver).to_have_title("Example Domain")
expect(driver).to_have_url("https://example.com/")
expect(driver).to_have_page_source_contains("This domain is for use in illustrative examples")

# Element assertions
heading = driver.find_element(By.TAG_NAME, "h1")
expect(heading).to_have_text("Example Domain")
expect(heading).to_have_tag("h1")
expect(heading).to_be_visible()

# Attribute assertions
link = driver.find_element(By.TAG_NAME, "a")
expect(link).to_have_attribute("href", "https://www.iana.org/domains/example")
expect(link).to_have_attribute_contains("href", "iana.org")

# CSS property assertions
expect(heading).to_have_css_property("color", "rgba(0, 0, 0, 1)")

# Negation
expect(link).not_.to_have_text("Click here")

driver.quit()

Configuration

Global defaults

from selenium_expect import (
    set_default_timeout,
    set_default_polling_interval,
    set_default_polling_intervals,
    set_screenshot_on_failure,
    set_debug_mode,
)

set_default_timeout(10)  # 10s timeout (default: 5s)
set_default_polling_interval(0.2)  # 200ms between polls (default: 500ms)
set_default_polling_intervals([0.1, 0.2, 0.5, 1.0])  # Backoff schedule
set_screenshot_on_failure(True, "/tmp/screenshots")
set_debug_mode(True)  # Log each poll attempt

Per-assertion override

# Override timeout for a single assertion
expect(element).to_be_visible(timeout=15)

# Override polling interval
expect(element).to_have_text("Ready", polling=0.1)

# Backoff schedule
expect(element).to_be_clickable(polling=[0.05, 0.1, 0.5, 1.0])

# Custom error message
expect(element).to_have_text("Hello", message="Greeting should say Hello")

# Soft assertion (accumulate failures, check later)
expect(element, soft=True).to_be_visible()
expect(element, soft=True).to_have_text("Hello")
assert_all()  # Raises if any soft assertions failed

Pre-configured expect

from selenium_expect import expect

# Create a variant with pre-applied config
slow_expect = expect.configure(timeout=30, polling=1.0)
slow_expect(driver).to_have_title("Slow Page")

Assertions reference

Driver / Page

Element — State

Element — Text

Element — Attributes

Element — CSS

Element — Identity

Element — Position / Dimensions

Element — Accessibility (Selenium 4+)

List

Alert

Cookie

JavaScript / Browser state

Shadow DOM

Select / Dropdown

Iframe

Window

Advanced features

Soft assertions

Accumulate failures and check them all at once:

from selenium_expect import expect, assert_all

form = driver.find_element(By.ID, "form")

# These won't raise immediately
expect(form, soft=True).to_be_visible()
expect(form, soft=True).to_have_attribute("method", "POST")
expect(form, soft=True).to_have_attribute("action", "/submit")

# Raises AssertionError with all failures if any failed
assert_all()

Custom matchers

Extend expect() with your own assertions:

from selenium_expect import expect, extend


@extend("to_be_in_viewport")
def check_in_viewport(element):
    script = """
        var r = arguments[0].getBoundingClientRect();
        return r.top >= 0 && r.left >= 0 &&
               r.bottom <= window.innerHeight &&
               r.right <= window.innerWidth;
    """
    result = element.parent.execute_script(script, element)
    return result, result


# Use it like any built-in assertion
expect(element).to_be_in_viewport()
expect(element).not_.to_be_in_viewport()

Locator-based expect

Re-finds the element on each poll cycle — eliminates StaleElementReferenceException:

# Instead of:
# element = driver.find_element(By.ID, "dynamic")
# expect(element).to_have_text("Loaded")  # element might go stale

# Use locator-based:
expect(driver, by=By.ID, value="dynamic").to_have_text("Loaded!")

expect.poll()

Retry arbitrary functions:

from selenium_expect import expect, poll

# Poll a JavaScript result
expect.poll(lambda: driver.execute_script("return localStorage.getItem('token')")).to_equal(
    "abc123"
)

# Poll with timeout
expect.poll(
    lambda: driver.execute_script("return document.readyState"),
    timeout=30,
).to_equal("complete")

expect.configure()

Create pre-configured expect variants:

# Fast assertions for frequent checks
fast_expect = expect.configure(timeout=1.0, polling=0.1)
fast_expect(button).to_be_visible()

# Strict assertions for critical paths
strict_expect = expect.configure(timeout=30.0, soft=True)
strict_expect(form).to_be_visible()
strict_expect(form).to_have_attribute("method", "POST")
assert_all()  # Check all soft assertions

Composition

Combine multiple assertions:

from selenium_expect import expect

# All must pass (AND)
expect(element).to_satisfy_all(
    lambda e: expect(e).to_be_visible(),
    lambda e: expect(e).to_be_enabled(),
    lambda e: expect(e).to_have_text("Submit"),
)

# At least one must pass (OR)
expect(element).to_satisfy_any(
    lambda e: expect(e).to_have_text("Save"),
    lambda e: expect(e).to_have_text("Submit"),
)

# None must pass (NOT)
expect(element).to_satisfy_none(
    lambda e: expect(e).to_be_disabled(),
    lambda e: expect(e).to_be_hidden(),
)

Comparison

Error messages

selenium-expect produces descriptive, multi-line error messages:

AssertionError: Expected element to have text "Loaded!", but got "Loading..."
  Expected: Loaded!
  Actual:   Loading...
  Element:  <div id="status" class="loading">Loading...</div>
  Waited:   5001ms (10 polls at 0.5s interval)
  Message:  Status should show Loaded! after AJAX completes
  Timeline: [poll 1: Loading..., poll 2: Loading..., ..., poll 10: Loading...]

License

MIT

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

Please report security vulnerabilities privately — see SECURITY.md.

Links

• Documentation
• Changelog
• Contributing
• Security Policy
• Code of Conduct
• Issues
• PyPI

Acknowledgements

Inspired by Playwright's assertion API and @playwright/test's expect(). Built on Selenium Python bindings.