selenium-expect 1.0.0__py3-none-any.whl

selenium_expect/__init__.py

@@ -0,0 +1,35 @@
+"""selenium-expect — Playwright-style expect() for Selenium Python."""
+
+from __future__ import annotations
+
+from selenium_expect._config import (
+    ExpectConfig,
+    get_config,
+    set_debug_mode,
+    set_default_polling_interval,
+    set_default_polling_intervals,
+    set_default_timeout,
+    set_screenshot_on_failure,
+)
+from selenium_expect._expect import expect
+from selenium_expect._matcher import extend, merge_expects
+from selenium_expect._poll import poll
+from selenium_expect._soft import SoftAssertionCollector, assert_all
+
+__version__ = "1.0.0"
+
+__all__: list[str] = [
+    "ExpectConfig",
+    "SoftAssertionCollector",
+    "assert_all",
+    "expect",
+    "extend",
+    "get_config",
+    "merge_expects",
+    "poll",
+    "set_debug_mode",
+    "set_default_polling_interval",
+    "set_default_polling_intervals",
+    "set_default_timeout",
+    "set_screenshot_on_failure",
+]

selenium_expect/_compose.py

@@ -0,0 +1,117 @@
+"""Composition assertions — satisfy_all, satisfy_any, satisfy_none.
+
+Each condition is a callable that receives the target and executes an
+assertion (e.g. a lambda calling ``expect(el).to_be_visible()``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from selenium_expect._errors import AssertionFormatter
+
+
+def satisfy_all(
+    target: Any,
+    *conditions: Callable[[Any], None],
+    message: str | None = None,
+) -> None:
+    """Assert all conditions pass (AND logic).
+
+    Each condition is a callable that receives *target* and may raise
+    ``AssertionError`` on failure. All must pass without raising.
+
+    Each condition is responsible for its own retry/timeout via ``expect()``.
+    """
+    if not conditions:
+        raise ValueError("satisfy_all requires at least one condition")
+    failures: list[str] = []
+    for i, cond in enumerate(conditions):
+        try:
+            cond(target)
+        except AssertionError as exc:
+            failures.append(f"condition {i}: {exc}")
+    if failures:
+        combined = "\n".join(failures)
+        error_msg = AssertionFormatter.format_error(
+            entity="composition",
+            condition="to_satisfy_all",
+            expected="all pass",
+            actual=combined,
+            elapsed_ms=0,
+            poll_count=len(conditions),
+            polling_interval=0.0,
+            message=message,
+        )
+        raise AssertionError(error_msg)
+
+
+def satisfy_any(
+    target: Any,
+    *conditions: Callable[[Any], None],
+    message: str | None = None,
+) -> None:
+    """Assert at least one condition passes (OR logic).
+
+    Each condition is a callable that receives *target* and may raise
+    ``AssertionError`` on failure. At least one must pass without raising.
+
+    Each condition is responsible for its own retry/timeout via ``expect()``.
+    """
+    if not conditions:
+        raise ValueError("satisfy_any requires at least one condition")
+    failures: list[str] = []
+    for i, cond in enumerate(conditions):
+        try:
+            cond(target)
+            return  # at least one passed
+        except AssertionError as exc:
+            failures.append(f"condition {i}: {exc}")
+    combined = "\n".join(failures)
+    error_msg = AssertionFormatter.format_error(
+        entity="composition",
+        condition="to_satisfy_any",
+        expected="at least one pass",
+        actual=combined,
+        elapsed_ms=0,
+        poll_count=len(conditions),
+        polling_interval=0.0,
+        message=message,
+    )
+    raise AssertionError(error_msg)
+
+
+def satisfy_none(
+    target: Any,
+    *conditions: Callable[[Any], None],
+    message: str | None = None,
+) -> None:
+    """Assert no condition passes (NOT logic).
+
+    Each condition is a callable that receives *target* and may raise
+    ``AssertionError``. All must raise (i.e. none pass).
+
+    Each condition is responsible for its own retry/timeout via ``expect()``.
+    """
+    if not conditions:
+        raise ValueError("satisfy_none requires at least one condition")
+    passed: list[int] = []
+    for i, cond in enumerate(conditions):
+        try:
+            cond(target)
+            passed.append(i)
+        except AssertionError:
+            pass  # expected to fail
+    if passed:
+        error_msg = AssertionFormatter.format_error(
+            entity="composition",
+            condition="to_satisfy_none",
+            expected="none pass",
+            actual=f"conditions {passed} passed",
+            elapsed_ms=0,
+            poll_count=len(conditions),
+            polling_interval=0.0,
+            message=message,
+        )
+        raise AssertionError(error_msg)

selenium_expect/_config.py

@@ -0,0 +1,96 @@
+"""Configuration for selenium-expect assertions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import replace as _replace
+from typing import Any
+
+
+def normalize_timeout(timeout: float) -> float:
+    """Convert timeout to seconds.
+
+    If *timeout* is an int >= 1000, it is interpreted as milliseconds.
+    Floats and ints < 1000 are treated as seconds.
+    """
+    if isinstance(timeout, int) and timeout >= 1000:
+        return timeout / 1000.0
+    return float(timeout)
+
+
+@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: list[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:
+            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)
+
+
+_global_config: ExpectConfig = ExpectConfig()
+
+
+def set_default_timeout(seconds: float) -> None:
+    """Set the default timeout for all expect assertions.
+
+    If *seconds* is an int >= 1000, it is interpreted as milliseconds
+    (consistent with ``expect(timeout=...)``).
+    """
+    global _global_config
+    _global_config = _global_config.replace(timeout=normalize_timeout(seconds))
+
+
+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)
+
+
+def set_default_polling_intervals(intervals: list[float]) -> None:
+    """Set a backoff schedule for polling intervals."""
+    global _global_config
+    _global_config = _global_config.replace(polling_intervals=intervals)
+
+
+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/",
+    )
+
+
+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)
+
+
+def get_config() -> ExpectConfig:
+    """Return the current global config."""
+    return _global_config

selenium_expect/_errors.py

@@ -0,0 +1,57 @@
+"""Assertion error message formatting for selenium-expect."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AssertionFormatter:
+    """Builds descriptive multi-line error messages."""
+
+    @staticmethod
+    def format_error(
+        entity: str,
+        condition: str,
+        expected: Any,
+        actual: Any,
+        elapsed_ms: int,
+        poll_count: int,
+        polling_interval: float,
+        message: str | None = None,
+        element_html: str | None = None,
+        timeline: list[dict[str, Any]] | None = None,
+    ) -> str:
+        """Format a descriptive AssertionError message.
+
+        Output format:
+            Expected {entity} {condition}, but got {actual}
+              Expected: {expected}
+              Actual:   {actual}
+              Element:  {truncated_html}     # if element_html provided
+              Waited:   {elapsed_ms}ms ({poll_count} polls at {polling_interval}s interval)
+              Message:  {custom_message}     # if message provided
+              Timeline: [poll N: actual, ...] # last 5 polls if timeline provided
+        """
+        lines: list[str] = [
+            f"Expected {entity} {condition}, but got {actual}",
+            f"  Expected: {expected}",
+            f"  Actual:   {actual}",
+        ]
+
+        if element_html is not None:
+            truncated = element_html if len(element_html) <= 200 else element_html[:200] + "..."
+            lines.append(f"  Element:  {truncated}")
+
+        lines.append(
+            f"  Waited:   {elapsed_ms}ms ({poll_count} polls at {polling_interval}s interval)"
+        )
+
+        if message is not None:
+            lines.append(f"  Message:  {message}")
+
+        if timeline:
+            recent = timeline[-5:]
+            entries = ", ".join(f"poll {e['poll']}: {e['actual']}" for e in recent)
+            lines.append(f"  Timeline: [{entries}]")
+
+        return "\n".join(lines)

selenium_expect/_expect.py

@@ -0,0 +1,181 @@
+"""expect() entry point — dispatches to the correct assertion class."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, cast
+
+from selenium.webdriver.common.alert import Alert
+from selenium.webdriver.remote.shadowroot import ShadowRoot
+from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support.ui import Select
+
+from selenium_expect._config import ExpectConfig, get_config, normalize_timeout
+from selenium_expect._poll import PollAssertion
+from selenium_expect.assertions import ASSERTION_REGISTRY
+from selenium_expect.assertions._base import AssertionMixin
+
+
+def _resolve_target_type(target: Any) -> str:
+    """Determine the registry type name for *target*.
+
+    Select is checked before WebElement because Select wraps a WebElement.
+    """
+    if isinstance(target, Select):
+        return "Select"
+    if isinstance(target, WebElement):
+        return "WebElement"
+    if isinstance(target, list):
+        return "list"
+    if isinstance(target, WebDriver):
+        return "WebDriver"
+    if isinstance(target, Alert):
+        return "Alert"
+    if isinstance(target, ShadowRoot):
+        return "ShadowRoot"
+    cls_name = type(target).__name__
+    if cls_name == "WebDriver":
+        return "WebDriver"
+    if cls_name == "Alert":
+        return "Alert"
+    return cls_name
+
+
+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 = config if config is not None else get_config()
+            if timeout is not None or polling is not None or soft is not None:
+                overrides: dict[str, Any] = {}
+                if timeout is not None:
+                    overrides["timeout"] = normalize_timeout(timeout)
+                if polling is not None:
+                    if isinstance(polling, list):
+                        overrides["polling_intervals"] = polling
+                    else:
+                        overrides["polling_interval"] = polling
+                if soft is not None:
+                    overrides["soft_mode"] = soft
+                effective_config = effective_config.replace(**overrides)
+
+            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 = config if config is not None else get_config()
+
+        if timeout is not None or polling is not None or soft is not None:
+            cfg_overrides: dict[str, Any] = {}
+            if timeout is not None:
+                cfg_overrides["timeout"] = normalize_timeout(timeout)
+            if polling is not None:
+                if isinstance(polling, list):
+                    cfg_overrides["polling_intervals"] = polling
+                else:
+                    cfg_overrides["polling_interval"] = polling
+            if soft is not None:
+                cfg_overrides["soft_mode"] = soft
+            effective_config = effective_config.replace(**cfg_overrides)
+
+        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)
+
+        return _configured_expect
+
+
+expect = Expect()

selenium_expect/_locator.py

@@ -0,0 +1,157 @@
+"""LocatorExpect — re-finds element on each poll cycle.
+
+When ``expect(driver, by=By.ID, value="foo")`` is used, a ``LocatorExpect``
+is returned instead of ``ExpectElement``. On every poll cycle it calls
+``driver.find_element(by, value)`` to get a fresh element, then delegates
+the condition check to the corresponding ``ExpectElement`` method.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from selenium.common.exceptions import NoSuchElementException, StaleElementReferenceException
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from selenium_expect._config import ExpectConfig
+from selenium_expect.assertions._base import AssertionMixin
+
+
+class LocatorExpect(AssertionMixin):
+    """Locator-based expect that re-finds the element on each poll.
+
+    Delegates all ``ExpectElement`` assertion methods via ``__getattr__``.
+    Each assertion method is executed with a fresh element obtained from
+    ``driver.find_element(by, value)`` on every poll cycle.
+    """
+
+    def __init__(
+        self,
+        driver: WebDriver,
+        by: str,
+        value: str,
+        config: ExpectConfig | None = None,
+        message: str | None = None,
+        negate: bool = False,
+    ) -> None:
+        super().__init__(target=driver, config=config, message=message, negate=negate)
+        self._driver = driver
+        self._by = by
+        self._value = value
+
+    def _find_element(self) -> Any:
+        """Find the element fresh. Returns None if not found."""
+        try:
+            return self._driver.find_element(self._by, self._value)
+        except NoSuchElementException:
+            return None
+
+    @property
+    def not_(self) -> LocatorExpect:
+        """Return a negated copy."""
+        return LocatorExpect(
+            driver=self._driver,
+            by=self._by,
+            value=self._value,
+            config=self._config,
+            message=self._message,
+            negate=not self._negate,
+        )
+
+    def _entity_description(self) -> str:
+        return f"locator({self._by}={self._value!r})"
+
+    def _get_element_html(self) -> str | None:
+        el = self._find_element()
+        if el is None:
+            return None
+        try:
+            html: str | None = el.get_attribute("outerHTML")
+            return html
+        except StaleElementReferenceException:
+            return None
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate to ExpectElement methods or custom matchers with re-find on each poll.
+
+        For each assertion method call, we wrap the condition so that
+        ``find_element`` is called fresh on every retry poll.
+        """
+        # Avoid recursion for private/dunder attributes
+        if name.startswith("_"):
+            raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+        from selenium_expect._matcher import CustomMatcherRegistry
+        from selenium_expect.assertions.element import ExpectElement
+
+        # Check for custom matcher first
+        matcher_fn = CustomMatcherRegistry.get(name)
+
+        # Get the actual method from ExpectElement
+        element_method = getattr(ExpectElement, name, None)
+
+        if matcher_fn is None and (element_method is None or not callable(element_method)):
+            raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+        if matcher_fn is not None:
+
+            def _invoke_matcher(*args: Any, **kwargs: Any) -> None:
+                timeout = kwargs.pop("timeout", None)
+                polling = kwargs.pop("polling", None)
+
+                def condition() -> tuple[bool, Any]:
+                    try:
+                        el = self._driver.find_element(self._by, self._value)
+                    except NoSuchElementException:
+                        return (False, "element not found")
+                    try:
+                        return matcher_fn(el, *args, **kwargs)
+                    except StaleElementReferenceException:
+                        return (False, "stale element")
+
+                self._run_assertion(
+                    condition=condition,
+                    condition_name=name.replace("_", " "),
+                    expected=None,
+                    entity=self._entity_description(),
+                    timeout=timeout,
+                    polling=polling,
+                )
+
+            return _invoke_matcher
+
+        def _invoke(*args: Any, **kwargs: Any) -> None:
+            timeout = kwargs.pop("timeout", None)
+            polling = kwargs.pop("polling", None)
+
+            def condition() -> tuple[bool, Any]:
+                try:
+                    el = self._driver.find_element(self._by, self._value)
+                except NoSuchElementException:
+                    return (False, "element not found")
+                inner_config = self._config.replace(soft_mode=False, screenshot_on_failure=False)
+                temp = ExpectElement(
+                    target=el,
+                    config=inner_config,
+                    message=self._message,
+                    negate=False,
+                )
+                method = getattr(temp, name)
+                try:
+                    method(*args, timeout=0.001, **kwargs)
+                    return (True, "passed")
+                except AssertionError:
+                    return (False, "failed")
+                except StaleElementReferenceException:
+                    return (False, "stale element")
+
+            self._run_assertion(
+                condition=condition,
+                condition_name=name.replace("_", " "),
+                expected=None,
+                entity=self._entity_description(),
+                timeout=timeout,
+                polling=polling,
+            )
+
+        return _invoke