prettyplay 0.0.2__py3-none-any.whl

prettyplay/driver/.usages/plumbing.md

@@ -0,0 +1,52 @@
+# Driver plumbing — the internal page handle
+
+Domain: the worker-thread boundary and the internal page handle of prettyplay. Audience: implementers of the engine,
+steering and root cells — the code that executes step code, collects page state and offers the author escape hatch.
+Not an API for generated step code: generated code receives the genuine Playwright sync Page inside the worker thread.
+
+## The worker boundary
+
+The whole Playwright session lives in one dedicated driver thread. The only crossing point is the run primitive of the
+page handle: a callable executes wholly inside the worker thread and receives the genuine sync Page there.
+
+    result = page.run(action)  # action(page) runs inside the worker thread
+
+Immediate reads such as `page.url` cross the boundary the same way — one unit through the
+run primitive, plain string back; the calling thread never adopts the Playwright event loop.
+
+- The calling thread never adopts the Playwright event loop — the IPython/Jupyter guarantee holds
+- The result returns as-is; an exception propagates as-is: an AssertionError of a step reaches failure classification
+  untouched
+- A re-entrant crossing is rejected loudly: a callable calling back into the worker (a step, a screenshot, a nested
+  run from inside a run_on_page action) raises an Error instead of deadlocking both threads
+- Playwright objects never cross back: the callable returns plain data
+
+## The handle members
+
+| Call | Purpose |
+|---|---|
+| page.run(action) | execute the callable inside the worker thread with the genuine sync Page |
+| page.url | the current page URL — an immediate read through the worker-thread run primitive |
+| page.aria_snapshot() | the accessibility-tree page state — the primary LLM input |
+| page.screenshot() | full-page PNG bytes |
+| page.close() | close this page's isolated context |
+
+## Step execution through the boundary
+
+Step code of the fixed form `def step(page)` receives the genuine sync Page. Compile and resolve stay on the calling
+thread; the whole step call runs inside the worker as one run. Every standard Playwright call — locators, actions,
+`expect` chains, plain asserts on immediate reads, `locator.count()` — is the real thing on the real object.
+
+## Dialogs — resolver of last resort
+
+The runtime registers one dialog routing handler per page before any step code runs. A dialog handled by an in-step
+stock capture (`with page.expect_event("dialog") as info:` ... `info.value.accept()`) is never touched by the router.
+Every unclaimed dialog is resolved exactly once: accept when accept_dialogs is on, an explicit dismiss otherwise.
+The step wins, the router is last — deterministic inside the worker thread. The drain of one unit is bounded: a page
+that fires a fresh dialog for every resolution leaves the excess pending for the next unit tail — no unit runs forever.
+
+## Rules
+
+- One browser process per test; contexts stay isolated
+- Driving is strictly sequential: one run at a time
+- No fixed delays anywhere in runtime plumbing — waits live in locators and expectations of step code

prettyplay/driver/__init__.py

@@ -0,0 +1,11 @@
+"""Facade of the prettyplay.driver cell: the Playwright sync driver of prettyplay."""
+
+from .errors import is_pollable_failure
+from .page import PageFacade
+from .session import DriverSession
+
+__all__ = [
+    "DriverSession",
+    "PageFacade",
+    "is_pollable_failure",
+]

prettyplay/driver/errors.py

@@ -0,0 +1,76 @@
+"""The fixed pollable map of the prettyplay.driver error surface."""
+
+from __future__ import annotations
+
+import re
+
+from playwright.sync_api import Error as PlaywrightError
+
+#: The timeout signature of the installed Playwright driver — "Timeout NNNms
+#: exceeded" over locator, action, expectation and navigation waits alike.
+_TIMEOUT_PATTERN = re.compile(r"timeout \d+m?s exceeded")
+
+#: Fixed message-pattern set of the pollable driver kinds — element state,
+#: detach/stale handles, navigation and context races. Every pattern matches
+#: a real message of the installed Playwright driver; the detach family is
+#: exactly this set.
+_POLLABLE_PATTERNS = (
+    "element is not visible",
+    "element is not enabled",
+    "element is outside of the viewport",
+    "element is not attached",
+    "frame has been detached",
+    "detached from document",
+    "execution context was destroyed",
+    "target closed",
+    "interrupted by another navigation",
+    "navigation interrupted the evaluation",
+)
+
+
+def _matches_pollable(text: str) -> bool:
+    """Match a Playwright error text against the fixed pollable pattern set.
+
+    Args:
+        text: the message text of the exception, any casing.
+
+    Returns:
+        True when the lowercased text carries a timeout signature or one of
+        the fixed pollable message patterns.
+    """
+    lower = text.lower()
+
+    if _TIMEOUT_PATTERN.search(lower):
+        return True
+
+    return any(pattern in lower for pattern in _POLLABLE_PATTERNS)
+
+
+def is_pollable_failure(exc: Exception) -> bool:
+    """Decide whether a failed step-code exception is transient page state.
+
+    Args:
+        exc: the exception raised by the failed step code.
+
+    Returns:
+        True when the kind is transient — the settle window may re-execute
+        the same code; False — deterministic or unknown, it goes straight
+        to classification. True covers a failed check and the
+        timeout/element-state/navigation driver families; False covers
+        locator ambiguity and Python-level errors.
+    """
+    text = str(exc)
+
+    # Locator ambiguity first — the elements are there, waiting will not
+    # collapse them to one; an ambiguity-styled AssertionError is refused too.
+    if "strict mode violation" in text:
+        return False
+
+    # A failed expectation: the check executed and did not hold; the state
+    # may catch up.
+    if isinstance(exc, AssertionError):
+        return True
+
+    # Driver kinds by type and message pattern — never pattern alone; anything
+    # else — Python-level or unknown — is the conservative default.
+    return isinstance(exc, PlaywrightError) and _matches_pollable(text)

prettyplay/driver/page.py

@@ -0,0 +1,175 @@
+"""The internal runtime plumbing handle of a single test page."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+from playwright.sync_api import BrowserContext, Dialog, Page
+
+if TYPE_CHECKING:
+    from .session import PlaywrightWorker
+
+_T = TypeVar("_T")
+
+logger = logging.getLogger("prettyplay")
+
+# The drain bound of one resolver pass: a page that fires a fresh dialog for
+# every resolution would keep the pass — and with it the whole driver-thread
+# unit — alive forever; the excess rolls forward to the next unit tail instead.
+_RESOLVE_PASS_LIMIT = 128
+
+
+class PageFacade:
+    """The internal runtime plumbing handle of a single test page — plumbing only, no proxies of page capabilities.
+
+    Attributes:
+        _page: the wrapped Playwright page; never exposed to the calling thread.
+        _context: the isolated context owning the page; the handle boundary.
+        _worker: the driver thread of the owning session; ``None`` for
+            hand-built handles, which then call Playwright inline.
+        _router: the dialog routing state shared by every page of the context;
+            ``None`` for a handle without a session — no handler is registered,
+            hence nothing is ever pending.
+    """
+
+    def __init__(self, page: Page, context: BrowserContext) -> None:
+        """Wrap one Playwright page of an isolated context.
+
+        Args:
+            page: the Playwright page object; never exposed to the calling thread.
+            context: the isolated context of the page; the handle boundary.
+        """
+        self._page = page
+        self._context = context
+        self._worker: PlaywrightWorker | None = None
+        self._router: _DialogRouter | None = None
+
+    @property
+    def url(self) -> str:
+        """The current URL of the page — an immediate read.
+
+        Returns:
+            The current URL of the page, read as one driver-thread unit; a
+            plain string crosses back, no Playwright object.
+        """
+        return self._call(lambda: self._page.url)
+
+    def run(self, action: Callable[[Page], _T]) -> _T:
+        """Execute the callable wholly inside the driver worker thread — the only crossing point of the boundary.
+
+        Args:
+            action: the callable to execute; receives the genuine sync Page.
+
+        Returns:
+            Whatever ``action`` returns — plain data only; Playwright
+            objects never cross back. The leftover-dialog pass runs after
+            the action — it never raises and never masks the outcome; an
+            exception inside the action propagates untouched.
+        """
+
+        return self._call(lambda: action(self._page))
+
+    def _resolve_leftovers(self) -> None:
+        """Run the deferred dialog pass of the driver-thread unit; never raises."""
+        if self._router is not None:
+            self._router.resolve_pending()
+
+    def _call(self, fn: Callable[[], _T]) -> _T:
+        """Run one callable in the driver thread with the leftover pass.
+
+        Args:
+            fn: the callable touching the wrapped Playwright objects.
+
+        Returns:
+            Whatever ``fn`` returns — the deferred dialog pass drains every
+            unclaimed dialog after the callable, so no pending dialog
+            survives the boundary.
+        """
+
+        def unit() -> _T:
+            """Run fn and resolve the dialog leftovers afterwards."""
+            try:
+                return fn()
+            finally:
+                self._resolve_leftovers()
+
+        if self._worker is None:  # hand-built handle (tests): inline execution
+            return unit()
+
+        return self._worker.run(unit)  # one queued unit; outcome/error re-raised as-is
+
+    def aria_snapshot(self) -> str:
+        """Capture the accessibility-tree state of the page.
+
+        Returns:
+            The aria snapshot of the page body.
+        """
+        return self._call(lambda: self._page.locator("body").aria_snapshot())
+
+    def screenshot(self) -> bytes:
+        """Capture a full-page screenshot.
+
+        Returns:
+            The PNG image of the whole page as bytes.
+        """
+        return self._call(lambda: self._page.screenshot(full_page=True))
+
+    def close(self) -> None:
+        """Close the isolated context of the page; the test's browser keeps running."""
+        self._call(self._context.close)
+
+
+class _DialogRouter:
+    """The single dialog routing state of one browser context — the resolver of last resort at every unit tail.
+
+    Attributes:
+        accept_dialogs: the ``browser.accept_dialogs`` setting read once at
+            context creation; ``True`` accepts unclaimed dialogs — the
+            router is the resolver of last resort at every unit tail:
+            accept on this setting, else an explicit dismiss.
+        _pending: the dialogs recorded by the routing handlers and not yet
+            resolved; only the single worker thread touches it.
+    """
+
+    def __init__(self, accept_dialogs: bool) -> None:
+        """Keep the setting; nothing is pending yet.
+
+        Args:
+            accept_dialogs: whether dialogs no in-step stock dialog capture
+                claims are accepted automatically at the unit tail.
+        """
+        self.accept_dialogs = accept_dialogs
+        self._pending: list[Dialog] = []
+
+    def record(self, dialog: Dialog) -> None:
+        """Record a dialog fired on any page of the context — pure bookkeeping.
+
+        Args:
+            dialog: the raw Playwright dialog fired on the page; no
+                Playwright call happens inside the event dispatch, so the
+                step's own in-step capture stays free to claim it.
+        """
+        self._pending.append(dialog)
+
+    def resolve_pending(self) -> None:
+        """Resolve recorded dialogs — the bounded tail pass of every driver-thread unit; never raises."""
+        resolved = 0
+        while self._pending and resolved < _RESOLVE_PASS_LIMIT:
+            dialog = self._pending.pop(0)  # FIFO — the unstarted tail stays ordered for the next unit tail
+            resolved += 1
+            try:
+                if self.accept_dialogs:
+                    dialog.accept()
+                else:
+                    dialog.dismiss()
+            except Exception as failure:
+                if "already handled" in str(failure):
+                    continue  # the step's capture resolved it — never double-handle
+                logger.warning("dialog resolution failed", extra={"error": str(failure)})
+        if self._pending:  # the drain cap held the unit open — the rest waits for the next unit tail
+            logger.warning(
+                "dialog drain limit reached; the rest resolves at the next unit tail",
+                extra={"pending": len(self._pending), "limit": _RESOLVE_PASS_LIMIT},
+            )

prettyplay/driver/session.py

@@ -0,0 +1,330 @@
+"""Lifecycle owner of the Playwright sync driver and the browser process of one test."""
+
+from __future__ import annotations
+
+import difflib
+import queue
+import re
+import threading
+from collections.abc import Callable
+from typing import TypeVar, cast
+
+from playwright.sync_api import Browser, BrowserContext, Error, Page, Playwright, sync_playwright
+
+from ..config import Config
+from .page import PageFacade, _DialogRouter
+
+_T = TypeVar("_T")
+
+
+class _Task:
+    """One unit of work crossing from the caller thread into the driver thread.
+
+    Attributes:
+        fn: the callable executed by the worker pump.
+        done: set once fn returned or raised in the worker thread.
+        result: the return value of fn; ``None`` until done.
+        error: the exception fn raised, if any.
+    """
+
+    __slots__ = ("done", "error", "fn", "result")
+
+    def __init__(self, fn: Callable[[], object]) -> None:
+        """Bind the callable; the outcome slots fill when the pump finishes.
+
+        Args:
+            fn: the callable executed by the worker pump.
+        """
+        self.fn = fn
+        self.done = threading.Event()
+        self.error: BaseException | None = None
+        self.result: object = None
+
+
+class PlaywrightWorker:
+    """The dedicated thread where the Playwright sync session lives — keeping the asyncio marker off the caller thread.
+
+    Attributes:
+        _tasks: the queue feeding the pump thread; ``None`` is the stop sentinel.
+        _thread: the pump thread; ``None`` before start and after close.
+    """
+
+    def __init__(self) -> None:
+        """Prepare the task queue; no thread exists yet."""
+        self._tasks: queue.SimpleQueue[Callable[[], object] | None] = queue.SimpleQueue()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        """Spawn the pump thread; it serves queued tasks until close."""
+        thread = threading.Thread(target=self._pump, name="prettyplay-playwright", daemon=True)
+        thread.start()
+        self._thread = thread
+
+    def run(self, fn: Callable[[], _T]) -> _T:
+        """Execute one callable in the driver thread and block for its outcome.
+
+        Args:
+            fn: the callable to execute; it must touch the Playwright objects
+                owned by the worker thread only.
+
+        Returns:
+            Whatever ``fn`` returns.
+
+        Raises:
+            Error: the worker is not running (stopped or never started) — the
+                same message Playwright itself raises on a stopped driver; or
+                the call arrives from the worker's own pump thread — code
+                running inside a driver-thread unit (a ``run_on_page``
+                action, step code) crossed the boundary again, a unit the
+                busy pump could never serve; the loud error replaces the
+                silent deadlock of both threads.
+        """
+        if self._thread is None:
+            raise Error("Event loop is closed! Is Playwright already stopped?")
+
+        if threading.current_thread() is self._thread:
+            raise Error(
+                "re-entrant crossing of the driver thread: code running inside a "
+                "driver-thread unit called back into the worker — an action inside "
+                "run_on_page (or step code) must use the genuine Page directly, "
+                "never the prettyplay test object, whose every call marshals into "
+                "the same worker and could never be served"
+            )
+
+        task = _Task(fn)
+        self._tasks.put(task)
+
+        task.done.wait()
+
+        if task.error is not None:
+            raise task.error
+
+        return cast(_T, task.result)
+
+    def close(self) -> None:
+        """Stop the pump thread and wait for its exit; idempotent."""
+        thread = self._thread
+        if thread is None:
+            return
+
+        self._tasks.put(None)
+        thread.join()
+        self._thread = None
+
+    def _pump(self) -> None:
+        """Serve queued tasks one by one until the stop sentinel arrives."""
+        while True:
+            task = self._tasks.get()
+            if task is None:
+                return
+
+            try:
+                task.result = task.fn()
+            except BaseException as error:  # exception propagates to the caller's thread
+                task.error = error
+            finally:
+                task.done.set()
+
+
+class DriverSession:
+    """Owns the Playwright sync driver and one browser process for one test.
+
+    Attributes:
+        _config: project settings; the ``browser`` group selects the engine of
+            the matrix, its ``screen`` sets the size mode of every context,
+            and its ``endpoint`` switches the start to a remote ws connect.
+        _playwright: the started Playwright driver; ``None`` until first start.
+        _browser: the connected or launched browser process; ``None`` until first start.
+        _worker: the thread owning the Playwright session; ``None`` until first start.
+    """
+
+    def __init__(self, config: Config) -> None:
+        """Keep the config; nothing is started yet.
+
+        Args:
+            config: project settings; the ``browser`` group selects the engine.
+        """
+        self._config = config
+        self._playwright: Playwright | None = None
+        self._browser: Browser | None = None
+        self._worker: PlaywrightWorker | None = None
+
+    def open_context(self) -> PageFacade:
+        """Open a fresh isolated context with one page wrapped into the handle.
+
+        Returns:
+            The page handle of a fresh isolated context — the driver and the
+            browser start lazily on the first call; the dialog router is
+            registered before ``new_page()``: every page of the context,
+            popups included, registers exactly one handler.
+
+        Raises:
+            Error: the ``screen`` value names a device absent from the
+                registry of the running Playwright.
+        """
+        if self._browser is None:
+            self._launch()
+
+        worker = self._worker
+        browser = self._browser
+
+        def open_isolated() -> tuple[Page, BrowserContext, _DialogRouter]:
+            """Open one fresh isolated context with one page in the driver thread.
+
+            Returns:
+                The page, its context and the dialog router registered
+                before the first page event.
+            """
+            params = self._screen_context_params()
+            context: BrowserContext = browser.new_context(**params)
+            router = _DialogRouter(self._config.browser.accept_dialogs)
+            # registered before new_page: the first page fires the event and registers once
+            context.on("page", lambda opened: opened.on("dialog", router.record))
+            page = context.new_page()
+            return page, context, router
+
+        page, context, router = worker.run(open_isolated)
+
+        facade = PageFacade(page, context)
+        facade._worker = worker  # handle calls marshal into the driver thread
+        facade._router = router  # the shared router records every dialog of every page of the context
+        return facade
+
+    def _screen_context_params(self) -> dict[str, object]:
+        """Resolve the screen setting of the browser group into context parameters.
+
+        Returns:
+            The ``new_context`` keyword arguments — resolved inside the
+            driver thread against the registry of the running Playwright:
+            empty keeps the default, ``fullscreen`` follows the window or
+            pins a viewport, a WxH value is a fixed viewport, anything else
+            is a device name.
+
+        Raises:
+            Error: the value names no device of the running registry; the
+                message carries the closest registry names.
+        """
+        group = self._config.browser
+        screen = group.screen
+
+        if screen == "":
+            return {}
+
+        if screen == "fullscreen":
+            if group.endpoint == "" and not group.headless:
+                return {"no_viewport": True}  # the viewport follows the window
+            return {"viewport": {"width": 1920, "height": 1080}}  # no window exists there
+
+        match = re.fullmatch(r"(\d+)x(\d+)", screen)
+        if match is not None:
+            return {"viewport": {"width": int(match.group(1)), "height": int(match.group(2))}}
+
+        devices = self._playwright.devices  # the registry of the running Playwright
+        if screen in devices:
+            return dict(devices[screen])
+
+        close = difflib.get_close_matches(screen, devices, n=3, cutoff=0.5)
+        suggestion = f" — closest names: {', '.join(close)}" if close else ""
+        raise Error(f"unknown screen device {screen!r}: not in the playwright device registry{suggestion}")
+
+    def close(self) -> None:
+        """Stop the browser, the Playwright driver and the worker; idempotent; a failing close never skips the rest."""
+        worker = self._worker
+        if worker is None:
+            return
+
+        try:
+            if self._browser is not None:
+                worker.run(self._browser.close)
+        finally:
+            self._browser = None
+
+            try:
+                if self._playwright is not None:
+                    worker.run(self._playwright.stop)
+            finally:
+                self._playwright = None
+                worker.close()
+                self._worker = None
+
+    def _launch(self) -> None:
+        """Start the driver thread, the Playwright session and the browser.
+
+        Raises:
+            Exception: whatever the engine start raises — on a launch or
+                connect failure the driver is stopped and the worker closed
+                before the error propagates, so a retry starts from a clean
+                state.
+        """
+        worker = PlaywrightWorker()
+        worker.start()
+
+        try:
+            playwright = worker.run(lambda: sync_playwright().start())
+        except BaseException:
+            worker.close()
+            raise
+
+        try:
+            browser = worker.run(lambda: self._launch_engine(playwright))
+        except BaseException:
+            # a browser that failed to start leaves no driver process alive
+            worker.run(playwright.stop)
+            worker.close()
+            raise
+
+        self._worker = worker
+        self._playwright = playwright
+        self._browser = browser
+
+    def _launch_engine(self, playwright: Playwright) -> Browser:
+        """Start the browser engine selected by the browser group of the configuration.
+
+        Args:
+            playwright: the started Playwright session of the worker thread.
+
+        Returns:
+            The connected or launched browser process — the group ``speed``
+            maps to the native ``slow_mo``, fixed at process start and never
+            a code wait; a set ``endpoint`` connects instead of launching,
+            with ``headless`` ignored; ``chrome``/``msedge`` launch through
+            the chromium engine with the matching channel.
+
+        Raises:
+            Error: a connect failure — re-raised wrapped with the endpoint,
+                chained to the original.
+        """
+        group = self._config.browser
+        name = group.name
+        # the pace setting maps linearly to the native slow_mo: 100 -> 0 ms, 0 -> 3000 ms
+        slow_mo = int((100 - group.speed) * 30)
+
+        engines: dict[str, object] = {
+            "chromium": playwright.chromium,
+            "firefox": playwright.firefox,
+            "webkit": playwright.webkit,
+        }
+
+        if group.endpoint:
+            endpoint = group.endpoint
+            engine = playwright.chromium if name in ("chrome", "msedge") else engines[name]
+            try:
+                return cast(Browser, engine.connect(endpoint, slow_mo=slow_mo))
+            except Error as failure:
+                raise Error(f"cannot connect to the browser endpoint {endpoint}: {failure}") from failure
+
+        channel: str | None
+        if name in ("chrome", "msedge"):
+            engine = playwright.chromium
+            channel = name
+        else:
+            engine = engines[name]
+            channel = None
+
+        launch_kwargs: dict[str, object] = {"headless": group.headless, "slow_mo": slow_mo}
+        if channel:
+            launch_kwargs["channel"] = channel
+        if group.screen == "fullscreen" and name in ("chromium", "chrome", "msedge") and not group.headless:
+            # a window exists only on a local headed launch — start it maximized
+            launch_kwargs["args"] = ["--start-maximized"]
+        return cast(Browser, engine.launch(**launch_kwargs))