procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/web/steps.py

@@ -0,0 +1,162 @@
+"""Declarative step interpreter for the web tool's ``run`` action.
+
+A *step list* is a JSON array of step objects. Each step has a ``do`` key
+selecting the operation; the remaining keys are its parameters. The interpreter
+dispatches each step to one ``BrowserDriver`` call, collecting named outputs.
+
+Step schema (mini-language)
+---------------------------
+  {"do": "goto",         "url": "https://..."[, "timeout": ms]}
+  {"do": "click",        "selector": "css-or-text"[, "timeout": ms][, "force": true]}
+  {"do": "fill",         "selector": "...", "text": "..."[, "timeout": ms]}
+  {"do": "press",        "key": "Enter"[, "selector": "..."]}
+  {"do": "type",         "text": "...", "selector": "..."(optional)[, "timeout": ms]}
+  {"do": "wait",         "ms": 1500}
+  {"do": "wait_for",     "selector": "..."[, "timeout": ms]}
+  {"do": "extract_text", "selector": "..."(optional), "name": "field"[, "timeout": ms]}
+  {"do": "extract_attr", "selector": "...", "attr": "href", "name": "field"[, "timeout": ms]}
+  {"do": "viewport",     "width": 1920, "height": 1080}
+  {"do": "screenshot",   "path": "out.png"[, "full_page": true]}
+  {"do": "upload",       "selector": "input[type=file]", "path": "a.png" | ["a.png", ...][, "timeout": ms]}
+  {"do": "upload_via_chooser", "selector": "button.attach", "path": "a.png" | [...][, "timeout": ms]}
+
+``upload`` sets files on an ``<input type=file>`` directly (the input may be
+hidden - the standard Playwright way). ``upload_via_chooser`` is for a site whose
+real file input exists only transiently behind a NATIVE chooser: it clicks the
+trigger selector while expecting the chooser, then hands it the files. ``path``
+is a single path string or a list of paths.
+
+Return value
+------------
+``run_steps(driver, steps)`` returns
+    {"results": {name -> value}, "screenshots": [path, ...], "final_url": "..."}
+
+``extract_text`` / ``extract_attr`` write into ``results`` under their ``name``
+(falling back to the selector if no name is given). ``screenshot`` paths are
+collected into ``screenshots``.
+
+The interpreter validates each step *before* touching the driver, raising
+``UsageError`` (-> invalid_argument, exit 2) on a malformed step. This means a
+bad step list fails fast and identically whether or not a real browser exists.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from tools.web.errors import UsageError
+
+# do-name -> required keys (besides "do") and optional keys it understands.
+_SCHEMA: dict[str, dict[str, set[str]]] = {
+    "goto": {"required": {"url"}, "optional": {"timeout"}},
+    "click": {"required": {"selector"}, "optional": {"timeout", "force"}},
+    "fill": {"required": {"selector", "text"}, "optional": {"timeout"}},
+    "press": {"required": {"key"}, "optional": {"selector"}},
+    "type": {"required": {"text"}, "optional": {"selector", "timeout"}},
+    "wait": {"required": {"ms"}, "optional": set()},
+    "wait_for": {"required": {"selector"}, "optional": {"timeout"}},
+    "extract_text": {"required": set(), "optional": {"selector", "name", "timeout"}},
+    "extract_attr": {"required": {"selector", "attr"}, "optional": {"name", "timeout"}},
+    "eval": {"required": {"script"}, "optional": {"name", "arg"}},
+    "viewport": {"required": {"width", "height"}, "optional": set()},
+    "screenshot": {"required": {"path"}, "optional": {"full_page"}},
+    "upload": {"required": {"selector", "path"}, "optional": {"timeout"}},
+    "upload_via_chooser": {"required": {"selector", "path"}, "optional": {"timeout"}},
+}
+
+KNOWN_STEPS = frozenset(_SCHEMA)
+
+
+def _validate_step(i: int, step: Any) -> tuple[str, dict]:
+    if not isinstance(step, dict):
+        raise UsageError(f"step {i}: must be a JSON object, got {type(step).__name__}")
+    do = step.get("do")
+    if not do:
+        raise UsageError(f"step {i}: missing 'do' key")
+    if do not in _SCHEMA:
+        raise UsageError(
+            f"step {i}: unknown action {do!r}. Known: {', '.join(sorted(_SCHEMA))}"
+        )
+    spec = _SCHEMA[do]
+    keys = set(step) - {"do"}
+    missing = spec["required"] - keys
+    if missing:
+        raise UsageError(f"step {i} ({do}): missing required key(s): {', '.join(sorted(missing))}")
+    allowed = spec["required"] | spec["optional"]
+    extra = keys - allowed
+    if extra:
+        raise UsageError(f"step {i} ({do}): unknown key(s): {', '.join(sorted(extra))}")
+    return do, step
+
+
+def validate_steps(steps: Any) -> list[tuple[str, dict]]:
+    """Validate a whole step list without running it. Raises UsageError."""
+    if not isinstance(steps, list):
+        raise UsageError("steps must be a JSON array of step objects")
+    return [_validate_step(i, s) for i, s in enumerate(steps)]
+
+
+def _timeout(step: dict) -> int | None:
+    t = step.get("timeout")
+    return int(t) if t is not None else None
+
+
+def run_steps(driver, steps: Any) -> dict:
+    """Execute a validated step list against a BrowserDriver.
+
+    Returns {"results": {...}, "screenshots": [...], "final_url": "..."}.
+    """
+    validated = validate_steps(steps)
+    results: dict[str, Any] = {}
+    screenshots: list[str] = []
+
+    for do, step in validated:
+        if do == "goto":
+            driver.goto(step["url"], timeout=_timeout(step))
+        elif do == "click":
+            driver.click(step["selector"], timeout=_timeout(step),
+                         force=bool(step.get("force")))
+        elif do == "fill":
+            driver.fill(step["selector"], step["text"], timeout=_timeout(step))
+        elif do == "press":
+            driver.press(step["key"], selector=step.get("selector"))
+        elif do == "type":
+            driver.type_text(step["text"], selector=step.get("selector"),
+                             timeout=_timeout(step))
+        elif do == "wait":
+            driver.wait(int(step["ms"]))
+        elif do == "viewport":
+            driver.set_viewport(int(step["width"]), int(step["height"]))
+        elif do == "wait_for":
+            driver.wait_for(step["selector"], timeout=_timeout(step))
+        elif do == "extract_text":
+            name = step.get("name") or step.get("selector") or "text"
+            results[name] = driver.extract_text(
+                step.get("selector"), timeout=_timeout(step)
+            )
+        elif do == "extract_attr":
+            name = step.get("name") or f"{step['selector']}@{step['attr']}"
+            results[name] = driver.extract_attr(
+                step["selector"], step["attr"], timeout=_timeout(step)
+            )
+        elif do == "eval":
+            # evaluate JS in the page and collect the result — for verification asserts
+            # that need live DOM/JS state (e.g. an input's .value PROPERTY, which
+            # extract_attr cannot read). {"do":"eval","script":"...","name":"key"}
+            name = step.get("name") or "eval"
+            results[name] = driver.eval_js(step["script"], arg=step.get("arg"))
+        elif do == "screenshot":
+            path = driver.screenshot(
+                step["path"], full_page=bool(step.get("full_page", True))
+            )
+            screenshots.append(path)
+        elif do == "upload":
+            driver.set_input_files(step["selector"], step["path"], timeout=_timeout(step))
+        elif do == "upload_via_chooser":
+            driver.set_files_via_chooser(step["selector"], step["path"], timeout=_timeout(step))
+
+    out: dict[str, Any] = {"results": results, "screenshots": screenshots}
+    try:
+        out["final_url"] = driver.current_url()
+    except Exception:  # noqa: BLE001 - current_url is best-effort metadata
+        pass
+    return out

procesio_cli/tools/web/tests/conftest.py

@@ -0,0 +1,197 @@
+"""Pytest fixtures + sys.path for the web tool.
+
+FakeDriver records every BrowserDriver call (method + args) and returns canned
+values for the extract_* / current_url reads. Tests inject it everywhere a real
+browser would be used, so the suite is fully hermetic - ZERO real browser, and
+it runs even when Playwright's browser binaries are not installed.
+
+The ``isolated_sessions`` fixture redirects ``tools.web.sessions.SESSIONS_DIR``
+to a temp directory so session read/write/list/delete tests never touch the real
+sessions folder.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+FRAMEWORK_ROOT = Path(__file__).resolve().parents[3]
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+
+class FakeDriver:
+    """A BrowserDriver test double.
+
+    Records calls in ``self.calls`` as (method, kwargs) tuples. Read methods
+    return values from ``self.texts`` / ``self.attrs`` / ``self.url`` so tests
+    can assert on the interpreter's collected results. ``storage_state()``
+    returns ``self.state`` (used by save-session tests).
+    """
+
+    def __init__(self, *, storage_state=None, headless=True, channel=None,
+                 user_data_dir=None, texts=None, attrs=None, htmls=None, evals=None,
+                 extra_args=None, url="https://example.com/after"):
+        self.init = {"storage_state": storage_state, "headless": headless,
+                     "channel": channel, "user_data_dir": user_data_dir,
+                     "extra_args": list(extra_args or [])}
+        self.calls: list[tuple[str, dict]] = []
+        self.texts = texts or {}          # selector(or None) -> text
+        self.attrs = attrs or {}          # (selector, attr) -> value
+        self.htmls = htmls or {}          # selector -> innerHTML
+        self.evals = evals or {}          # script -> result
+        self.url = url
+        self.started = False
+        self.closed = False
+        # what storage_state() returns after an interactive capture
+        self.state = {"cookies": [{"name": "sid", "value": "abc"}], "origins": []}
+        # what get_cookies() returns (incl. session-scoped); add_cookies records here
+        self.cookies = [{"name": "sid", "value": "abc", "domain": ".example.com",
+                         "path": "/", "expires": -1}]
+        self.injected_cookies: list[dict] = []
+
+    # lifecycle
+    def start(self):
+        self.started = True
+        self.calls.append(("start", {}))
+        return self
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, *_exc):
+        self.close()
+
+    def close(self):
+        self.closed = True
+        self.calls.append(("close", {}))
+
+    def storage_state(self):
+        self.calls.append(("storage_state", {}))
+        return self.state
+
+    # surface
+    def goto(self, url, *, timeout=None):
+        self.calls.append(("goto", {"url": url, "timeout": timeout}))
+
+    def click(self, selector, *, timeout=None, force=False):
+        self.calls.append(("click", {"selector": selector, "timeout": timeout,
+                                     "force": force}))
+
+    def hover(self, selector, *, timeout=None):
+        self.calls.append(("hover", {"selector": selector, "timeout": timeout}))
+
+    def context_click(self, selector, *, timeout=None):
+        self.calls.append(("context_click", {"selector": selector, "timeout": timeout}))
+
+    def fill(self, selector, text, *, timeout=None):
+        self.calls.append(("fill", {"selector": selector, "text": text, "timeout": timeout}))
+
+    def press(self, key, *, selector=None):
+        self.calls.append(("press", {"key": key, "selector": selector}))
+
+    def type_text(self, text, *, selector=None, timeout=None):
+        self.calls.append(("type_text", {"text": text, "selector": selector, "timeout": timeout}))
+
+    def wait(self, ms):
+        self.calls.append(("wait", {"ms": ms}))
+
+    def set_viewport(self, width, height):
+        self.calls.append(("set_viewport", {"width": width, "height": height}))
+
+    def wait_for(self, selector, *, timeout=None):
+        self.calls.append(("wait_for", {"selector": selector, "timeout": timeout}))
+
+    def extract_text(self, selector=None, *, timeout=None):
+        self.calls.append(("extract_text", {"selector": selector, "timeout": timeout}))
+        return self.texts.get(selector, f"text:{selector}")
+
+    def extract_attr(self, selector, attr, *, timeout=None):
+        self.calls.append(("extract_attr", {"selector": selector, "attr": attr, "timeout": timeout}))
+        return self.attrs.get((selector, attr), f"attr:{selector}:{attr}")
+
+    def inner_html(self, selector, *, timeout=None):
+        self.calls.append(("inner_html", {"selector": selector, "timeout": timeout}))
+        return self.htmls.get(selector, f"<i>html:{selector}</i>")
+
+    def eval_js(self, script, *, arg=None):
+        self.calls.append(("eval_js", {"script": script, "arg": arg}))
+        return self.evals.get(script)
+
+    def set_input_files(self, selector, files, *, timeout=None):
+        self.calls.append(("set_input_files", {"selector": selector, "files": files, "timeout": timeout}))
+
+    def set_files_via_chooser(self, trigger_selector, files, *, timeout=None):
+        self.calls.append(("set_files_via_chooser",
+                           {"selector": trigger_selector, "files": files, "timeout": timeout}))
+
+    def screenshot(self, path, *, full_page=True):
+        self.calls.append(("screenshot", {"path": path, "full_page": full_page}))
+        return path
+
+    def render_pdf(self, html, path, *, fmt="A4", width=None, height=None, margin=None):
+        self.calls.append(("render_pdf", {"html": html, "path": path, "fmt": fmt,
+                                          "width": width, "height": height, "margin": margin}))
+        # Write a minimal stub so callers that stat the output see bytes.
+        with open(path, "wb") as fh:
+            fh.write(b"%PDF-1.4 fake\n")
+        return path
+
+    def current_url(self):
+        self.calls.append(("current_url", {}))
+        return self.url
+
+    def get_cookies(self):
+        self.calls.append(("get_cookies", {}))
+        return list(self.cookies)
+
+    def add_cookies(self, cookies):
+        self.calls.append(("add_cookies", {"cookies": cookies}))
+        self.injected_cookies.extend(cookies or [])
+
+    # convenience for assertions
+    def methods(self):
+        return [m for m, _ in self.calls]
+
+
+@pytest.fixture
+def fake_driver():
+    return FakeDriver()
+
+
+@pytest.fixture
+def driver_factory():
+    """Returns (factory, holder). factory(**kwargs) builds a FakeDriver and
+    appends it to holder so tests can inspect what was built/called."""
+    built: list[FakeDriver] = []
+
+    def factory(*, storage_state=None, headless=True, channel=None, user_data_dir=None,
+                extra_args=None):
+        d = FakeDriver(storage_state=storage_state, headless=headless,
+                       channel=channel, user_data_dir=user_data_dir, extra_args=extra_args)
+        built.append(d)
+        return d
+
+    factory.built = built  # type: ignore[attr-defined]
+    return factory
+
+
+@pytest.fixture
+def isolated_sessions(tmp_path, monkeypatch):
+    """Point the sessions module at a temp dir for the duration of a test."""
+    from tools.web import sessions
+
+    d = tmp_path / "sessions"
+    d.mkdir()
+    monkeypatch.setattr(sessions, "SESSIONS_DIR", d)
+    return d
+
+
+@pytest.fixture(autouse=True)
+def _no_broker_routing(monkeypatch):
+    """Default every test to the in-process path: a test targeting an OWNED
+    session name (whatsapp/ryver/fgo/mirro) must never talk to — or spawn — a
+    real serializing broker. Routing tests delete these selectively."""
+    for env in ("WHATSAPP_DIRECT", "RYVER_WEB_DIRECT", "FGO_WEB_DIRECT", "MIRRO_DIRECT"):
+        monkeypatch.setenv(env, "1")