prettyplay 0.0.0__py3-none-any.whl

prettyplay/driver/page.py

@@ -0,0 +1,350 @@
+"""The narrow, stable facade of a single test page and of one located element.
+
+The facade is the single page API the generated step code may work through —
+a backward-compatibility contract: it may only grow, never rename or remove.
+No raw Playwright object crosses the boundary; every return value is a plain
+``str``/``bytes`` or another facade. Auto-wait lives inside Playwright, so the
+facade never sleeps and never applies fixed delays. When the page belongs to a
+live driver session, every Playwright call is marshalled into the session's
+driver thread; a facade built without a worker (hand-built in tests) calls
+Playwright inline in the constructing thread.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+from playwright.sync_api import BrowserContext, Locator, Page, expect
+
+if TYPE_CHECKING:
+    from .session import PlaywrightWorker
+
+_T = TypeVar("_T")
+
+_SCROLL_INTO_VIEW_JS = """(el, target) => {
+    const cr = el.getBoundingClientRect();
+    const tr = target.getBoundingClientRect();
+    el.scrollTop += tr.top - cr.top - (el.clientHeight - tr.height) / 2;
+}"""
+
+
+class PageFacade:
+    """The only page API the generated step code may use.
+
+    Wraps one isolated browser context created by
+    :class:`~prettyplay.driver.session.DriverSession`; ``close`` closes the
+    context and leaves the browser of the test running.
+
+    Attributes:
+        _page: the wrapped Playwright page; never exposed through the facade.
+        _context: the isolated context owning the page; the facade boundary.
+        _worker: the driver thread of the owning session; ``None`` for
+            hand-built facades, which then call Playwright inline.
+    """
+
+    def __init__(self, page: Page, context: BrowserContext) -> None:
+        """Wrap one Playwright page of an isolated context.
+
+        Args:
+            page: the Playwright page object; never exposed through the facade.
+            context: the isolated context of the page; the facade boundary.
+        """
+        self._page = page
+        self._context = context
+        self._worker: PlaywrightWorker | None = None
+
+    def _call(self, fn: Callable[[], _T]) -> _T:
+        """Run one Playwright-touching callable in the driver thread.
+
+        Args:
+            fn: the callable touching the wrapped Playwright objects.
+
+        Returns:
+            Whatever ``fn`` returns.
+        """
+        if self._worker is None:
+            return fn()
+
+        return self._worker.run(fn)
+
+    @property
+    def url(self) -> str:
+        """The current URL of the page."""
+        return self._call(lambda: self._page.url)
+
+    def open(self, url: str) -> None:
+        """Navigate to the URL and wait for the load event.
+
+        Args:
+            url: the address to open.
+        """
+        self._call(lambda: self._page.goto(url))
+
+    def find_by_role(self, role: str, name: str) -> LocatorFacade:
+        """Find an element by its aria role and accessible name.
+
+        Args:
+            role: the aria role of the element, e.g. ``button``.
+            name: the accessible name of the element.
+
+        Returns:
+            The facade of the located element.
+        """
+        locator = self._call(lambda: self._page.get_by_role(role, name=name))
+        return self._wrap_locator(locator)
+
+    def find_by_label(self, label: str) -> LocatorFacade:
+        """Find a form element by its associated label.
+
+        Args:
+            label: the text of the label associated with the element.
+
+        Returns:
+            The facade of the located element.
+        """
+        locator = self._call(lambda: self._page.get_by_label(label))
+        return self._wrap_locator(locator)
+
+    def find_by_text(self, text: str) -> LocatorFacade:
+        """Find an element by its visible text.
+
+        Args:
+            text: the visible text of the element.
+
+        Returns:
+            The facade of the located element.
+        """
+        locator = self._call(lambda: self._page.get_by_text(text))
+        return self._wrap_locator(locator)
+
+    def find_by_attribute(self, name: str, value: str) -> LocatorFacade:
+        """Find an element by the value of one of its attributes.
+
+        Intended for data-* attributes (e.g. ``data-test-id``); the CSS engine
+        handles the attribute selector natively and the returned handle
+        auto-waits exactly like the other locating methods.
+
+        Args:
+            name: the full attribute name, e.g. ``data-test-id``.
+            value: the attribute value to match.
+
+        Returns:
+            The facade of the located element.
+        """
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        locator = self._call(lambda: self._page.locator(f'[{name}="{escaped}"]'))
+        return self._wrap_locator(locator)
+
+    def find_by_css(self, selector: str) -> LocatorFacade:
+        """Find an element by a CSS selector.
+
+        The selector is passed through verbatim — escaping belongs to the
+        caller, a universal escaping would break ``>``/``+`` combinators.
+
+        Args:
+            selector: a valid CSS selector expression, e.g. ``form > button.primary``.
+
+        Returns:
+            The facade of the located element.
+        """
+        locator = self._call(lambda: self._page.locator(selector))
+        return self._wrap_locator(locator)
+
+    def find_by_xpath(self, xpath: str) -> LocatorFacade:
+        """Find an element by an XPath expression.
+
+        The explicit ``xpath=`` engine prefix keeps every expression uniform:
+        Playwright sniffs XPath implicitly only via a ``//`` or ``..`` prefix,
+        so an expression such as ``*[@id='main']`` would otherwise silently go
+        to the CSS engine.
+
+        Args:
+            xpath: a valid XPath expression, e.g. ``//button[@type='submit']``.
+
+        Returns:
+            The facade of the located element.
+        """
+        locator = self._call(lambda: self._page.locator(f"xpath={xpath}"))
+        return self._wrap_locator(locator)
+
+    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 scroll_to_element(self, element: LocatorFacade) -> None:
+        """Scroll the page so the element enters the viewport.
+
+        Works inside the nearest scrollable ancestor when the element lives in
+        a scrollable container; the scrolled state is awaited by the follow-up
+        locators and expectations, never by a delay.
+
+        Args:
+            element: the located element to bring into view.
+        """
+        self._call(element._locator.scroll_into_view_if_needed)
+
+    def scroll_down(self, pixels: int) -> None:
+        """Scroll the page down by an amount.
+
+        Args:
+            pixels: a positive scroll amount in CSS pixels.
+        """
+        self._call(lambda: self._page.mouse.wheel(0, pixels))
+
+    def scroll_up(self, pixels: int) -> None:
+        """Scroll the page up by an amount.
+
+        Args:
+            pixels: a positive scroll amount in CSS pixels.
+        """
+        self._call(lambda: self._page.mouse.wheel(0, -pixels))
+
+    def scroll_to_bottom(self) -> None:
+        """Scroll the page to its end."""
+        self._call(lambda: self._page.evaluate("window.scrollTo(0, document.body.scrollHeight)"))
+
+    def scroll_to_top(self) -> None:
+        """Scroll the page to its start."""
+        self._call(lambda: self._page.evaluate("window.scrollTo(0, 0)"))
+
+    def scroll_into_view(self, element: LocatorFacade, container: LocatorFacade) -> None:
+        """Bring the element into the visible area of the specific scrollable container.
+
+        For nested scrollables where the nearest-ancestor behavior of
+        ``scroll_to_element`` is not enough. The target is resolved through
+        ``element_handle()`` (which auto-waits) and passed to the container
+        evaluation as the live handle argument.
+
+        Args:
+            element: the located element to bring into view.
+            container: the located scrollable container, e.g. a carousel.
+        """
+
+        def scroll() -> None:
+            handle = element._locator.element_handle()
+            container._locator.evaluate(_SCROLL_INTO_VIEW_JS, handle)
+
+        self._call(scroll)
+
+    def scroll_container_down(self, container: LocatorFacade, pixels: int) -> None:
+        """Scroll the scrollable container down by an amount.
+
+        Args:
+            container: the located scrollable container.
+            pixels: a positive scroll amount in CSS pixels.
+        """
+        self._call(lambda: container._locator.evaluate("(el, px) => { el.scrollTop += px; }", pixels))
+
+    def scroll_container_up(self, container: LocatorFacade, pixels: int) -> None:
+        """Scroll the scrollable container up by an amount.
+
+        Args:
+            container: the located scrollable container.
+            pixels: a positive scroll amount in CSS pixels.
+        """
+        self._call(lambda: container._locator.evaluate("(el, px) => { el.scrollTop -= px; }", pixels))
+
+    def close(self) -> None:
+        """Close the isolated context of the page; the test's browser keeps running."""
+        self._call(self._context.close)
+
+    def _wrap_locator(self, locator: Locator) -> LocatorFacade:
+        """Wrap a located element, inheriting the driver thread boundary.
+
+        Args:
+            locator: the Playwright locator object; never exposed.
+
+        Returns:
+            The facade of the located element.
+        """
+        facade = LocatorFacade(locator)
+        facade._worker = self._worker
+
+        return facade
+
+
+class LocatorFacade:
+    """An auto-waiting handle of one located element.
+
+    Actions and expectations delegate to the wrapped locator; expectations go
+    through Playwright ``expect`` and raise ``AssertionError`` on failure, so a
+    broken expectation reaches failure classification untouched.
+
+    Attributes:
+        _locator: the wrapped Playwright locator; never exposed through the facade.
+        _worker: the driver thread inherited from the page facade that created
+            this handle; ``None`` for hand-built handles, which then call
+            Playwright inline.
+    """
+
+    def __init__(self, locator: Locator) -> None:
+        """Wrap one Playwright locator.
+
+        Args:
+            locator: the Playwright locator object; never exposed through the facade.
+        """
+        self._locator = locator
+        self._worker: PlaywrightWorker | None = None
+
+    def _call(self, fn: Callable[[], _T]) -> _T:
+        """Run one Playwright-touching callable in the driver thread.
+
+        Args:
+            fn: the callable touching the wrapped Playwright objects.
+
+        Returns:
+            Whatever ``fn`` returns.
+        """
+        if self._worker is None:
+            return fn()
+
+        return self._worker.run(fn)
+
+    def click(self) -> None:
+        """Click the element with auto-wait."""
+        self._call(self._locator.click)
+
+    def fill(self, value: str) -> None:
+        """Set the text input value of the element.
+
+        Args:
+            value: the text to type into the element.
+        """
+        self._call(lambda: self._locator.fill(value))
+
+    def select_option(self, value: str) -> None:
+        """Choose one option of the element.
+
+        Args:
+            value: the value of the option to choose.
+        """
+        self._call(lambda: self._locator.select_option(value))
+
+    def expect_visible(self) -> None:
+        """Assert the element is visible."""
+        self._call(lambda: expect(self._locator).to_be_visible())
+
+    def expect_text(self, text: str) -> None:
+        """Assert the element contains the text.
+
+        Args:
+            text: the text the element must contain.
+        """
+        self._call(lambda: expect(self._locator).to_contain_text(text))
+
+    def expect_enabled(self) -> None:
+        """Assert the element is enabled."""
+        self._call(lambda: expect(self._locator).to_be_enabled())

prettyplay/driver/session.py

@@ -0,0 +1,288 @@
+"""Lifecycle owner of the Playwright sync driver and the browser process of one test."""
+
+from __future__ import annotations
+
+import queue
+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
+
+_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.
+
+    The Playwright sync API runs its private asyncio loop on a greenlet fiber
+    of the thread that started it, and that thread keeps the loop's running
+    marker until the session stops — which breaks any asyncio-driven host
+    (IPython, Jupyter) that executed a step in its own thread. The worker
+    keeps the fiber and the marker inside its own background thread instead;
+    calls still happen strictly sequentially through :meth:`run`.
+
+    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.
+        """
+        if self._thread is None:
+            raise Error("Event loop is closed! Is Playwright already stopped?")
+
+        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: a call before start and repeated calls are no-ops.
+        """
+        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.
+
+    The constructor starts nothing: the driver and the browser start lazily on
+    the first :meth:`open_context` call and then serve every step of the test.
+    Every call opens a fresh isolated browser context wrapped into a
+    :class:`PageFacade` — no state is shared between tests through the library.
+    The whole Playwright session lives inside the thread of a
+    :class:`PlaywrightWorker`, so the thread executing the steps never keeps a
+    running asyncio loop.
+
+    Attributes:
+        _config: project settings; ``browser`` selects the engine of the matrix,
+            ``browser_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 setting 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 facade.
+
+        The driver and the browser start lazily on the first call exactly once
+        per test; each subsequent call only creates a new isolated context.
+
+        Returns:
+            The facade of the new page of a fresh isolated context.
+        """
+        if self._browser is None:
+            self._launch()
+
+        worker = self._worker
+        browser = self._browser
+
+        def open_isolated() -> tuple[Page, BrowserContext]:
+            context: BrowserContext = browser.new_context()
+            return context.new_page(), context
+
+        page, context = worker.run(open_isolated)
+
+        facade = PageFacade(page, context)
+        facade._worker = worker  # facade calls go to the driver thread
+        return facade
+
+    def close(self) -> None:
+        """Stop the browser and the Playwright driver; safe when nothing was started.
+
+        Idempotent: repeated calls and a call before any launch are no-ops.
+        A failing browser close (e.g. after a crash) never skips the
+        Playwright stop and the worker thread join — its error still
+        propagates after both ran.
+        """
+        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.
+
+        Everything Playwright-touching runs inside the worker thread, so the
+        caller's thread never adopts the Playwright event loop. 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.
+
+        Raises:
+            Exception: whatever the engine start raises.
+        """
+        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 configuration.
+
+        A set ``browser_endpoint`` connects over the Playwright ws endpoint of
+        the selected engine instead of launching locally: the browser setting
+        selects the engine type (``chrome``/``msedge`` map to chromium —
+        channels do not apply to a connect) and ``headless`` is ignored, because
+        window visibility belongs to the endpoint server. Playwright's raw
+        connect error carries only the OS-level cause and never the endpoint
+        URL, so a failed connect is re-raised wrapped, chained to the original.
+
+        Otherwise every engine launches with the ``headless`` setting;
+        ``chrome``/``msedge`` name a locally installed browser launched through
+        the chromium engine with the matching channel. A channel launch without
+        the installed browser fails with Playwright's own actionable error,
+        propagated as-is.
+
+        Args:
+            playwright: the started Playwright session of the worker thread.
+
+        Returns:
+            The connected or launched browser process of the test.
+
+        Raises:
+            Error: a connect failure, wrapped with the endpoint in the message.
+        """
+        name = self._config.browser
+
+        engines: dict[str, object] = {
+            "chromium": playwright.chromium,
+            "firefox": playwright.firefox,
+            "webkit": playwright.webkit,
+        }
+
+        if self._config.browser_endpoint:
+            endpoint = self._config.browser_endpoint
+            engine = playwright.chromium if name in ("chrome", "msedge") else engines[name]
+            try:
+                return cast(Browser, engine.connect(endpoint))
+            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
+
+        if channel:
+            return cast(Browser, engine.launch(headless=self._config.headless, channel=channel))
+        return cast(Browser, engine.launch(headless=self._config.headless))

prettyplay/engine/.usages/generation.md

@@ -0,0 +1,45 @@
+# Step generation
+
+Domain: generating executable code for an unknown step. Audience: library internals and engineers debugging a first run.
+
+## Generate a step
+
+```python
+step = generator.generate(
+    identity=identity,
+    step_text="click the «Sign in» button",
+    previous_steps=["open the login page", "enter the login and password"],
+    page=page,
+)
+```
+
+- The loop: request code → execute against the live page → on failure re-request with the fresh error and snapshot
+- A non-empty generation_prompt setting adds a USER INSTRUCTIONS block to every generation and regeneration request — the project's code style guidance (e.g. prefer data-test-id attributes); classification requests never carry it; changing the instructions never invalidates the cache — cached steps run as stored
+- A failed check of a candidate (an assertion that executed and did not hold) stops the retries at once: the failure goes to classification — product_defect raises ProductDefectError with the verdict, anything else raises IncurableStepError with it; when the LLM is unavailable at this classification the verdict is skipped quietly (WARNING in the log) and IncurableStepError raises without it; one failed check is spent, never the whole budget
+- Other candidate failures (element not found, timeouts) retry with the fresh error and snapshot
+- Attempts are budgeted per step per test (default 3); exhaustion raises IncurableStepError carrying the classification verdict of the last candidate — when the LLM is unavailable the verdict is skipped quietly (WARNING in the log) and the failure raises without it
+- A success stores the step in the cache and returns it
+- Provider unavailability of a generation request raises LlmUnavailableError immediately — no retry on it
+
+## Classification call
+
+Both engines classify through one routine:
+
+```python
+from prettyplay.engine import classify_step_failure
+
+classification = classify_step_failure(
+    config=config,
+    provider=provider,
+    step_text="click the «Sign in» button",
+    code=step_code,
+    error="element not found: button «Sign in»",
+    page=page,
+)
+```
+
+The routine collects the fresh page snapshot (plus the screenshot when enabled) and calls the provider with the engine classification prompt. Provider unavailability propagates: the calling path decides whether it is a terminal infrastructure failure or a quiet verdict skip.
+
+## The fixed form
+
+Generated code is one function receiving exactly one argument — the page facade — and working only through the facade surface: page.find_by_role(...).click(), page.find_by_attribute("data-test-id", "submit").click(), page.find_by_css("form > button.primary"), page.find_by_xpath("//button[@type='submit']"), element.expect_visible(), page.scroll_down(600) and alike. No provider constructs, no direct driver imports, no fixed delays.