visus-web 0.1.0__py3-none-any.whl

visus/web/__init__.py

@@ -0,0 +1,64 @@
+"""visus.web — Playwright-style web automation on a Selenium engine."""
+
+from __future__ import annotations
+
+from visus.web import errors, tracing
+from visus.web.api.assertions import expect
+from visus.web.api.browser import Browser
+from visus.web.api.context import Context
+from visus.web.api.fields import Field
+from visus.web.api.page import Page
+from visus.web.backends.selenium_backend import SeleniumBackend
+from visus.web.config import Defaults
+from visus.web.engine import Engine
+from visus.web.registry import get_browser_config
+from visus.web.rpa import rpa
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "launch",
+    "rpa",
+    "expect",
+    "Engine",
+    "Browser",
+    "Context",
+    "Page",
+    "Field",
+    "errors",
+    "tracing",
+]
+
+
+def launch(
+    engine: Engine | str = Engine.CHROME,
+    *,
+    headless: bool = False,
+    slow_mo: int = 0,
+    user_data_dir: str | None = None,
+    remote_url: str | None = None,
+) -> Browser:
+    """Launch a browser and return a Browser handle.
+
+    *slow_mo* delays every action/navigation by the given milliseconds — handy
+    to watch a script drive the page in real time.
+
+    *user_data_dir* reuses (or creates) a persistent browser profile instead of
+    a throwaway temp profile — cookies, localStorage and logins survive across
+    runs. The directory is never deleted by visus.
+
+    *remote_url* opens the session on a Selenium Grid / Remote WebDriver
+    (e.g. ``"http://grid:4444/wd/hub"``) instead of spawning a local browser.
+
+    Usage:
+        with launch(headless=True) as browser:
+            page = browser.new_page()
+            page.goto("https://example.com")
+    """
+    resolved = Engine.from_str(engine)
+    config = get_browser_config(resolved)
+    backend = SeleniumBackend()
+    delegate = backend.launch(
+        config, headless=headless, user_data_dir=user_data_dir, remote_url=remote_url
+    )
+    return Browser(delegate, Defaults(slow_mo_ms=slow_mo))

visus/web/api/_htmlsel.py

@@ -0,0 +1,175 @@
+"""Build a resilient *smart* locator from a pasted DevTools element snippet.
+
+When a selector is an HTML element (e.g. copied via DevTools → "Copy element"),
+this derives an ordered list of candidate selectors — CSS-first, most-likely-unique
+first — that the engine tries in order until one matches.  Fault-tolerant: stale or
+non-matching candidates (an id that changed, a class that moved) are skipped, and a
+candidate that matches a *single* element is preferred over an ambiguous one.
+
+Example::
+
+    page.locator('<input name="query" aria-label="Search" class="md-search__input">')
+    # tries: input[name="query"] → [aria-label="Search"] → input.md-search__input → xpath…
+"""
+
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+
+_SIMPLE_IDENT = re.compile(r"^[A-Za-z_-][\w-]*$")
+_TEST_HOOKS = ("data-testid", "data-test", "data-test-id", "data-qa", "data-cy")
+
+
+class _FirstElement(HTMLParser):
+    """Capture the tag, attributes, and text of the first element in a snippet."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.tag: str | None = None
+        self.attrs: dict[str, str] = {}
+        self._depth = 0
+        self._text: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if self.tag is None:
+            self.tag = tag
+            self.attrs = {k: (v or "") for k, v in attrs}
+            self._depth = 1
+        elif self._depth > 0:
+            self._depth += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        if self._depth > 0:
+            self._depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self.tag is not None and self._depth >= 1:
+            self._text.append(data)
+
+    @property
+    def text(self) -> str:
+        return " ".join("".join(self._text).split())
+
+
+def parse(snippet: str) -> tuple[str | None, dict[str, str], str]:
+    """Return (tag, attrs, text) for the first element in *snippet*."""
+    p = _FirstElement()
+    p.feed(snippet)
+    return p.tag, p.attrs, p.text
+
+
+def _eq(value: str) -> str:
+    """Escape a value for a CSS ``[attr="value"]`` selector."""
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _css_ident_escape(ident: str) -> str:
+    """Escape a class/id identifier for use in a CSS selector.
+
+    Handles Tailwind-style classes such as ``file:border-0`` → ``file\\:border-0``
+    or ``pr-[88px]`` → ``pr-\\[88px\\]``. ``\\w`` is unicode-aware, so accented
+    class names stay intact; only ASCII punctuation is backslash-escaped.
+    """
+    return re.sub(r"([^\w-])", r"\\\1", ident)
+
+
+def _xq(value: str) -> str:
+    """Render *value* as an XPath string literal (handling embedded quotes)."""
+    if '"' not in value:
+        return f'"{value}"'
+    if "'" not in value:
+        return f"'{value}'"
+    parts = value.split('"')
+    return "concat(" + ", '\"', ".join(f'"{p}"' for p in parts) + ")"
+
+
+def candidates(tag: str, attrs: dict[str, str], text: str) -> list[dict[str, str]]:
+    """Ordered candidate selectors (CSS-first, most-likely-unique first)."""
+    out: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+
+    def add(kind: str, value: str) -> None:
+        key = (kind, value)
+        if value and key not in seen:
+            seen.add(key)
+            out.append({kind: value})
+
+    t = tag or "*"
+    classes = (attrs.get("class") or "").split()
+
+    if attrs.get("id"):
+        aid = attrs["id"]
+        add("css", f"#{aid}" if _SIMPLE_IDENT.match(aid) else f'[id="{_eq(aid)}"]')
+    for k in _TEST_HOOKS:
+        if attrs.get(k):
+            add("css", f'[{k}="{_eq(attrs[k])}"]')
+    if attrs.get("name"):
+        add("css", f'{t}[name="{_eq(attrs["name"])}"]')
+    for k, v in attrs.items():
+        if k.startswith("data-") and v and k not in _TEST_HOOKS:
+            add("css", f'{t}[{k}="{_eq(v)}"]')
+    if attrs.get("aria-label"):
+        add("css", f'[aria-label="{_eq(attrs["aria-label"])}"]')
+    if attrs.get("placeholder"):
+        add("css", f'[placeholder="{_eq(attrs["placeholder"])}"]')
+    if classes:
+        add("css", t + "".join("." + _css_ident_escape(c) for c in classes))
+    combined = _combined_css(t, attrs)
+    if combined:
+        add("css", combined)
+    if text:
+        add("xpath", f"//{t}[normalize-space()={_xq(text)}]")
+    for k in ("name", "aria-label", "placeholder"):
+        if attrs.get(k):
+            add("xpath", f"//{t}[@{k}={_xq(attrs[k])}]")
+    if attrs.get("class"):
+        add("xpath", f"//{t}[@class={_xq(attrs['class'])}]")
+    if not out:
+        add("css", t)
+    return out
+
+
+def _combined_css(tag: str, attrs: dict[str, str]) -> str:
+    """A tighter CSS selector combining a couple of identifying attributes."""
+    keys = [k for k in ("name", "type", "role", "href", "aria-label") if attrs.get(k)]
+    if len(keys) < 2:
+        return ""
+    return tag + "".join(f'[{k}="{_eq(attrs[k])}"]' for k in keys[:3])
+
+
+def smart_step(snippet: str) -> dict[str, object]:
+    """Parse a pasted element snippet into a ``smart`` locator step."""
+    tag, attrs, text = parse(snippet)
+    return {"kind": "smart", "tag": tag or "*", "candidates": candidates(tag or "*", attrs, text)}
+
+
+def translate(snippet: str) -> dict[str, object]:
+    """Translate a pasted DevTools element into id / css / xpath / class selectors.
+
+    Returns the recommended selector in each format plus the full ordered candidate
+    list (the same order the smart locator tries them in). Powers ``visus translate``
+    and the ``browser_translate_element`` MCP tool.
+    """
+    tag, attrs, text = parse(snippet)
+    t = tag or "*"
+    cands = candidates(t, attrs, text)
+    css = [c["css"] for c in cands if "css" in c]
+    xpath = [c["xpath"] for c in cands if "xpath" in c]
+    classes = (attrs.get("class") or "").split()
+    aid = attrs.get("id")
+    id_sel = None
+    if aid:
+        id_sel = f"#{aid}" if _SIMPLE_IDENT.match(aid) else f'[id="{_eq(aid)}"]'
+    class_sel = t + "".join("." + _css_ident_escape(c) for c in classes) if classes else None
+    return {
+        "tag": t,
+        "id": id_sel,
+        "name": attrs.get("name"),
+        "css": css[0] if css else None,
+        "xpath": xpath[0] if xpath else None,
+        "class": class_sel,
+        "classes": classes,
+        "candidates_css": css,
+        "candidates_xpath": xpath,
+    }

visus/web/api/_steps.py

@@ -0,0 +1,235 @@
+"""Backtrack helper for visus.web actions.
+
+run_step() executes an action and, on VisusWebError, optionally *backtracks*: it
+re-runs the last N successful steps (oldest→newest), then retries the failed step
+**once**.  ``backtrack`` is the depth — how many previous steps to replay before
+retrying:
+
+* ``False`` / ``0`` → disabled (the error propagates immediately)
+* ``True``          → replay 1 previous step (the default depth)
+* ``N``             → replay the last ``min(N, 3)`` steps
+
+Example — steps 1, 2, 3, 4 where step 4 fails:
+  ``backtrack=3`` re-runs 1, 2, 3 (in order) then retries 4;
+  ``backtrack=1`` re-runs 3 then retries 4.
+
+Backtrack is **not** a retry loop: the failed step is retried exactly once after
+the replay.  Each delegate carries a rolling history of its last 3 successful
+steps, so this behaves identically for the sync and async (to_thread) APIs.
+
+When tracing is active each step is timed and an event (+ highlighted screenshot)
+is emitted via the active Recorder — *including the replayed backtrack steps*,
+which appear in the report timeline as ``↻`` events.  With tracing OFF the
+behaviour is the same minus the recording overhead.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from visus.web import errors
+
+_log = logging.getLogger("visus.web")
+
+MAX_BACKTRACK = 3  # how many previous steps the engine remembers and can replay
+
+
+def _coerce_depth(backtrack: bool | int) -> int:
+    """Backtrack depth: False/0 → 0 (off), True → 1, N → min(N, MAX_BACKTRACK)."""
+    return max(0, min(int(backtrack), MAX_BACKTRACK))
+
+
+def _record_step(delegate: object, action: Callable[[], None]) -> None:
+    """Append a successful action to the delegate's rolling step history (last 3)."""
+    history: list[Callable[[], None]] | None = getattr(delegate, "_step_history", None)
+    if history is None:
+        history = []
+        delegate._step_history = history  # type: ignore[attr-defined]
+    history.append(action)
+    del history[:-MAX_BACKTRACK]  # keep only the most recent MAX_BACKTRACK steps
+
+
+def _replay_one(step: Callable[[], None], recorder: Any, delegate: object) -> None:
+    """Re-run a previous step during a backtrack.
+
+    When tracing, record it as a ``↻`` replay event (with a highlighted screenshot)
+    so the backtrack's replayed steps are visible in the report — using the metadata
+    tagged onto the action by :func:`run_step`.  A replay failure is recorded then
+    re-raised.
+    """
+    meta = getattr(step, "_visus_step", None)
+    if recorder is None or meta is None:
+        step()  # plain replay (no tracing, or an untagged history entry)
+        return
+    start = time.monotonic()
+    start_ts = time.time()
+    success = True
+    error: str | None = None
+    try:
+        step()
+    except errors.VisusWebError as exc:
+        success = False
+        error = str(exc)
+        raise
+    finally:
+        recorder.record_action(
+            delegate,
+            action="replay " + str(meta.get("name") or "step"),
+            selector=meta.get("selector"),
+            target=meta.get("target"),
+            start_ts=start_ts,
+            end_ts=time.time(),
+            duration_ms=int((time.monotonic() - start) * 1000),
+            success=success,
+            error=error,
+            backtrack_steps=0,
+        )
+
+
+def _execute(delegate: object, action: Callable[[], None], depth: int, recorder: Any = None) -> int:
+    """Run ``action`` once; backtrack on failure.
+
+    On :exc:`~visus.web.errors.VisusWebError`, if *depth* > 0, re-run the last
+    *depth* successful steps (oldest→newest) then retry ``action`` exactly once.
+    Each replayed step is recorded via *recorder* when tracing is active.  Returns
+    the number of steps replayed (0 when the action succeeded on the first try).
+    Records the action as a successful step on success; re-raises if it still fails
+    or if there is nothing to backtrack to.
+    """
+    try:
+        action()
+    except errors.VisusWebError:
+        history: list[Callable[[], None]] = list(getattr(delegate, "_step_history", None) or [])
+        replay = history[-depth:] if depth > 0 else []
+        if not replay:
+            raise  # backtrack disabled, or no previous step to return to
+        attempted = len(replay)
+        _log.info("backtrack: replaying %d previous step(s) before retry", attempted)
+        in_replay = True
+        try:
+            for step in replay:
+                _replay_one(step, recorder, delegate)  # re-run (and record) the previous step(s)
+            in_replay = False
+            action()  # then retry the failed step ONCE
+        except errors.VisusWebError as exc:
+            # A depth-N backtrack was attempted; tag it so the traced report records
+            # the backtrack even when a replayed step (or the retry) ultimately fails.
+            exc.backtrack_steps = attempted  # type: ignore[attr-defined]
+            if in_replay:
+                _log.warning("backtrack: a replayed step failed — the page may have moved on")
+            # `from None`: the first attempt and the retry are the same failure — don't
+            # chain them into a noisy "During handling of the above exception" traceback.
+            raise exc from None
+        _record_step(delegate, action)
+        return attempted
+    _record_step(delegate, action)
+    return 0
+
+
+def run_step(
+    delegate: object,
+    action: Callable[[], None],
+    backtrack: bool | int,
+    *,
+    action_name: str = "action",
+    selector: str | None = None,
+    target: str | None = None,
+    slow_mo_ms: int = 0,
+) -> None:
+    """Run ``action()`` with optional backtrack recovery.
+
+    On :exc:`~visus.web.errors.VisusWebError`, if *backtrack* is truthy, re-run
+    the last ``int(backtrack)`` (capped at 3) successful steps then retry
+    ``action`` once.  ``True`` → depth 1.  On success, record ``action`` as the
+    delegate's most recent successful step.
+
+    *action_name*, *selector*, and *target* are forwarded to the :class:`Recorder`
+    when tracing is active (and tagged onto *action* so a later backtrack replay of
+    this step can be recorded too); they are ignored on the fast path.
+    """
+    from visus.web import tracing
+
+    if slow_mo_ms > 0:
+        time.sleep(slow_mo_ms / 1000)
+
+    # Tag the action with its metadata so that, if a later step backtracks and
+    # replays this one, the replay can be recorded with the right label/screenshot.
+    action._visus_step = {  # type: ignore[attr-defined]
+        "name": action_name,
+        "selector": selector,
+        "target": target,
+    }
+
+    if not tracing.is_enabled() or tracing.current_recorder() is None:
+        _run_plain(delegate, action, backtrack)
+        return
+
+    _run_traced(
+        delegate,
+        action,
+        backtrack,
+        action_name=action_name,
+        selector=selector,
+        target=target,
+    )
+
+
+def _run_plain(delegate: object, action: Callable[[], None], backtrack: bool | int) -> None:
+    """Fast path: replay-then-retry backtrack with zero tracing overhead."""
+    _execute(delegate, action, _coerce_depth(backtrack))
+
+
+def _run_traced(
+    delegate: object,
+    action: Callable[[], None],
+    backtrack: bool | int,
+    *,
+    action_name: str,
+    selector: str | None,
+    target: str | None,
+) -> None:
+    """Traced path: same semantics as _run_plain but times the step and records an event."""
+    from visus.web import tracing
+
+    rec = tracing.current_recorder()
+    # rec should not be None here (caller checked), but guard defensively
+    if rec is None:
+        _run_plain(delegate, action, backtrack)
+        return
+
+    depth = _coerce_depth(backtrack)
+    start = time.monotonic()
+    start_ts = time.time()
+    steps_replayed = 0
+    error: str | None = None
+    success = False
+    label = target or selector or ""
+    _log.info("%s → %s", action_name, label)
+    try:
+        steps_replayed = _execute(delegate, action, depth, recorder=rec)
+        success = True
+    except errors.VisusWebError as exc:
+        error = str(exc)
+        steps_replayed = getattr(exc, "backtrack_steps", 0)  # backtrack tried but failed
+        raise
+    finally:
+        duration_ms = int((time.monotonic() - start) * 1000)
+        if success:
+            _log.info("%s ✓ (%dms, back %d step(s))", action_name, duration_ms, steps_replayed)
+        else:
+            _log.warning("%s ✗ %s", action_name, error or "")
+        rec.record_action(
+            delegate,
+            action=action_name,
+            selector=selector,
+            target=target,
+            start_ts=start_ts,
+            end_ts=time.time(),
+            duration_ms=duration_ms,
+            success=success,
+            error=error,
+            backtrack_steps=steps_replayed,
+        )