API reference¶

This page provides a complete reference for all public APIs in selenium-expect.

expect() — Entry point for all assertions
poll() — Poll-based assertions on arbitrary functions
extend() — Register custom matchers
merge_expects() — Combine matchers from modules
SoftAssertionCollector — Soft assertion management
assert_all() — Raise collected soft failures
ExpectConfig — Configuration dataclass
Configuration setters — Global defaults
Assertion classes — All assertion class references

`expect(target, ...)`¶

Create an assertion for the given target. Dispatches to the appropriate assertion class based on the target's type.

Supported targets¶

Target type	Assertion class	Example
`WebElement`	`ExpectElement`	`expect(element).to_be_visible()`
`WebDriver`	`ExpectDriver`	`expect(driver).to_have_title("Page")`
`list[WebElement]`	`ExpectList`	`expect(elements).to_have_count(5)`
`Alert`	`ExpectAlert`	`expect(alert).to_have_text("Confirm?")`
`Select`	`ExpectSelect`	`expect(select).to_have_value("opt1")`
`ShadowRoot`	`ExpectShadow`	`expect(shadow).to_have_element(By.ID, "x")`
`WebDriver` + `by`/`value`	`LocatorExpect`	`expect(driver, by=By.ID, value="x").to_be_visible()`

Parameters¶

Parameter	Type	Default	Description
`target`	`Any`	—	The object to assert on
`by`	`str`	`None`	Locator strategy (for locator-based expect)
`value`	`str`	`None`	Locator value (for locator-based expect)
`locator`	`tuple[str, str]`	`None`	`(by, value)` tuple shorthand
`message`	`str`	`None`	Custom message for error output
`soft`	`bool \\| None`	`None`	Enable soft assertion mode (`None` inherits global config)
`timeout`	`float`	`None`	Override default timeout
`polling`	`float \\| list[float]`	`None`	Override default polling

selenium_expect._expect.Expect ¶

Callable expect dispatcher with attached utilities.

Use expect(target) to create assertions, expect.poll(fn) for retry-based polling, and expect.configure(...) for pre-configured variants.

Source code in selenium_expect/_expect.py

class Expect:
    """Callable expect dispatcher with attached utilities.

    Use ``expect(target)`` to create assertions, ``expect.poll(fn)`` for
    retry-based polling, and ``expect.configure(...)`` for pre-configured
    variants.
    """

    def __call__(
        self,
        target: Any,
        /,
        *,
        message: str | None = None,
        timeout: float | None = None,
        polling: float | list[float] | None = None,
        soft: bool | None = None,
        config: ExpectConfig | None = None,
        by: str | None = None,
        value: str | None = None,
        locator: tuple[str, str] | None = None,
    ) -> AssertionMixin:
        """Create an expect assertion for the given target.

        Dispatches to the appropriate assertion class via ``ASSERTION_REGISTRY``
        based on the target's type.

        If ``by`` and ``value`` are provided, a ``LocatorExpect`` is created
        that re-finds the element on each poll cycle.

        Alternatively, ``locator=(By.ID, 'foo')`` can be used as a tuple
        shorthand for ``by=..., value=...``.
        """
        if locator is not None:
            if by is not None or value is not None:
                raise ValueError("Cannot use both 'locator' and 'by/value' arguments")
            by, value = locator

        if (by is not None) != (value is not None):
            raise ValueError("Must provide both 'by' and 'value', or neither")

        if by is not None and value is not None:
            from selenium_expect._locator import LocatorExpect

            if not isinstance(target, WebDriver):
                raise TypeError("expect() with by/value requires a WebDriver target")

            effective_config = _effective_config(config, timeout, polling, soft)

            return LocatorExpect(
                driver=target,
                by=by,
                value=value,
                config=effective_config,
                message=message,
            )

        if target is None:
            raise TypeError("expect() does not support None as target")

        type_name = _resolve_target_type(target)
        cls = ASSERTION_REGISTRY.get(type_name)
        if cls is None:
            raise TypeError(f"expect() does not support target type '{type_name}'")

        assertion_cls = cast(type[AssertionMixin], cls)

        effective_config = _effective_config(config, timeout, polling, soft)

        return assertion_cls(target=target, config=effective_config, message=message)

    def poll(
        self,
        fn: Callable[[], Any],
        *,
        timeout: float | None = None,
        polling: float | list[float] | None = None,
        config: ExpectConfig | None = None,
    ) -> PollAssertion:
        """Create a ``PollAssertion`` for retry-based assertions on *fn*.

        Usage::

            expect.poll(lambda: driver.execute_script("return document.readyState"))
                .to_equal("complete")
        """
        return PollAssertion(fn, timeout=timeout, polling=polling, config=config)

    def configure(self, **defaults: Any) -> Callable[..., AssertionMixin]:
        """Create a pre-configured expect variant.

        Returns a callable that behaves like ``expect()`` with *defaults*
        pre-applied. Explicit kwargs from the caller override the defaults.

        Usage::

            fast_expect = expect.configure(timeout=1.0, polling=0.1)
            fast_expect(el).to_be_visible()
        """

        def _configured_expect(
            target: Any,
            /,
            **overrides: Any,
        ) -> AssertionMixin:
            merged: dict[str, Any] = {**defaults, **overrides}
            return self(target, **merged)

        def _configured_poll(
            fn: Callable[[], Any],
            /,
            **overrides: Any,
        ) -> PollAssertion:
            poll_keys = ("timeout", "polling", "config")
            merged = {
                **{k: v for k, v in defaults.items() if k in poll_keys},
                **overrides,
            }
            return self.poll(fn, **merged)

        _configured_expect.poll = _configured_poll  # type: ignore[attr-defined]
        return _configured_expect

call ¶

__call__(target: Any, /, *, message: str | None = None, timeout: float | None = None, polling: float | list[float] | None = None, soft: bool | None = None, config: ExpectConfig | None = None, by: str | None = None, value: str | None = None, locator: tuple[str, str] | None = None) -> AssertionMixin

Create an expect assertion for the given target.

Dispatches to the appropriate assertion class via ASSERTION_REGISTRY based on the target's type.

If by and value are provided, a LocatorExpect is created that re-finds the element on each poll cycle.

Alternatively, locator=(By.ID, 'foo') can be used as a tuple shorthand for by=..., value=....

Source code in selenium_expect/_expect.py

def __call__(
    self,
    target: Any,
    /,
    *,
    message: str | None = None,
    timeout: float | None = None,
    polling: float | list[float] | None = None,
    soft: bool | None = None,
    config: ExpectConfig | None = None,
    by: str | None = None,
    value: str | None = None,
    locator: tuple[str, str] | None = None,
) -> AssertionMixin:
    """Create an expect assertion for the given target.

    Dispatches to the appropriate assertion class via ``ASSERTION_REGISTRY``
    based on the target's type.

    If ``by`` and ``value`` are provided, a ``LocatorExpect`` is created
    that re-finds the element on each poll cycle.

    Alternatively, ``locator=(By.ID, 'foo')`` can be used as a tuple
    shorthand for ``by=..., value=...``.
    """
    if locator is not None:
        if by is not None or value is not None:
            raise ValueError("Cannot use both 'locator' and 'by/value' arguments")
        by, value = locator

    if (by is not None) != (value is not None):
        raise ValueError("Must provide both 'by' and 'value', or neither")

    if by is not None and value is not None:
        from selenium_expect._locator import LocatorExpect

        if not isinstance(target, WebDriver):
            raise TypeError("expect() with by/value requires a WebDriver target")

        effective_config = _effective_config(config, timeout, polling, soft)

        return LocatorExpect(
            driver=target,
            by=by,
            value=value,
            config=effective_config,
            message=message,
        )

    if target is None:
        raise TypeError("expect() does not support None as target")

    type_name = _resolve_target_type(target)
    cls = ASSERTION_REGISTRY.get(type_name)
    if cls is None:
        raise TypeError(f"expect() does not support target type '{type_name}'")

    assertion_cls = cast(type[AssertionMixin], cls)

    effective_config = _effective_config(config, timeout, polling, soft)

    return assertion_cls(target=target, config=effective_config, message=message)

configure ¶

configure(**defaults: Any) -> Callable[..., AssertionMixin]

Create a pre-configured expect variant.

Returns a callable that behaves like expect() with defaults pre-applied. Explicit kwargs from the caller override the defaults.

Usage::

fast_expect = expect.configure(timeout=1.0, polling=0.1)
fast_expect(el).to_be_visible()

Source code in selenium_expect/_expect.py

def configure(self, **defaults: Any) -> Callable[..., AssertionMixin]:
    """Create a pre-configured expect variant.

    Returns a callable that behaves like ``expect()`` with *defaults*
    pre-applied. Explicit kwargs from the caller override the defaults.

    Usage::

        fast_expect = expect.configure(timeout=1.0, polling=0.1)
        fast_expect(el).to_be_visible()
    """

    def _configured_expect(
        target: Any,
        /,
        **overrides: Any,
    ) -> AssertionMixin:
        merged: dict[str, Any] = {**defaults, **overrides}
        return self(target, **merged)

    def _configured_poll(
        fn: Callable[[], Any],
        /,
        **overrides: Any,
    ) -> PollAssertion:
        poll_keys = ("timeout", "polling", "config")
        merged = {
            **{k: v for k, v in defaults.items() if k in poll_keys},
            **overrides,
        }
        return self.poll(fn, **merged)

    _configured_expect.poll = _configured_poll  # type: ignore[attr-defined]
    return _configured_expect

poll ¶

poll(fn: Callable[[], Any], *, timeout: float | None = None, polling: float | list[float] | None = None, config: ExpectConfig | None = None) -> PollAssertion

Create a PollAssertion for retry-based assertions on fn.

Usage::

expect.poll(lambda: driver.execute_script("return document.readyState"))
    .to_equal("complete")

Source code in selenium_expect/_expect.py

def poll(
    self,
    fn: Callable[[], Any],
    *,
    timeout: float | None = None,
    polling: float | list[float] | None = None,
    config: ExpectConfig | None = None,
) -> PollAssertion:
    """Create a ``PollAssertion`` for retry-based assertions on *fn*.

    Usage::

        expect.poll(lambda: driver.execute_script("return document.readyState"))
            .to_equal("complete")
    """
    return PollAssertion(fn, timeout=timeout, polling=polling, config=config)

`ExpectConfig`¶

Immutable configuration dataclass for all assertions.

Fields¶

Field	Type	Default	Description
`timeout`	`float`	`5.0`	Default timeout in seconds
`polling_interval`	`float`	`0.5`	Fixed polling interval
`polling_intervals`	`list[float] \\| None`	`None`	Backoff schedule
`screenshot_on_failure`	`bool`	`False`	Capture screenshot on failure
`screenshot_path`	`str \\| None`	`None`	Screenshot directory
`debug_mode`	`bool`	`False`	Debug logging
`soft_mode`	`bool`	`False`	Soft assertion mode

Usage¶

from selenium_expect import ExpectConfig, expect

# Create a custom config
config = ExpectConfig(timeout=10, polling_interval=0.25, debug_mode=True)

# Use it per call or pre-apply it with expect.configure()
expect(element, config=config).to_be_visible()
debug_expect = expect.configure(config=config)
debug_expect(element).to_be_visible()

selenium_expect._config.ExpectConfig `dataclass` ¶

Immutable configuration for expect assertions.

Use replace() to create a new instance with overridden fields. The global config singleton is mutated via the module-level setters.

Source code in selenium_expect/_config.py

@dataclass(frozen=True, slots=True)
class ExpectConfig:
    """Immutable configuration for expect assertions.

    Use ``replace()`` to create a new instance with overridden fields.
    The global config singleton is mutated via the module-level setters.
    """

    timeout: float = 5.0
    polling_interval: float = 0.5
    polling_intervals: Sequence[float] | None = None
    screenshot_on_failure: bool = False
    screenshot_path: str | None = None
    debug_mode: bool = False
    soft_mode: bool = False

    def __post_init__(self) -> None:
        if self.timeout < 0:
            raise ValueError(f"timeout must be >= 0, got {self.timeout}")
        if self.polling_interval < 0:
            raise ValueError(f"polling_interval must be >= 0, got {self.polling_interval}")
        if self.polling_intervals is not None:
            # Store as tuple so the frozen dataclass is truly immutable.
            object.__setattr__(self, "polling_intervals", tuple(self.polling_intervals))
            if len(self.polling_intervals) == 0:
                raise ValueError("polling_intervals must not be empty; use None for fixed interval")
            for i, interval in enumerate(self.polling_intervals):
                if interval < 0:
                    raise ValueError(f"polling_intervals[{i}] must be >= 0, got {interval}")

    def replace(self, **kwargs: Any) -> ExpectConfig:
        """Return a new instance with overridden fields."""
        return _replace(self, **kwargs)

replace ¶

replace(**kwargs: Any) -> ExpectConfig

Return a new instance with overridden fields.

Source code in selenium_expect/_config.py

def replace(self, **kwargs: Any) -> ExpectConfig:
    """Return a new instance with overridden fields."""
    return _replace(self, **kwargs)

`poll(fn, ...)`¶

Create a PollAssertion for retry-based assertions on an arbitrary function.

Parameters¶

Parameter	Type	Default	Description
`fn`	`Callable[[], Any]`	—	Zero-argument callable to poll
`timeout`	`float`	`None`	Override default timeout
`polling`	`float \\| list[float]`	`None`	Override default polling

Example¶

from selenium_expect import expect, poll

# Using expect.poll
expect.poll(lambda: driver.execute_script("return document.readyState")).to_equal("complete")

# Using standalone poll
poll(lambda: driver.current_url, timeout=10).to_match(r"https://.*\.example\.com")

selenium_expect._poll.poll ¶

poll(fn: Callable[[], Any], *, timeout: float | None = None, polling: float | list[float] | None = None, config: ExpectConfig | None = None) -> PollAssertion

Create a PollAssertion for retry-based assertions on fn.

Usage::

poll(lambda: driver.execute_script("return document.readyState"))
    .to_equal("complete")

Source code in selenium_expect/_poll.py

def poll(
    fn: Callable[[], Any],
    *,
    timeout: float | None = None,
    polling: float | list[float] | None = None,
    config: ExpectConfig | None = None,
) -> PollAssertion:
    """Create a ``PollAssertion`` for retry-based assertions on *fn*.

    Usage::

        poll(lambda: driver.execute_script("return document.readyState"))
            .to_equal("complete")
    """
    return PollAssertion(fn, timeout=timeout, polling=polling, config=config)

`PollAssertion`¶

Assertion over an arbitrary function with retry loop.

Methods¶

Method	Description
`to_equal(expected)`	Assert `fn() == expected`
`to_be_truthy()`	Assert `bool(fn())` is `True`
`to_be_falsy()`	Assert `bool(fn())` is `False`
`to_be_none()`	Assert `fn()` is `None`
`to_contain(expected)`	Assert `expected in fn()`
`to_match(pattern)`	Assert `re.search(pattern, str(fn()))` matches
`to_be_greater_than(expected)`	Assert `fn() > expected`
`to_be_less_than(expected)`	Assert `fn() < expected`
`to_be_in_list(expected)`	Assert `fn() in expected`
`to_have_length(expected)`	Assert `len(fn()) == expected`

selenium_expect._poll.PollAssertion ¶

Assertion over an arbitrary function with retry loop.

Source code in selenium_expect/_poll.py

class PollAssertion:
    """Assertion over an arbitrary function with retry loop."""

    def __init__(
        self,
        fn: Callable[[], Any],
        timeout: float | None = None,
        polling: float | list[float] | None = None,
        config: ExpectConfig | None = None,
    ) -> None:
        self._fn = fn
        self._config = config if config is not None else get_config()
        self._timeout = _normalize_timeout(timeout) if timeout is not None else self._config.timeout
        if self._timeout < 0:
            raise ValueError(f"timeout must be >= 0, got {self._timeout}")
        if polling is None:
            self._polling_interval = self._config.polling_interval
            self._polling_intervals = self._config.polling_intervals
        elif isinstance(polling, list):
            if len(polling) == 0:
                raise ValueError("polling list must not be empty; use a float for fixed interval")
            self._polling_interval = 0.5
            self._polling_intervals = polling
        else:
            self._polling_interval = _normalize_timeout(polling)
            self._polling_intervals = None
        if self._polling_interval < 0:
            raise ValueError(f"polling interval must be >= 0, got {self._polling_interval}")
        if self._polling_intervals is not None:
            for i, interval in enumerate(self._polling_intervals):
                if interval < 0:
                    raise ValueError(f"polling_intervals[{i}] must be >= 0, got {interval}")

    def _run(
        self,
        condition: Callable[[], tuple[bool, Any]],
        condition_name: str,
        expected: Any = None,
    ) -> None:
        """Execute the retry loop and raise on failure."""
        result = retry_until(
            condition=condition,
            timeout=self._timeout,
            polling_interval=self._polling_interval,
            polling_intervals=self._polling_intervals,
            debug=self._config.debug_mode,
        )
        if result.passed:
            return
        error_msg = AssertionFormatter.format_error(
            entity="poll()",
            condition=condition_name,
            expected=expected,
            actual=result.actual_value,
            elapsed_ms=result.elapsed_ms,
            poll_count=result.poll_count,
            polling_interval=self._polling_interval,
            timeline=result.timeline,
        )
        if self._config.soft_mode:
            from selenium_expect._soft import SoftAssertionCollector

            SoftAssertionCollector.add_failure(error_msg)
        else:
            raise AssertionError(error_msg)

    def to_equal(self, expected: Any) -> Self:
        """Assert fn() == expected."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            return (actual == expected, actual)

        self._run(condition, f"to equal {expected!r}", expected)

        return self

    def to_be_truthy(self) -> Self:
        """Assert bool(fn()) is True."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            return (bool(actual), actual)

        self._run(condition, "to be truthy", True)

        return self

    def to_be_falsy(self) -> Self:
        """Assert bool(fn()) is False."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            return (not bool(actual), actual)

        self._run(condition, "to be falsy", False)

        return self

    def to_be_none(self) -> Self:
        """Assert fn() is None."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            return (actual is None, actual)

        self._run(condition, "to be None", None)

        return self

    def to_contain(self, expected: Any) -> Self:
        """Assert expected in fn()."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            if actual is None:
                return (False, actual)
            try:
                return (expected in actual, actual)
            except TypeError:
                return (False, f"not iterable: {actual!r}")

        self._run(condition, f"to contain {expected!r}", expected)

        return self

    def to_match(self, pattern: str) -> Self:
        """Assert re.search(pattern, str(fn()))."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            return (re.search(pattern, str(actual)) is not None, actual)

        self._run(condition, f"to match {pattern!r}", pattern)

        return self

    def to_be_greater_than(self, expected: Any) -> Self:
        """Assert fn() > expected."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            try:
                return (actual > expected, actual)
            except TypeError:
                return (False, f"not comparable: {actual!r} > {expected!r}")

        self._run(condition, f"to be greater than {expected}", expected)

        return self

    def to_be_less_than(self, expected: Any) -> Self:
        """Assert fn() < expected."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            try:
                return (actual < expected, actual)
            except TypeError:
                return (False, f"not comparable: {actual!r} < {expected!r}")

        self._run(condition, f"to be less than {expected}", expected)

        return self

    def to_be_in_list(self, expected: list[Any]) -> Self:
        """Assert fn() in expected."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            return (actual in expected, actual)

        self._run(condition, f"to be in {expected!r}", expected)

        return self

    def to_have_length(self, expected: int) -> Self:
        """Assert len(fn()) == expected."""
        fn = self._fn

        def condition() -> tuple[bool, Any]:
            actual = fn()
            try:
                actual_len = len(actual)
            except TypeError:
                return (False, f"no len() for {actual!r}")
            return (actual_len == expected, actual_len)

        self._run(condition, f"to have length {expected}", expected)

        return self

to_be_falsy ¶

to_be_falsy() -> Self

Assert bool(fn()) is False.

Source code in selenium_expect/_poll.py

def to_be_falsy(self) -> Self:
    """Assert bool(fn()) is False."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        return (not bool(actual), actual)

    self._run(condition, "to be falsy", False)

    return self

to_be_greater_than ¶

to_be_greater_than(expected: Any) -> Self

Assert fn() > expected.

Source code in selenium_expect/_poll.py

def to_be_greater_than(self, expected: Any) -> Self:
    """Assert fn() > expected."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        try:
            return (actual > expected, actual)
        except TypeError:
            return (False, f"not comparable: {actual!r} > {expected!r}")

    self._run(condition, f"to be greater than {expected}", expected)

    return self

to_be_in_list ¶

to_be_in_list(expected: list[Any]) -> Self

Assert fn() in expected.

Source code in selenium_expect/_poll.py

def to_be_in_list(self, expected: list[Any]) -> Self:
    """Assert fn() in expected."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        return (actual in expected, actual)

    self._run(condition, f"to be in {expected!r}", expected)

    return self

to_be_less_than ¶

to_be_less_than(expected: Any) -> Self

Assert fn() < expected.

Source code in selenium_expect/_poll.py

def to_be_less_than(self, expected: Any) -> Self:
    """Assert fn() < expected."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        try:
            return (actual < expected, actual)
        except TypeError:
            return (False, f"not comparable: {actual!r} < {expected!r}")

    self._run(condition, f"to be less than {expected}", expected)

    return self

to_be_none ¶

to_be_none() -> Self

Assert fn() is None.

Source code in selenium_expect/_poll.py

def to_be_none(self) -> Self:
    """Assert fn() is None."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        return (actual is None, actual)

    self._run(condition, "to be None", None)

    return self

to_be_truthy ¶

to_be_truthy() -> Self

Assert bool(fn()) is True.

Source code in selenium_expect/_poll.py

def to_be_truthy(self) -> Self:
    """Assert bool(fn()) is True."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        return (bool(actual), actual)

    self._run(condition, "to be truthy", True)

    return self

to_contain ¶

to_contain(expected: Any) -> Self

Assert expected in fn().

Source code in selenium_expect/_poll.py

def to_contain(self, expected: Any) -> Self:
    """Assert expected in fn()."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        if actual is None:
            return (False, actual)
        try:
            return (expected in actual, actual)
        except TypeError:
            return (False, f"not iterable: {actual!r}")

    self._run(condition, f"to contain {expected!r}", expected)

    return self

to_equal ¶

to_equal(expected: Any) -> Self

Assert fn() == expected.

Source code in selenium_expect/_poll.py

def to_equal(self, expected: Any) -> Self:
    """Assert fn() == expected."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        return (actual == expected, actual)

    self._run(condition, f"to equal {expected!r}", expected)

    return self

to_have_length ¶

to_have_length(expected: int) -> Self

Assert len(fn()) == expected.

Source code in selenium_expect/_poll.py

def to_have_length(self, expected: int) -> Self:
    """Assert len(fn()) == expected."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        try:
            actual_len = len(actual)
        except TypeError:
            return (False, f"no len() for {actual!r}")
        return (actual_len == expected, actual_len)

    self._run(condition, f"to have length {expected}", expected)

    return self

to_match ¶

to_match(pattern: str) -> Self

Assert re.search(pattern, str(fn())).

Source code in selenium_expect/_poll.py

def to_match(self, pattern: str) -> Self:
    """Assert re.search(pattern, str(fn()))."""
    fn = self._fn

    def condition() -> tuple[bool, Any]:
        actual = fn()
        return (re.search(pattern, str(actual)) is not None, actual)

    self._run(condition, f"to match {pattern!r}", pattern)

    return self

`extend(name)`¶

Decorator to register a custom matcher under name.

Parameters¶

Parameter	Type	Description
`name`	`str`	Method name to register (e.g. `"to_be_in_viewport"`)

Matcher signature¶

def my_matcher(target: Any, *args, **kwargs) -> tuple[bool, Any]:
    ...
    return (passed, actual_value)

Example¶

from selenium_expect import extend

@extend("to_have_trimmed_text")
def check_trimmed_text(element, expected: str):
    actual = element.text.strip()
    return (actual == expected, actual)

# Usage
expect(element).to_have_trimmed_text("Hello!")
expect(element).not_.to_have_trimmed_text("  Hello!  ")

selenium_expect._matcher.extend ¶

extend(name: str) -> Callable[[_MatcherFn], _MatcherFn]

Decorator to register a custom matcher under name.

Usage::

@extend("to_be_in_viewport")
def check_in_viewport(element: Any) -> tuple[bool, Any]:
    ...
    return (passed, actual_value)

The matcher function receives the assertion's _target as its first argument and must return a (bool, Any) tuple where the bool indicates pass/fail and the Any is the actual value for error reporting.

name must be a valid public identifier. If it collides with an existing assertion method (e.g. to_be_visible), the built-in method takes precedence on assertion classes that define it.

Source code in selenium_expect/_matcher.py

def extend(name: str) -> Callable[[_MatcherFn], _MatcherFn]:
    """Decorator to register a custom matcher under *name*.

    Usage::

        @extend("to_be_in_viewport")
        def check_in_viewport(element: Any) -> tuple[bool, Any]:
            ...
            return (passed, actual_value)

    The matcher function receives the assertion's ``_target`` as its
    first argument and must return a ``(bool, Any)`` tuple where the
    bool indicates pass/fail and the Any is the actual value for
    error reporting.

    *name* must be a valid public identifier. If it collides with an
    existing assertion method (e.g. ``to_be_visible``), the built-in
    method takes precedence on assertion classes that define it.
    """
    if not name.isidentifier() or name.startswith("_"):
        raise ValueError(f"Invalid matcher name: {name!r}")

    def decorator(fn: Callable[..., tuple[bool, Any]]) -> Callable[..., tuple[bool, Any]]:
        CustomMatcherRegistry.register(name, fn)
        fn._selenium_expect_matcher = name  # type: ignore[attr-defined]
        return fn

    return decorator

`merge_expects(*modules)`¶

Combine custom matchers from multiple modules into the registry.

Parameters¶

Parameter	Type	Description
`*modules`	`ModuleType \\| str`	Modules or importable module paths

Example¶

from selenium_expect import merge_expects

# Pass module objects
import my_project.matchers
import my_project.custom_assertions
merge_expects(my_project.matchers, my_project.custom_assertions)

# Or pass importable strings
merge_expects("my_project.matchers", "my_project.custom_assertions")

selenium_expect._matcher.merge_expects ¶

merge_expects(*modules: ModuleType | str) -> list[str]

Combine custom matchers from multiple modules into the registry.

Each module should have used @extend to register matchers. Pass modules as objects or importable strings.

Usage::

import my_matchers
merge_expects(my_matchers)

# or by import path:
merge_expects("my_project.matchers")

Returns the list of newly registered matcher names.

Source code in selenium_expect/_matcher.py

def merge_expects(*modules: ModuleType | str) -> list[str]:
    """Combine custom matchers from multiple modules into the registry.

    Each module should have used ``@extend`` to register matchers.
    Pass modules as objects or importable strings.

    Usage::

        import my_matchers
        merge_expects(my_matchers)

        # or by import path:
        merge_expects("my_project.matchers")

    Returns the list of newly registered matcher names.
    """
    import importlib

    resolved: list[ModuleType] = []
    for mod in modules:
        if isinstance(mod, str):
            resolved.append(importlib.import_module(mod))
        else:
            resolved.append(mod)
    return CustomMatcherRegistry.merge_from(*resolved)

`SoftAssertionCollector`¶

Collects soft assertion failures for deferred raising.

Methods¶

Method	Description
`reset()`	Clear all collected failures
`get_failures()`	Return list of failure messages
`assert_all()`	Raise `AssertionError` if any failures, then reset

Example¶

from selenium_expect import expect, SoftAssertionCollector, assert_all

SoftAssertionCollector.reset()

expect(element, soft=True).to_be_visible()
expect(element, soft=True).to_have_text("Hello")

failures = SoftAssertionCollector.get_failures()
if failures:
    print(f"{len(failures)} failures collected")

assert_all()  # raises if any failures

selenium_expect._soft.SoftAssertionCollector ¶

Collects soft assertion failures for deferred raising.

Failures are stored per execution context (ContextVar): each thread and each async task has its own list.

Source code in selenium_expect/_soft.py

class SoftAssertionCollector:
    """Collects soft assertion failures for deferred raising.

    Failures are stored per execution context (``ContextVar``): each
    thread and each async task has its own list.
    """

    _failures: ClassVar[ContextVar[list[str] | None]] = ContextVar(
        "soft_assertion_failures", default=None
    )

    @classmethod
    def _current(cls) -> list[str]:
        """Return this context's failure list, creating it on first use."""
        failures = cls._failures.get()
        if failures is None:
            failures = []
            cls._failures.set(failures)
        return failures

    @classmethod
    def add_failure(cls, message: str) -> None:
        """Record a soft assertion failure."""
        cls._current().append(message)

    @classmethod
    def get_failures(cls) -> list[str]:
        """Return all collected failures in this context."""
        return list(cls._current())

    @classmethod
    def reset(cls) -> None:
        """Clear all collected failures in this context."""
        cls._failures.set([])

    @classmethod
    def assert_all(cls) -> None:
        """Raise ``AssertionError`` if any failures were collected, then reset."""
        failures = cls._current()
        if not failures:
            return
        messages = list(failures)
        cls.reset()
        combined = "\n---\n".join(messages)
        raise AssertionError(f"Soft assertion failures ({len(messages)}):\n{combined}")

add_failure `classmethod` ¶

add_failure(message: str) -> None

Record a soft assertion failure.

Source code in selenium_expect/_soft.py

@classmethod
def add_failure(cls, message: str) -> None:
    """Record a soft assertion failure."""
    cls._current().append(message)

assert_all `classmethod` ¶

assert_all() -> None

Raise AssertionError if any failures were collected, then reset.

Source code in selenium_expect/_soft.py

@classmethod
def assert_all(cls) -> None:
    """Raise ``AssertionError`` if any failures were collected, then reset."""
    failures = cls._current()
    if not failures:
        return
    messages = list(failures)
    cls.reset()
    combined = "\n---\n".join(messages)
    raise AssertionError(f"Soft assertion failures ({len(messages)}):\n{combined}")

get_failures `classmethod` ¶

get_failures() -> list[str]

Return all collected failures in this context.

Source code in selenium_expect/_soft.py

@classmethod
def get_failures(cls) -> list[str]:
    """Return all collected failures in this context."""
    return list(cls._current())

reset `classmethod` ¶

reset() -> None

Clear all collected failures in this context.

Source code in selenium_expect/_soft.py

@classmethod
def reset(cls) -> None:
    """Clear all collected failures in this context."""
    cls._failures.set([])

`assert_all()`¶

Raise AssertionError if any soft failures were collected, then reset.

Example¶

from selenium_expect import expect, assert_all

expect(element, soft=True).to_be_visible()
expect(element, soft=True).to_have_text("Hello")

assert_all()  # raises AssertionError with combined message if any failed

selenium_expect._soft.assert_all ¶

assert_all() -> None

Raise AssertionError if any soft failures were collected, then reset.

Convenience wrapper around SoftAssertionCollector.assert_all().

Source code in selenium_expect/_soft.py

def assert_all() -> None:
    """Raise ``AssertionError`` if any soft failures were collected, then reset.

    Convenience wrapper around ``SoftAssertionCollector.assert_all()``.
    """
    SoftAssertionCollector.assert_all()

Configuration setters¶

`set_default_timeout(seconds)`¶

Set the global default timeout for all assertions.

from selenium_expect import set_default_timeout

set_default_timeout(10)     # 10 seconds
set_default_timeout(5000)   # interpreted as 5000ms = 5 seconds (int >= 1000)

selenium_expect._config.set_default_timeout ¶

set_default_timeout(seconds: float) -> None

Set the default timeout for all expect assertions.

Any value >= 1000 is interpreted as milliseconds (consistent with expect(timeout=...)).

Source code in selenium_expect/_config.py

def set_default_timeout(seconds: float) -> None:
    """Set the default timeout for all expect assertions.

    Any value >= 1000 is interpreted as milliseconds
    (consistent with ``expect(timeout=...)``).
    """
    global _global_config
    _global_config = _global_config.replace(timeout=normalize_timeout(seconds))

`set_default_polling_interval(seconds)`¶

Set the global default polling interval (fixed).

from selenium_expect import set_default_polling_interval

set_default_polling_interval(0.25)

selenium_expect._config.set_default_polling_interval ¶

set_default_polling_interval(seconds: float) -> None

Set the default polling interval for all expect assertions.

Source code in selenium_expect/_config.py

def set_default_polling_interval(seconds: float) -> None:
    """Set the default polling interval for all expect assertions."""
    global _global_config
    _global_config = _global_config.replace(polling_interval=seconds)

`set_default_polling_intervals(intervals)`¶

Set a backoff schedule for polling. The list is cycled through during the retry loop.

from selenium_expect import set_default_polling_intervals

set_default_polling_intervals([0.1, 0.2, 0.5, 1.0])

selenium_expect._config.set_default_polling_intervals ¶

set_default_polling_intervals(intervals: Sequence[float]) -> None

Set a backoff schedule for polling intervals.

Source code in selenium_expect/_config.py

def set_default_polling_intervals(intervals: Sequence[float]) -> None:
    """Set a backoff schedule for polling intervals."""
    global _global_config
    _global_config = _global_config.replace(polling_intervals=intervals)

`set_screenshot_on_failure(enabled, path=None)`¶

Enable automatic screenshot capture on assertion failure.

from selenium_expect import set_screenshot_on_failure

set_screenshot_on_failure(True, path="./screenshots/")

selenium_expect._config.set_screenshot_on_failure ¶

set_screenshot_on_failure(enabled: bool, path: str | None = None) -> None

Enable or disable screenshot capture on assertion failure.

Source code in selenium_expect/_config.py

def set_screenshot_on_failure(enabled: bool, path: str | None = None) -> None:
    """Enable or disable screenshot capture on assertion failure."""
    global _global_config
    _global_config = _global_config.replace(
        screenshot_on_failure=enabled,
        screenshot_path=path if path is not None else "./screenshots/",
    )

`set_debug_mode(enabled)`¶

Enable debug logging for retry loops. Prints poll count, elapsed time, and actual values.

from selenium_expect import set_debug_mode

set_debug_mode(True)

selenium_expect._config.set_debug_mode ¶

set_debug_mode(enabled: bool) -> None

Enable or disable debug logging for retry loops.

Source code in selenium_expect/_config.py

def set_debug_mode(enabled: bool) -> None:
    """Enable or disable debug logging for retry loops."""
    global _global_config
    _global_config = _global_config.replace(debug_mode=enabled)

`get_config()`¶

Return the current global ExpectConfig instance.

from selenium_expect import get_config

config = get_config()
print(f"Timeout: {config.timeout}s, Polling: {config.polling_interval}s")

selenium_expect._config.get_config ¶

get_config() -> ExpectConfig

Return the current global config.

Source code in selenium_expect/_config.py

def get_config() -> ExpectConfig:
    """Return the current global config."""
    return _global_config

Assertion classes¶

`ExpectElement`¶

Assertions for WebElement objects. Provides methods for visibility, state, text, attributes, CSS, identity, position, accessibility, shadow DOM, and JavaScript properties.

Key method categories:

State: to_be_visible, to_be_hidden, to_be_present, to_be_absent, to_be_enabled, to_be_disabled, to_be_selected, to_be_unselected, to_be_checked, to_be_unchecked, to_be_clickable, to_be_editable, to_be_readonly, to_be_focused, to_be_empty, to_be_stale
Text: to_have_text, to_have_text_contains, to_have_text_matches, to_have_text_empty, to_have_text_not_empty, to_have_text_starting_with, to_have_text_ending_with, to_have_text_in_list
Attributes: to_have_attribute, to_have_attribute_present, to_have_attribute_absent, to_have_attribute_contains, to_have_attribute_empty, to_have_attribute_in_list, to_have_attribute_matches, to_have_dom_attribute, to_have_dom_attribute_contains, to_have_class, to_have_class_contains, to_contain_class, to_have_class_in_list, to_have_class_matching, to_have_all_classes, to_have_id, to_have_value, to_have_value_contains, to_have_value_in_list, to_have_value_matches
CSS: to_have_css_property, to_have_css_property_contains, to_have_css_property_matches
Identity: to_have_tag, to_have_aria_role, to_have_aria_role_contains, to_have_aria_role_in_list, to_have_accessible_name, to_have_accessible_name_contains
Position: to_have_location, to_have_location_x, to_have_location_y, to_have_location_greater_than, to_have_location_less_than, to_have_location_once_scrolled_into_view, to_have_size, to_have_size_width, to_have_size_height, to_have_size_greater_than, to_have_size_less_than, to_have_rect
Properties/JS: to_have_property, to_have_property_contains, to_have_js_property
Shadow DOM: to_have_shadow_root, to_have_shadow_root_absent
Composition: to_satisfy_all, to_satisfy_any, to_satisfy_none