artest-browser 0.2.0__py3-none-any.whl

artest/browser/__init__.py

@@ -0,0 +1,73 @@
+"""Browser automation for Artest: funnel explorer, captures, vision tiles and variant rendering.
+
+This package owns Playwright. The explorer and the variant renderer share one browser pool, as persona
+sessions would, which are parked (ADR-0020).
+"""
+
+from artest.browser.capture import BlobSink, capture_page
+from artest.browser.decide import ExploreState, Move, MoveKind, Stop, next_move
+from artest.browser.explorer import (
+    Decider,
+    ExploreOptions,
+    ExploreResult,
+    RobotsDisallowedError,
+    StuckWalkError,
+    explore_funnel,
+)
+from artest.browser.identity import SYNTHETIC_SHOPPER, ShopAccount, Shopper
+from artest.browser.render import PixelDiff, RenderRefusedError, pixel_diff, render
+from artest.browser.trace import FunnelTrace, TraceStep, perform, replay
+from artest.browser.viewports import VIEWPORTS, new_context
+from artest.browser.vision import (
+    Mark,
+    Tile,
+    TileError,
+    TilePlan,
+    TokenRule,
+    cut_tiles,
+    numbered_elements,
+    plan_screen,
+    plan_tiles,
+    render_tiles,
+)
+from artest.core import ExploreOutcome
+
+__all__ = [
+    "SYNTHETIC_SHOPPER",
+    "VIEWPORTS",
+    "BlobSink",
+    "Decider",
+    "ExploreOptions",
+    "ExploreOutcome",
+    "ExploreResult",
+    "ExploreState",
+    "FunnelTrace",
+    "Mark",
+    "Move",
+    "MoveKind",
+    "PixelDiff",
+    "RenderRefusedError",
+    "RobotsDisallowedError",
+    "ShopAccount",
+    "Shopper",
+    "Stop",
+    "StuckWalkError",
+    "Tile",
+    "TileError",
+    "TilePlan",
+    "TokenRule",
+    "TraceStep",
+    "capture_page",
+    "cut_tiles",
+    "explore_funnel",
+    "new_context",
+    "next_move",
+    "numbered_elements",
+    "perform",
+    "pixel_diff",
+    "plan_screen",
+    "plan_tiles",
+    "render",
+    "render_tiles",
+    "replay",
+]

artest/browser/capture.py

@@ -0,0 +1,456 @@
+"""Capture one page state: the record (screenshot, DOM, accessibility tree), the elements agents cite, and
+what the browser measured on the page (see ``measure``)."""
+
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from importlib.resources import files
+from typing import Any, Protocol
+from urllib.parse import urldefrag
+
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import Page
+from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+from pydantic import BaseModel, TypeAdapter
+
+from artest.browser.measure import (
+    AxeRun,
+    Covers,
+    PageActivity,
+    PageMonitor,
+    check_accessibility,
+    check_covers,
+    own_resize,
+)
+from artest.core import (
+    ArtifactRef,
+    AxeImpact,
+    AxeReport,
+    AxeViolation,
+    Box,
+    Capture,
+    ElementRef,
+    FieldMessage,
+    FixedLayer,
+    FormProbe,
+    PastEdge,
+    Size,
+    ValidityReason,
+    Viewport,
+)
+
+_ELEMENTS_SCRIPT = files("artest.browser").joinpath("js/elements.js").read_text("utf-8")
+
+
+class BlobSink(Protocol):
+    """Where captured bytes go. The engine passes the run's artifact store; tests pass memory."""
+
+    async def put(self, data: bytes, media_type: str) -> ArtifactRef: ...
+
+
+class _MeasuredElement(BaseModel):
+    role: str
+    name: str
+    tag: str
+    text: str
+    selector: str
+    box: Box
+    visible: bool
+    wordsShown: str | None  # noqa: N815 - the key the in-page script returns
+    blank: bool
+    fixed: bool
+    pastEdge: PastEdge | None  # noqa: N815 - the key the in-page script returns
+    attributes: dict[str, str]
+    form: int | None
+
+
+class _MeasuredFixed(BaseModel):
+    roots: list[str]
+    screen: Box
+    ratio: float
+    solid: list[Box]
+
+
+class _Measured(BaseModel):
+    title: str
+    pageSize: Size  # noqa: N815 - the key the in-page script returns
+    fixed: _MeasuredFixed | None
+    elements: list[_MeasuredElement]
+
+
+_measured = TypeAdapter(_Measured)
+_ATTEMPTS = 3
+_IDLE_PATIENCE = 15.0
+"""Seconds a page gets to go idle before what it holds open reads as something that won't end."""
+_SHOT: dict[str, Any] = {"type": "png", "animations": "disabled", "caret": "hide"}
+_HAS_FOCUS = "() => ![null, document.body, document.documentElement].includes(document.activeElement)"
+_ROOT_PAINTS = """() => [document.documentElement, document.body].some((node) => {
+  const { backgroundColor, backgroundImage } = getComputedStyle(node);
+  return backgroundImage !== "none" || !/^rgba\\(.*, 0\\)$|transparent/.test(backgroundColor);
+})"""
+_ADD_SHEET = """(css) => {
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(css);
+  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+  return sheet;
+}"""
+_TAKE_SHEET = """(sheet) => {
+  document.adoptedStyleSheets = document.adoptedStyleSheets.filter((other) => other !== sheet);
+  for (const animation of document.getAnimations()) {
+    if (animation instanceof CSSTransition && /^(visibility|opacity)$/.test(animation.transitionProperty)) {
+      animation.finish();
+    }
+  }
+}"""
+_FONTS_READY = (
+    "Promise.race([document.fonts.ready, new Promise((done) => setTimeout(done, 5000))]).then(() => true)"
+)
+
+
+class CaptureError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class EmptySubmit:
+    """A form the explorer submitted empty, for the capture that shows what came of it."""
+
+    capture_id: str
+    form: str
+    """The form's selector."""
+    browser_messages: tuple[tuple[str, ValidityReason, str], ...] = ()
+    """The fields the browser's own validation flagged: each one's selector, why, and the message shown."""
+
+
+@dataclass(frozen=True)
+class _FixedShots:
+    page: bytes
+    layer: bytes
+
+
+@dataclass(frozen=True)
+class _Read:
+    url: str
+    measured: _Measured
+    screenshot: bytes
+    dom: str
+    aria: str
+    axe: AxeRun | None
+    settled: bool
+
+
+@dataclass(frozen=True)
+class PageRead:
+    """All a capture read from one page. Nothing of it is stored yet, so that it can still be refused."""
+
+    read: _Read
+    covers: Covers
+    activity: PageActivity | None
+    size: Size
+    fixed_shots: _FixedShots | None = None
+
+    @property
+    def url(self) -> str:
+        return self.read.url
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+async def settle(page: Page, monitor: PageMonitor | None = None) -> bool:
+    """Wait until the page has stopped loading and its fonts are ready, so captures are stable, and say
+    whether it did.
+
+    A page can hold a request open for as long as it lives, as a chat widget's long poll does, and look
+    finished to a shopper. With a ``monitor`` to say what it is waiting for, such a page gets
+    ``_IDLE_PATIENCE`` seconds and is then taken as it stands, which says False. What a page can't be drawn
+    without gets the browser's own wait, whose timeout ends the walk. Without a monitor, anything does.
+    """
+    settled = await _went_idle(page, monitor) if monitor is not None else None
+    if monitor is None:
+        await page.wait_for_load_state("networkidle")
+    # With a time limit, as a font a page asked for after it went idle may never come.
+    await page.evaluate(_FONTS_READY)
+    return settled is not False
+
+
+async def _went_idle(page: Page, monitor: PageMonitor) -> bool:
+    # One wait a document, as the capture after an action asks again. It may still have gone idle since.
+    patience = 0.1 if monitor.gave_up_waiting else None if monitor.waits_whole else _IDLE_PATIENCE
+    try:
+        if patience is not None:
+            try:
+                await page.wait_for_load_state("networkidle", timeout=patience * 1000)
+            except PlaywrightTimeoutError:
+                if monitor.still_needs_something():
+                    await page.wait_for_load_state("networkidle")
+                else:
+                    raise
+        else:
+            await page.wait_for_load_state("networkidle")
+    except PlaywrightTimeoutError:
+        if monitor.still_needs_something():
+            raise
+        monitor.gave_up_waiting = True
+        return False
+    return True
+
+
+async def capture_page(
+    page: Page,
+    *,
+    capture_id: str,
+    viewport: Viewport,
+    sink: BlobSink,
+    clock: Callable[[], datetime] = utc_now,
+    monitor: PageMonitor | None = None,
+    probe: EmptySubmit | None = None,
+) -> Capture:
+    """Read the page once it has settled (see ``read_page``), and keep what was read (see ``keep_page``)."""
+    read = await read_page(page, monitor=monitor)
+    return await keep_page(
+        read, capture_id=capture_id, viewport=viewport, sink=sink, clock=clock, probe=probe
+    )
+
+
+async def read_page(page: Page, *, monitor: PageMonitor | None = None) -> PageRead:
+    """Read the page once it has settled.
+
+    A page can start navigating after it looked settled, say when a form posts and redirects a moment
+    after the click. A read that sees a navigation starts again on the page it lands on, so the
+    screenshot, DOM, elements and accessibility check always come from one page. A new #fragment, as a
+    carousel may set, is the same page. Web Vitals, console and network come from ``monitor``; without
+    one, the capture has none.
+    """
+    for _ in range(_ATTEMPTS):
+        url = page.url
+        try:
+            read = await _read(page, monitor)
+            if read is None or urldefrag(read.url).url != urldefrag(url).url:
+                continue
+            covers = await _covers(page, read.measured)
+            # A navigation doesn't always say so in what it breaks, so what the probe missed has to be asked.
+            if urldefrag(page.url).url != urldefrag(url).url:
+                continue
+            activity = await monitor.take() if monitor is not None else None
+        except PlaywrightError as error:
+            # Whatever goes wrong on a page that has since moved on says nothing about where it is now:
+            # a screenshot that a new document overtakes can sit out its whole timeout.
+            if "navigat" not in error.message and urldefrag(page.url).url == urldefrag(url).url:
+                raise
+            continue
+        size = page.viewport_size or {"width": 0, "height": 0}
+        shots = await _shoot_fixed(page, read.measured.fixed, read.screenshot)
+        # What the shots hold is only worth having if they are of this page.
+        same = urldefrag(page.url).url == urldefrag(url).url
+        return PageRead(
+            read, covers, activity, Size(width=size["width"], height=size["height"]), shots if same else None
+        )
+    msg = f"{page.url} kept navigating while it was captured"
+    raise CaptureError(msg)
+
+
+async def _read(page: Page, monitor: PageMonitor | None) -> _Read | None:
+    """Read the page, or nothing if it has moved on by the time of the screenshot: painting a page before its
+    stylesheets have come would make the styled page read as a shift no shopper sees."""
+    start = urldefrag(page.url).url
+    settled = await settle(page, monitor)
+    screen = page.viewport_size
+    measured = _measured.validate_python(
+        await page.evaluate(_ELEMENTS_SCRIPT, screen["width"] if screen is not None else None)
+    )
+    if urldefrag(page.url).url != start:
+        return None
+    async with own_resize(page):
+        screenshot = await page.screenshot(**_SHOT, full_page=True)
+    dom = await page.content()
+    aria = await page.locator("body").aria_snapshot()
+    # Last, so that nothing axe-core does to look at the page can show in the record.
+    try:
+        axe = await check_accessibility(page, [element.selector for element in measured.elements])
+    except PlaywrightError as error:
+        # A navigation starts the capture again; a page axe-core can't check is left unchecked.
+        if "navigat" in error.message:
+            raise
+        axe = None
+    return _Read(
+        url=page.url,
+        measured=measured,
+        screenshot=screenshot,
+        dom=dom,
+        aria=aria,
+        axe=axe,
+        settled=settled,
+    )
+
+
+async def _shoot_fixed(page: Page, fixed: _MeasuredFixed | None, whole: bytes) -> _FixedShots | None:
+    """The page without what is fixed to the screen, and one screen of nothing else, for drawing tiles.
+
+    It comes last in a read, as hiding things can start what the page does about that, so nothing else read
+    from the page can show it. Hiding what has focus would make the page think a shopper left a field, so a
+    page with something focused is drawn as the record draws it. So is one a style sheet can't clear, one that
+    changes size meanwhile, and a phone's page laid out wider than the phone's screen, whose screen isn't what
+    it measured. Nothing here can cost the capture what it has.
+    """
+    if fixed is None:
+        return None
+    roots = ", ".join(fixed.roots)
+    within = ", ".join(f"{root} *" for root in fixed.roots)
+    only = (
+        "html:root:root:root, html:root:root:root > body "
+        "{ background: transparent !important; transition: none !important; } "
+        f"*:not({roots}, {within}) {{ visibility: hidden !important; }} "
+        # A root shows again by inheriting its own, as what its page hides inside it stays hidden.
+        f"{roots} {{ visibility: visible !important; }}"
+    )
+    try:
+        if await page.evaluate(_HAS_FOCUS):
+            return None
+        hidden = f"html:root:root:root :is({roots}) {{ opacity: 0 !important; }}"
+        async with _style_sheet(page, hidden), own_resize(page):
+            without = await page.screenshot(**_SHOT, full_page=True)
+        async with _style_sheet(page, only):
+            if await page.evaluate(_ROOT_PAINTS):
+                return None
+            alone = await page.screenshot(**_SHOT, omit_background=True)
+    except PlaywrightError:
+        return None
+    screen = (round(fixed.screen.width * fixed.ratio), round(fixed.screen.height * fixed.ratio))
+    if _png_size(without) != _png_size(whole) or _png_size(alone) != screen:
+        return None
+    return _FixedShots(without, alone)
+
+
+@asynccontextmanager
+async def _style_sheet(page: Page, css: str) -> AsyncGenerator[None]:
+    """A style sheet on the page's own document for a moment: it reaches into neither frames nor shadow roots,
+    and adds nothing a page's observers can see."""
+    sheet = await page.evaluate_handle(_ADD_SHEET, css)
+    try:
+        yield
+    finally:
+        with suppress(PlaywrightError):
+            await sheet.evaluate(_TAKE_SHEET)
+        await sheet.dispose()
+
+
+def _png_size(png: bytes) -> tuple[int, int]:
+    """A PNG's width and height, from its header."""
+    return int.from_bytes(png[16:20]), int.from_bytes(png[20:24])
+
+
+async def _covers(page: Page, measured: _Measured) -> Covers:
+    """What is drawn over the elements. It moves the page for a moment, and forces a layout a page still
+    loading wouldn't have painted, which would read as a shift, so it only runs once a read has held."""
+    try:
+        return await check_covers(
+            page, [element.selector if element.visible else None for element in measured.elements]
+        )
+    except PlaywrightError as error:
+        if "navigat" in error.message:
+            raise
+        return Covers()
+
+
+async def keep_page(
+    page: PageRead,
+    *,
+    capture_id: str,
+    viewport: Viewport,
+    sink: BlobSink,
+    clock: Callable[[], datetime] = utc_now,
+    probe: EmptySubmit | None = None,
+) -> Capture:
+    """Store what was read, as a capture. ``probe`` is the empty submit that led to the page, if one did."""
+    read, covers, activity = page.read, page.covers, page.activity
+    measured = read.measured
+    eids = [f"{capture_id}:e{index}" for index in range(1, len(measured.elements) + 1)]
+    covered, overlaid = set(covers.covered), set(covers.overlaid)
+    elements = tuple(
+        ElementRef(
+            eid=eid,
+            role=raw.role,
+            name=raw.name,
+            tag=raw.tag,
+            text=raw.text,
+            selector=raw.selector,
+            box=raw.box,
+            visible=raw.visible,
+            fixed=raw.fixed,
+            past_edge=raw.pastEdge,
+            covered=raw.blank or index in covered,
+            overlaid=index in overlaid,
+            words_shown=raw.wordsShown,
+            attributes=raw.attributes,
+            form=eids[raw.form] if raw.form is not None else None,
+        )
+        for index, (eid, raw) in enumerate(zip(eids, measured.elements, strict=True))
+    )
+    return Capture(
+        id=capture_id,
+        url=read.url,
+        title=measured.title,
+        viewport=viewport,
+        viewport_size=page.size,
+        page_size=measured.pageSize,
+        captured_at=clock(),
+        screenshot=await sink.put(read.screenshot, "image/png"),
+        dom=await sink.put(read.dom.encode(), "text/html"),
+        aria=await sink.put(read.aria.encode(), "text/yaml"),
+        elements=elements,
+        vitals=activity.vitals if activity is not None else None,
+        network=activity.network if activity is not None else None,
+        console=activity.console if activity is not None else None,
+        axe=_axe_report(read.axe, eids) if read.axe is not None else None,
+        probe=_form_probe(probe, elements) if probe is not None else None,
+        settled=read.settled,
+        fixed_layer=await _fixed_layer(page.fixed_shots, measured.fixed, sink),
+    )
+
+
+async def _fixed_layer(
+    shots: _FixedShots | None, fixed: _MeasuredFixed | None, sink: BlobSink
+) -> FixedLayer | None:
+    if shots is None or fixed is None:
+        return None
+    return FixedLayer(
+        page=await sink.put(shots.page, "image/png"),
+        layer=await sink.put(shots.layer, "image/png"),
+        screen=fixed.screen,
+        solid=tuple(fixed.solid),
+    )
+
+
+def _axe_report(run: AxeRun, eids: list[str]) -> AxeReport:
+    return AxeReport(
+        version=run.version,
+        violations=tuple(
+            AxeViolation(
+                rule=found.rule,
+                impact=AxeImpact(found.impact) if found.impact is not None else None,
+                description=found.description,
+                help_url=found.helpUrl,
+                tags=tuple(found.tags),
+                nodes=found.nodes,
+                elements=tuple(eids[position] for position in found.elements),
+            )
+            for found in run.violations
+        ),
+    )
+
+
+def _form_probe(probe: EmptySubmit, elements: tuple[ElementRef, ...]) -> FormProbe:
+    """The probe in this capture's terms. A field the page no longer has keeps no message."""
+    by_selector = {element.selector: element.eid for element in reversed(elements)}
+    return FormProbe(
+        submitted_on=probe.capture_id,
+        form=by_selector.get(probe.form),
+        browser_messages=tuple(
+            FieldMessage(field=by_selector[selector], reason=reason, message=message[:300])
+            for selector, reason, message in probe.browser_messages
+            if selector in by_selector
+        ),
+    )