selenium-expect 1.0.0__py3-none-any.whl

selenium_expect/_matcher.py

@@ -0,0 +1,111 @@
+"""Custom matcher registry for selenium-expect.
+
+Allows users to register custom assertion methods that integrate with
+the retry loop and negation via ``__getattr__`` on ``AssertionMixin``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any, ClassVar
+
+
+class CustomMatcherRegistry:
+    """Registry of user-defined custom matchers."""
+
+    _matchers: ClassVar[dict[str, Callable[..., tuple[bool, Any]]]] = {}
+
+    @classmethod
+    def register(cls, name: str, matcher_fn: Callable[..., tuple[bool, Any]]) -> None:
+        """Register a custom matcher function under *name*."""
+        cls._matchers[name] = matcher_fn
+
+    @classmethod
+    def get(cls, name: str) -> Callable[..., tuple[bool, Any]] | None:
+        """Return the matcher registered under *name*, or ``None``."""
+        return cls._matchers.get(name)
+
+    @classmethod
+    def names(cls) -> list[str]:
+        """Return all registered matcher names."""
+        return list(cls._matchers)
+
+    @classmethod
+    def reset(cls) -> None:
+        """Clear all registered matchers (for testing)."""
+        cls._matchers.clear()
+
+    @classmethod
+    def merge_from(cls, *modules: ModuleType) -> list[str]:
+        """Merge matchers from the given modules into this registry.
+
+        Each module is expected to have used ``@extend`` to register
+        matchers at import time. This method imports (if passed as a
+        string) or processes each module and returns the names of
+        newly registered matchers.
+        """
+        added: list[str] = []
+        for mod in modules:
+            for name in dir(mod):
+                fn = getattr(mod, name, None)
+                if callable(fn) and hasattr(fn, "_selenium_expect_matcher"):
+                    matcher_name: str = fn._selenium_expect_matcher
+                    if matcher_name not in cls._matchers:
+                        cls._matchers[matcher_name] = fn
+                        added.append(matcher_name)
+        return added
+
+
+_MatcherFn = Callable[..., tuple[bool, Any]]
+
+
+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.
+    """
+
+    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
+
+
+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)

selenium_expect/_poll.py

@@ -0,0 +1,221 @@
+"""PollAssertion — retry-based assertions over arbitrary functions.
+
+``poll(fn)`` wraps any zero-arg callable and provides Playwright-style
+assertion methods that retry until the function's return value satisfies
+the condition or the timeout expires.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any
+
+from selenium_expect._config import (
+    ExpectConfig,
+    get_config,
+)
+from selenium_expect._config import (
+    normalize_timeout as _normalize_timeout,
+)
+from selenium_expect._errors import AssertionFormatter
+from selenium_expect._retry import retry_until
+
+
+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 = 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) -> None:
+        """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)
+
+    def to_be_truthy(self) -> None:
+        """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)
+
+    def to_be_falsy(self) -> None:
+        """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)
+
+    def to_be_none(self) -> None:
+        """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)
+
+    def to_contain(self, expected: Any) -> None:
+        """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)
+
+    def to_match(self, pattern: str) -> None:
+        """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)
+
+    def to_be_greater_than(self, expected: Any) -> None:
+        """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)
+
+    def to_be_less_than(self, expected: Any) -> None:
+        """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)
+
+    def to_be_in_list(self, expected: list[Any]) -> None:
+        """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)
+
+    def to_have_length(self, expected: int) -> None:
+        """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)
+
+
+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)

selenium_expect/_retry.py

@@ -0,0 +1,145 @@
+"""Retry engine for selenium-expect assertions.
+
+The retry loop is agnostic — it knows nothing about Selenium. It calls
+a condition callable repeatedly until it returns ``(True, value)`` or
+the timeout expires. Retryable Selenium exceptions are caught and
+treated as a failed poll.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from selenium.common.exceptions import (
+    ElementNotInteractableException,
+    NoAlertPresentException,
+    NoSuchElementException,
+    NoSuchFrameException,
+    NoSuchShadowRootException,
+    NoSuchWindowException,
+    StaleElementReferenceException,
+)
+
+logger = logging.getLogger("selenium_expect")
+
+RETRYABLE_EXCEPTIONS: tuple[type[Exception], ...] = (
+    StaleElementReferenceException,
+    NoSuchElementException,
+    NoAlertPresentException,
+    NoSuchWindowException,
+    NoSuchFrameException,
+    ElementNotInteractableException,
+    NoSuchShadowRootException,
+)
+
+
+@dataclass(slots=True)
+class RetryResult:
+    """Result of a retry loop execution."""
+
+    passed: bool
+    actual_value: Any
+    elapsed_ms: int
+    poll_count: int
+    timeline: list[dict[str, Any]] = field(default_factory=list)
+
+
+def retry_until(
+    condition: Callable[[], tuple[bool, Any]],
+    timeout: float,
+    polling_interval: float = 0.5,
+    polling_intervals: list[float] | None = None,
+    debug: bool = False,
+) -> RetryResult:
+    """Execute ``condition()`` repeatedly until it returns ``(True, value)`` or timeout.
+
+    Args:
+        condition: Callable returning ``(passed: bool, actual_value: Any)``.
+        timeout: Maximum seconds to wait.
+        polling_interval: Fixed seconds between polls.
+        polling_intervals: Backoff schedule (overrides ``polling_interval``).
+            When exhausted, the last interval is repeated.
+        debug: If ``True``, log each poll via the ``logging`` module.
+
+    Returns:
+        ``RetryResult`` with pass/fail, actual value, elapsed time, and poll timeline.
+    """
+    start = time.monotonic()
+    poll_count = 0
+    timeline: list[dict[str, Any]] = []
+    actual_value: Any = None
+
+    def _get_interval(idx: int) -> float:
+        if polling_intervals is None or len(polling_intervals) == 0:
+            return polling_interval
+        if idx < len(polling_intervals):
+            return polling_intervals[idx]
+        return polling_intervals[-1]
+
+    while True:
+        poll_count += 1
+        try:
+            passed, actual_value = condition()
+        except RETRYABLE_EXCEPTIONS as exc:
+            passed = False
+            actual_value = f"{type(exc).__name__}: {exc}"
+            if debug:
+                logger.debug(
+                    "poll %d: retryable exception %s — %.1fms elapsed",
+                    poll_count,
+                    type(exc).__name__,
+                    (time.monotonic() - start) * 1000,
+                )
+            timeline.append({"poll": poll_count, "passed": False, "actual": str(actual_value)})
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                break
+            _sleep_and_check_timeout(start, timeout, _get_interval(poll_count - 1))
+            continue
+
+        if debug:
+            logger.debug(
+                "poll %d: passed=%s actual=%r — %.1fms elapsed",
+                poll_count,
+                passed,
+                actual_value,
+                (time.monotonic() - start) * 1000,
+            )
+
+        timeline.append({"poll": poll_count, "passed": passed, "actual": actual_value})
+
+        if passed:
+            return RetryResult(
+                passed=True,
+                actual_value=actual_value,
+                elapsed_ms=int((time.monotonic() - start) * 1000),
+                poll_count=poll_count,
+                timeline=timeline,
+            )
+
+        elapsed = time.monotonic() - start
+        if elapsed >= timeout:
+            break
+
+        _sleep_and_check_timeout(start, timeout, _get_interval(poll_count - 1))
+
+    return RetryResult(
+        passed=False,
+        actual_value=actual_value,
+        elapsed_ms=int((time.monotonic() - start) * 1000),
+        poll_count=poll_count,
+        timeline=timeline,
+    )
+
+
+def _sleep_and_check_timeout(start: float, timeout: float, interval: float) -> None:
+    """Sleep for *interval* seconds, but not past the timeout deadline."""
+    elapsed = time.monotonic() - start
+    remaining = timeout - elapsed
+    if remaining <= 0:
+        return
+    time.sleep(min(interval, remaining))

selenium_expect/_soft.py

@@ -0,0 +1,49 @@
+"""Soft assertion collector for selenium-expect.
+
+Accumulates assertion failures when ``soft_mode=True`` instead of raising
+immediately. ``assert_all()`` raises a combined ``AssertionError`` if any
+failures were collected.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+
+class SoftAssertionCollector:
+    """Collects soft assertion failures for deferred raising."""
+
+    _failures: ClassVar[list[str]] = []
+
+    @classmethod
+    def add_failure(cls, message: str) -> None:
+        """Record a soft assertion failure."""
+        cls._failures.append(message)
+
+    @classmethod
+    def get_failures(cls) -> list[str]:
+        """Return all collected failures."""
+        return list(cls._failures)
+
+    @classmethod
+    def reset(cls) -> None:
+        """Clear all collected failures."""
+        cls._failures.clear()
+
+    @classmethod
+    def assert_all(cls) -> None:
+        """Raise ``AssertionError`` if any failures were collected, then reset."""
+        if not cls._failures:
+            return
+        messages = list(cls._failures)
+        cls.reset()
+        combined = "\n---\n".join(messages)
+        raise AssertionError(f"Soft assertion failures ({len(messages)}):\n{combined}")
+
+
+def assert_all() -> None:
+    """Raise ``AssertionError`` if any soft failures were collected, then reset.
+
+    Convenience wrapper around ``SoftAssertionCollector.assert_all()``.
+    """
+    SoftAssertionCollector.assert_all()

selenium_expect/assertions/__init__.py

@@ -0,0 +1,30 @@
+"""Assertion class registry for selenium-expect."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+ASSERTION_REGISTRY: dict[str, type[Any]] = {}
+
+
+def register(type_name: str, cls: type[Any]) -> None:
+    """Register an assertion class for a target type name."""
+    ASSERTION_REGISTRY[type_name] = cls
+
+
+# Import all assertion modules to trigger their register() calls.
+# Done via importlib to avoid issues with `list` being a Python builtin.
+for _module_name in (
+    "alert",
+    "cookie",
+    "driver",
+    "element",
+    "iframe",
+    "js",
+    "list",
+    "select",
+    "shadow",
+    "window",
+):
+    importlib.import_module(f"selenium_expect.assertions.{_module_name}")