prettyplay 0.0.0__py3-none-any.whl

prettyplay/config/loader.py

@@ -0,0 +1,192 @@
+"""Loading of the ``[tool.prettyplay]`` section of pyproject.toml with layered overrides.
+
+The pyproject.toml path is either given explicitly or auto-searched upward from
+the current working directory. Environment overrides win over the file
+whenever the variable is set — including when it is set to an empty string:
+``PRETTYPLAY_<SETTING_UPPER>`` for every setting except the browser
+(``PRETTYPLAY_BROWSER_NAME``) and headless (``PRETTYPLAY_BROWSER_HEADLESS``).
+The removed legacy name ``PRETTYPLAY_BROWSER`` fails loudly before merging.
+Explicitly set programmatic values (``PrettyConfig`` fields passed at
+construction, non-empty for strings) win over the pyproject+env layer.
+LLM API keys are never read here: they come only from the provider clients
+themselves.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from ..failures.errors import PrettyplayError
+from .models import Config
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+#: The removed legacy env name; set — the load fails loudly before merging.
+_LEGACY_BROWSER_ENV = "PRETTYPLAY_BROWSER"
+
+#: Env variable name of every overridable setting; the two browser entries
+#: keep their historical special names.
+_ENV_NAMES: dict[str, str] = {
+    field: f"PRETTYPLAY_{field.upper()}"
+    for field in (
+        "provider",
+        "model",
+        "generation_model",
+        "classification_model",
+        "base_url",
+        "cache_root",
+        "generation_prompt",
+        "browser_endpoint",
+        "generation_attempts",
+        "healing_attempts",
+        "send_screenshots",
+    )
+}
+_ENV_NAMES["browser"] = "PRETTYPLAY_BROWSER_NAME"
+_ENV_NAMES["headless"] = "PRETTYPLAY_BROWSER_HEADLESS"
+
+#: The allowed-values text of the settings the validation render names.
+_ALLOWED_TEXT: dict[str, str] = {
+    "provider": "openai, anthropic",
+    "browser": "chromium, firefox, webkit, chrome, msedge",
+    "generation_attempts": "a positive integer",
+    "healing_attempts": "a positive integer",
+    "headless": "a boolean",
+    "send_screenshots": "a boolean",
+    "model": "a non-empty string",
+    "generation_model": "a non-empty string",
+    "classification_model": "a non-empty string",
+    "base_url": "a non-empty string",
+    "cache_root": "a non-empty string",
+    "generation_prompt": "a non-empty string",
+    "browser_endpoint": "a valid ws/wss URL",
+}
+
+
+class ConfigurationError(PrettyplayError):
+    """An invalid prettyplay configuration: the loaded settings failed validation.
+
+    Raised by :func:`load_config` with the original pydantic
+    ``ValidationError`` chained; catchable with the single library except
+    clause. Never carries a verdict — a configuration failure is not a step
+    failure.
+
+    Args:
+        message: the rendered actionable text — one line per invalid setting.
+    """
+
+
+def _find_pyproject() -> Path:
+    """Return the first existing pyproject.toml upward from the cwd.
+
+    Returns:
+        Absolute path of the found pyproject.toml.
+
+    Raises:
+        FileNotFoundError: when no pyproject.toml exists upward from the cwd.
+    """
+    for directory in (Path.cwd(), *Path.cwd().parents):
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+
+    raise FileNotFoundError("pyproject.toml not found upward from the current directory")
+
+
+def _collect_env_overrides() -> dict[str, str]:
+    """Collect the set environment overrides of all supported settings."""
+    overrides: dict[str, str] = {}
+
+    for field, env_name in _ENV_NAMES.items():
+        value = os.environ.get(env_name)
+        if value is not None:
+            overrides[field] = value
+
+    return overrides
+
+
+def _render_validation(error: ValidationError) -> str:
+    """Render the pydantic error as actionable per-setting lines.
+
+    Args:
+        error: the pydantic validation failure of the merged settings.
+
+    Returns:
+        One line per invalid setting — the setting name, the received value
+        and the allowed values or range — joined with newlines; no pydantic
+        internals in the user-visible text.
+    """
+    lines: list[str] = []
+
+    for entry in error.errors():
+        field = entry["loc"][0]
+        received = entry.get("input")
+        allowed = _ALLOWED_TEXT.get(str(field), entry["msg"])
+        lines.append(f"{field}: received {received!r} — allowed: {allowed}")
+
+    return "\n".join(lines)
+
+
+def load_config(pyproject_path: str | None = None, overrides: Config | None = None) -> Config:
+    """Load validated settings layered pyproject → env → explicit programmatic values.
+
+    The section is optional: a missing ``[tool.prettyplay]`` yields defaults.
+    Environment variables override the file value whenever they are set, empty
+    string included: ``PRETTYPLAY_BROWSER_NAME`` for the browser,
+    ``PRETTYPLAY_BROWSER_HEADLESS`` for headless and
+    ``PRETTYPLAY_<SETTING_UPPER>`` for every other setting. An empty
+    ``cache_root`` resolves to ``<pyproject_dir>/.prettyplay/cache``.
+
+    The programmatic layer wins last: a field of ``overrides`` participates
+    when it was passed at construction (``model_fields_set``) and is non-empty
+    for strings — explicitly set values win, untouched model defaults and
+    empty strings never overwrite the pyproject+env values.
+
+    Args:
+        pyproject_path: explicit pyproject.toml path; ``None`` auto-searches
+            upward from the current working directory.
+        overrides: the programmatic layer, typically a ``PrettyConfig`` built
+            by the integrator; ``None`` (or an instance with no explicitly set
+            fields) returns the validated file layer as is.
+
+    Returns:
+        Validated configuration.
+
+    Raises:
+        FileNotFoundError: when ``pyproject_path`` is ``None`` and no
+            pyproject.toml is found upward from the cwd.
+        tomllib.TOMLDecodeError: when the file is not valid TOML.
+        ConfigurationError: when merged settings fail validation — the
+            original ``ValidationError`` chained as the cause.
+    """
+    path = Path(pyproject_path) if pyproject_path is not None else _find_pyproject()
+
+    with path.open("rb") as stream:
+        data = tomllib.load(stream)
+    section = data.get("tool", {}).get("prettyplay", {})
+
+    if _LEGACY_BROWSER_ENV in os.environ:
+        raise ConfigurationError(f"{_LEGACY_BROWSER_ENV} is no longer supported: use PRETTYPLAY_BROWSER_NAME")
+
+    merged = {**section, **_collect_env_overrides()}
+
+    if not merged.get("cache_root"):
+        merged["cache_root"] = str(path.parent / ".prettyplay" / "cache")
+
+    try:
+        file_config = Config(**merged)
+    except ValidationError as error:
+        raise ConfigurationError(_render_validation(error)) from error
+
+    if overrides is None:
+        return file_config
+
+    explicit = overrides.model_fields_set
+    update = {name: value for name, value in overrides if name in explicit and (value or not isinstance(value, str))}
+
+    return file_config.model_copy(update=update)

prettyplay/config/models.py

@@ -0,0 +1,92 @@
+"""Validated project settings of prettyplay.
+
+The single source of the immutable configuration part. Secrets (LLM API keys)
+never live here: they come only from environment variables.
+"""
+
+from typing import Literal
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, ConfigDict, PositiveInt, field_validator
+
+
+class Config(BaseModel):
+    """Validated project settings loaded from ``[tool.prettyplay]``.
+
+    Every field has an empty default so the model can be constructed before a
+    pyproject.toml section exists; ``load_config`` fills and resolves it.
+
+    Attributes:
+        provider: the LLM provider of the {openai, anthropic} set; default openai.
+        browser: browser of the {chromium, firefox, webkit, chrome, msedge} set;
+            chrome and msedge launch the locally installed browser through the
+            driver channel mechanism; default chromium.
+        model: main LLM model name.
+        generation_model: optional generation override; empty falls back to ``model``.
+        classification_model: optional classification override; empty falls back to ``model``.
+        base_url: optional custom LLM API endpoint.
+        cache_root: cache root; empty means the default resolved at load.
+        generation_prompt: user instructions for generation requests; non-empty
+            renders a separate USER INSTRUCTIONS block in generation and
+            regeneration requests; empty means no block.
+        browser_endpoint: ws endpoint of a remote browser; empty means the local
+            launch; on a remote connect headless is ignored.
+        generation_attempts: generation attempt budget per step per test; default 3.
+        healing_attempts: healing attempt budget per step per test; default 2.
+        send_screenshots: whether screenshots are attached to LLM requests.
+        headless: run the browser without a visible window; default True.
+    """
+
+    model_config = ConfigDict(kw_only=True)
+
+    provider: Literal["openai", "anthropic"] = "openai"
+    browser: Literal["chromium", "firefox", "webkit", "chrome", "msedge"] = "chromium"
+    model: str = ""
+    generation_model: str = ""
+    classification_model: str = ""
+    base_url: str = ""
+    cache_root: str = ""
+    generation_prompt: str = ""
+    browser_endpoint: str = ""
+    generation_attempts: PositiveInt = 3
+    healing_attempts: PositiveInt = 2
+    send_screenshots: bool = False
+    headless: bool = True
+
+    @field_validator("browser_endpoint")
+    @classmethod
+    def _validate_browser_endpoint(cls, value: str) -> str:
+        """Check that a non-empty endpoint is a ws/wss URL.
+
+        Args:
+            value: the raw endpoint setting; empty means the local launch.
+
+        Returns:
+            The unchanged endpoint when empty or a valid ws/wss URL.
+
+        Raises:
+            ValueError: when a non-empty endpoint is not a ws/wss URL.
+        """
+        if not value:
+            return value
+
+        parsed = urlparse(value)
+
+        if parsed.scheme not in {"ws", "wss"} or not parsed.netloc:
+            raise ValueError("must be a valid ws/wss URL")
+
+        return value
+
+    @property
+    def effective_generation_model(self) -> str:
+        """Return generation_model when non-empty, otherwise model."""
+        return self.generation_model if self.generation_model else self.model
+
+    @property
+    def effective_classification_model(self) -> str:
+        """Return classification_model when non-empty, otherwise model."""
+        return self.classification_model if self.classification_model else self.model
+
+
+#: The public name of ``Config``: the integrator-facing settings model.
+PrettyConfig = Config

prettyplay/driver/.usages/facade.md

@@ -0,0 +1,66 @@
+# Driver facade
+
+Domain: the browser facade of prettyplay. Audience: consumers of the page API — the step generation engine and engineers reading or hand-writing step code.
+
+The facade wraps the Playwright sync API. Step code receives a `PageFacade` and works only through it and `LocatorFacade` — never through raw Playwright objects. The method set is a backward-compatibility contract: cached step code keeps working across library upgrades.
+
+## Surface
+
+| Call | Purpose |
+|---|---|
+| page.open(url) | navigate and wait for load |
+| page.find_by_role(role, name) | element by aria role and accessible name |
+| page.find_by_label(label) | element by associated label |
+| page.find_by_text(text) | element by visible text |
+| page.find_by_attribute(name, value) | element by attribute value — data-* attributes |
+| page.find_by_css(selector) | element by CSS selector |
+| page.find_by_xpath(xpath) | element by XPath expression |
+| page.aria_snapshot() | accessibility-tree page state |
+| page.screenshot() | full-page PNG bytes |
+| page.url | current URL |
+| page.scroll_to_element(element) | bring an element into the viewport (works inside scrollable ancestors) |
+| page.scroll_down(pixels) | scroll the page down by an amount |
+| page.scroll_up(pixels) | scroll the page up by an amount |
+| page.scroll_to_bottom() | scroll to the end of the page |
+| page.scroll_to_top() | scroll to the start of the page |
+| page.scroll_into_view(element, container) | bring an element into view inside a specific scrollable container |
+| page.scroll_container_down(container, pixels) | scroll a scrollable container down by an amount |
+| page.scroll_container_up(container, pixels) | scroll a scrollable container up by an amount |
+| element.click() | click with auto-wait |
+| element.fill(value) | set input text |
+| element.select_option(value) | choose an option |
+| element.expect_visible() | assert visible |
+| element.expect_text(text) | assert text |
+| element.expect_enabled() | assert enabled |
+
+## Example
+
+```python
+page.open("https://example.com/login")
+page.find_by_label("Username").fill("user")
+page.find_by_label("Password").fill("secret")
+page.find_by_role("button", name="Sign in").click()
+page.find_by_text("Welcome back").expect_visible()
+
+# locating by data attributes, CSS and XPath
+page.find_by_attribute("data-test-id", "submit-button").click()
+page.find_by_css("form > button.primary").expect_enabled()
+page.find_by_xpath("//button[@type='submit']").expect_visible()
+
+# scroll scenarios
+page.scroll_down(600)
+page.find_by_text("Footer").expect_visible()
+
+cards = page.find_by_role("list", name="Recommendations")
+page.scroll_container_down(cards, 400)
+page.find_by_text("Fifth card").expect_visible()
+
+snapshot = page.aria_snapshot()
+```
+
+## Rules
+
+- One browser process per test: each test owns its browser through its runtime; contexts stay isolated
+- Every call executes in the library's driver thread and returns when done: driving is strictly sequential, and the calling thread never adopts the Playwright event loop — hand-written step code stays safe in interactive hosts (IPython, Jupyter)
+- Auto-wait everywhere: no time.sleep, no fixed delays in step code — including around scrolls: the scrolled state is awaited through locators and expectations
+- Never put secrets into step actions — step texts and code land in the repository cache

prettyplay/driver/CODEMANIFEST

@@ -0,0 +1,162 @@
+Imports:
+  - Types:
+      - Config
+    From: prettyplay/config
+
+Usages:
+  conventions: .goga/usages/conventions.md
+  playwright: .goga/usages/cooks/playwright.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+  Use `playwright` for the sync API lifecycle, locators, auto-wait, the accessibility snapshot, browser channels, remote connects and the scroll primitives.
+
+  The driver is Playwright sync-only: the async API is out of scope.
+  The whole Playwright session — start, browser, contexts, pages — lives in one dedicated driver thread owned by the library: the sync API parks its private event loop on its starting thread, so the thread executing the steps never holds a running asyncio loop (interactive hosts such as IPython and Jupyter keep working between steps).
+  Driver-thread calls are strictly sequential: one facade call runs at a time; concurrent driving is out of scope.
+  One browser process per test: the session is owned by the test's runtime — no state is shared between tests through the library.
+  The start mode branches on the browser_endpoint setting of `Config`: empty — local launch with headless and the channel for chrome/msedge; set — connect over the Playwright ws endpoint: headless is ignored, channels do not apply, the browser setting selects the engine (see `playwright`).
+  All waits go through locators and expectations; fixed delays (time.sleep and similar) are forbidden.
+  The facade surface is a backward-compatibility contract: generated step code works only through `PageFacade` and LocatorFacade, so the existing method set must not break across library releases — extend, never rename or remove.
+
+---
+
+"DriverSession(config: Config)":
+  location: session.py
+  annotations: |
+    Lifecycle owner of the Playwright sync driver and the browser process of one test.
+
+    `config`: project settings; the browser setting selects the browser of the {chromium, firefox, webkit, chrome, msedge} set — chrome and msedge launch the locally installed browser through the channel mechanism; headless controls the window visibility of a local launch; browser_endpoint switches the start to a remote connect (see `playwright`).
+
+    Requirements:
+    - The Playwright session lives in a dedicated driver thread owned by the session: every Playwright-touching operation of this type runs there, and the calling thread never holds a running asyncio loop after any call
+  methods:
+    "open_context() -> page: PageFacade": |
+      Open a fresh isolated context with one page of this test's browser.
+
+      Algorithm:
+      1. Start lazily on the first call: constructing the session starts nothing — start the dedicated driver thread, then start Playwright inside it; an empty browser_endpoint — launch the selected engine locally with headless from the project settings and the channel for the chrome/msedge values; a set browser_endpoint — connect over the Playwright ws endpoint of the selected engine: headless is ignored and channels do not apply; a failed launch or connect stops the started driver and closes the thread, so a retry begins from a clean state
+      2. Create a fresh isolated browser context and its page inside the driver thread (see `playwright`)
+      3. Wrap the page into `PageFacade` bound to the driver thread and return it
+
+      Requirements:
+      - Each result is isolated from every other context
+      - A channel launch without the installed browser fails loudly with an actionable message naming the missing browser
+      - A failed connect fails loudly with an actionable message naming the endpoint
+    "close()": |
+      Stop the browser, the Playwright driver and the driver thread; safe to call when nothing was started.
+
+"PageFacade(page: Page, context: BrowserContext)":
+  location: page.py
+  annotations: |
+    The narrow, stable facade of a single test page — the only page API the generated step code may use.
+    Wraps one isolated browser context created by `DriverSession`.
+
+    `page`: the wrapped Playwright page object; never exposed through the facade.
+    `context`: the isolated browser context owning the page; the boundary the close method closes.
+
+    Requirements:
+    - Every Playwright call runs in the driver thread of the owning session: the call blocks until it finishes, strictly one at a time, and the calling thread never adopts the Playwright event loop
+    - Locating methods never sleep: waiting is the locator's own auto-wait behavior
+    - Scroll methods never sleep: the scrolled state is awaited through locators and expectations
+    - aria_snapshot and screenshot reflect the state at call time
+
+    Constraints:
+    - No method exposes raw Playwright objects: the facade is the boundary generated code works against
+  properties:
+    "url -> str": |
+      The current page URL.
+  methods:
+    "open(url: str)": |
+      Navigate to `url` and wait for the load state (see `playwright`).
+    "find_by_role(role: str, name: str) -> element: LocatorFacade": |
+      Locate one element by its aria role and accessible name; returns a `LocatorFacade`.
+    "find_by_label(label: str) -> element: LocatorFacade": |
+      Locate one element by its associated label; returns a `LocatorFacade`.
+    "find_by_text(text: str) -> element: LocatorFacade": |
+      Locate one element by its visible text; returns a `LocatorFacade`.
+    "find_by_attribute(name: str, value: str) -> element: LocatorFacade": |
+      Locate one element by the value of the attribute `name` — the intended use is data-* attributes (data-test-id, data-qa and any other data attribute). Auto-waits exactly like the other locating methods.
+
+      `name`: the full attribute name, e.g. data-test-id.
+      `value`: the attribute value to match.
+    "find_by_css(selector: str) -> element: LocatorFacade": |
+      Locate one element by a CSS selector.
+
+      `selector`: a valid CSS selector expression, e.g. form > button.primary.
+    "find_by_xpath(xpath: str) -> element: LocatorFacade": |
+      Locate one element by an XPath expression.
+
+      `xpath`: a valid XPath expression, e.g. //button[@type='submit'].
+    "aria_snapshot() -> snapshot: str": |
+      The structured accessibility-tree representation of the page — the primary machine-readable page state (see `playwright`).
+    "screenshot() -> image: bytes": |
+      A full-page PNG image of the current state.
+    "scroll_to_element(element: LocatorFacade)": |
+      Scroll the page so `element` enters the viewport — inside its nearest scrollable ancestor when the element lives in a scrollable container (see `playwright`).
+
+      `element`: the located element to bring into view.
+    "scroll_down(pixels: int)": |
+      Scroll the page down by `pixels`.
+
+      `pixels`: a positive scroll amount in CSS pixels.
+    "scroll_up(pixels: int)": |
+      Scroll the page up by `pixels`.
+
+      `pixels`: a positive scroll amount in CSS pixels.
+    "scroll_to_bottom()": |
+      Scroll the page to its end.
+    "scroll_to_top()": |
+      Scroll the page to its start.
+    "scroll_into_view(element: LocatorFacade, container: LocatorFacade)": |
+      Bring `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 (see `playwright`).
+
+      `element`: the located element to bring into view.
+      `container`: the located scrollable container, e.g. a carousel.
+    "scroll_container_down(container: LocatorFacade, pixels: int)": |
+      Scroll the scrollable `container` down by `pixels`.
+
+      `container`: the located scrollable container.
+      `pixels`: a positive scroll amount in CSS pixels.
+    "scroll_container_up(container: LocatorFacade, pixels: int)": |
+      Scroll the scrollable `container` up by `pixels`.
+
+      `container`: the located scrollable container.
+      `pixels`: a positive scroll amount in CSS pixels.
+    "close()": |
+      Close the isolated context of this page; the browser process keeps running.
+
+"LocatorFacade(locator: Locator)":
+  location: page.py
+  annotations: |
+    An auto-waiting handle of one located element — the only element API the generated step code may use.
+
+    `locator`: the wrapped Playwright locator object; never exposed through the facade.
+
+    Requirements:
+    - Every action and expectation runs in the driver thread inherited from the page facade that created the handle
+    - Every action and expectation auto-waits for actionability (see `playwright`)
+    - Failed expectations raise assertion-style errors destined for failure classification
+
+    Constraints:
+    - No fixed delays; no raw Playwright objects exposed
+  methods:
+    "click()": |
+      Click the element, waiting for actionability.
+    "fill(value: str)": |
+      Set the text input value of the element to `value`.
+    "select_option(value: str)": |
+      Select the option with `value` in a list or combo box.
+    "expect_visible()": |
+      Assert the element is visible.
+    "expect_text(text: str)": |
+      Assert the element text equals or contains `text`.
+    "expect_enabled()": |
+      Assert the element is enabled.
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  The Playwright sync driver of prettyplay: the per-test session with local launches and remote ws connects, and the narrow backward-compatible page facade with universal locators and scroll abilities for generated step code.

prettyplay/driver/__init__.py

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