@capagents/forgeqe 1.3.2 → 2.0.0

package/py/forgeqe_desktop/replay.py

@@ -0,0 +1,345 @@
+"""
+Replay a desktop workflow without a model.
+
+Steps run in order on a ``Driver`` and the run stops at the first failure. When a step's control is not found and a
+``heal`` callback is given, it may propose a new target once; the step is retried with it and the proposal is
+returned for review, never written into the workflow here.
+
+A step waits up to its ``timeout`` for its control, closing any ``dismiss`` dialog that is in the way, and is tried
+again up to ``retries`` times; ``expect_image`` hands what it captured to ``compare_image``.
+
+``{{secret:NAME}}`` is filled only for names the caller allows (``forgeqe.yaml`` ``desktop.secrets``), so a workflow
+cannot ask for ForgeQE's own keys or any other variable in the environment.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Protocol
+
+from .apps import AppSpec, resolve_app
+from .workflow import MOBILE_FORMAT, MOBILE_RETRY_OPS, RETRY_OPS, WorkflowError, env_secret, fill, fill_targets, parse_chord, secret_names, validate
+
+
+class ControlNotFound(LookupError):
+    """No control in the app's windows matches a step's target."""
+
+
+class Driver(Protocol):
+    def launch(self, app: AppSpec) -> None: ...
+    def find(self, target: Mapping[str, Any], timeout: float) -> Any: ...
+    def click(self, control: Any, double: bool = False) -> None: ...
+    def type_text(self, control: Any, text: str) -> None: ...
+    def select(self, control: Any, value: str) -> None: ...
+    def press(self, chord: List[str]) -> None: ...
+    def text_of(self, control: Any) -> str: ...
+    def close(self) -> None: ...
+
+
+@dataclass
+class StepResult:
+    index: int
+    op: str
+    ok: bool
+    ms: int
+    error: str = ""
+    healed_target: Optional[Dict[str, Any]] = None
+    attempts: int = 1
+    # Labels of the dialogs dismissed while this step ran.
+    dismissed: List[str] = field(default_factory=list)
+    # expect_image: the files written for the step (baseline, actual, diff) and how much differed.
+    images: Optional[Dict[str, Any]] = None
+    note: str = ""
+
+
+@dataclass
+class ReplayResult:
+    ok: bool
+    steps: List[StepResult] = field(default_factory=list)
+    stopped: bool = False
+
+    @property
+    def healed(self) -> List[StepResult]:
+        return [s for s in self.steps if s.healed_target is not None]
+
+
+Heal = Callable[[int, Dict[str, Any], str], Optional[Dict[str, Any]]]
+# expect_image: (step index, the step, the PNG captured now) -> (ok, message, images) from the caller, which owns the
+# baselines folder and the run folder.
+CompareImage = Callable[[int, Mapping[str, Any], bytes], "tuple[bool, str, Dict[str, Any]]"]
+
+POLL_SECONDS = 0.25
+MAX_DISMISS_ROUNDS = 3
+MAX_SCROLLS = 15
+
+
+def _label(target: Mapping[str, Any]) -> str:
+    return str(target.get("name") or target.get("automation_id") or "")
+
+
+def replay(
+    workflow: Mapping[str, Any],
+    driver: Driver,
+    apps: Mapping[str, AppSpec],
+    variables: Optional[Mapping[str, Any]] = None,
+    allowed_secrets: Iterable[str] = (),
+    secret: Callable[[str], Optional[str]] = env_secret,
+    heal: Optional[Heal] = None,
+    find_timeout: float = 10.0,
+    sleep: Callable[[float], None] = time.sleep,
+    must_exist: bool = True,
+    on_step: Optional[Callable[[StepResult], None]] = None,
+    should_stop: Callable[[], bool] = lambda: False,
+    compare_image: Optional[CompareImage] = None,
+    clock: Callable[[], float] = time.time,
+) -> ReplayResult:
+    wf = validate(dict(workflow))
+    spec = resolve_app(wf["app"], apps, must_exist=must_exist)
+    allowed = {str(n) for n in allowed_secrets}
+    values: Dict[str, Any] = {**wf["variables"], **dict(variables or {})}
+    wf = fill_targets(wf, values)
+
+    def allowed_secret(name: str) -> Optional[str]:
+        if name not in allowed:
+            raise WorkflowError(f"secret {name} is not listed in forgeqe.yaml desktop.secrets")
+        return secret(name)
+
+    # Every placeholder is checked before the app starts, so a bad workflow fails without touching the desktop.
+    for step in wf["steps"]:
+        for k in ("text", "value"):
+            if k in step:
+                for name in secret_names(step[k]):
+                    if name not in allowed:
+                        raise WorkflowError(f"secret {name} is not listed in forgeqe.yaml desktop.secrets")
+        if step["op"] == "expect_image" and compare_image is None:
+            raise WorkflowError("this workflow has expect_image steps, and this replay has nowhere to keep baseline images")
+
+    runner = _Runner(driver, spec, values, allowed_secret, wf.get("timeout", find_timeout), wf.get("dismiss") or [], sleep, clock, compare_image)
+    runner.mobile = wf["format"] == MOBILE_FORMAT
+    retry_ops = MOBILE_RETRY_OPS if runner.mobile else RETRY_OPS
+    default_retries = int(wf.get("retries", 0))
+    result = ReplayResult(ok=True)
+    try:
+        for i, step in enumerate(wf["steps"], 1):
+            if should_stop():
+                result.ok, result.stopped = False, True
+                break
+            started = clock()
+            op = step["op"]
+            res = StepResult(index=i, op=op, ok=True, ms=0)
+            runner.res = res
+            tries = 1 + (int(step.get("retries", default_retries)) if op in retry_ops else 0)
+            error: Optional[Exception] = None
+            for attempt in range(1, tries + 1):
+                res.attempts = attempt
+                try:
+                    runner.run(i, step)
+                    error = None
+                    break
+                except WorkflowError as e:
+                    # A workflow that cannot run as written does not get better by trying again.
+                    error = e
+                    break
+                except Exception as e:
+                    error = e
+                    if attempt < tries:
+                        sleep(min(1.0 * attempt, 5.0))
+                        runner.dismiss_dialogs()
+            if isinstance(error, ControlNotFound) and "target" in step:
+                proposal = heal(i, dict(step["target"]), str(error)) if heal else None
+                if proposal is not None:
+                    try:
+                        # The proposal is checked like any target, then tried once.
+                        healed = validate({**wf, "steps": [{**step, "target": proposal}]})["steps"][0]
+                        runner.run(i, healed)
+                        res.healed_target = healed["target"]
+                        error = None
+                    except Exception as e2:
+                        error = ControlNotFound(f"{error}; the healed target failed too: {e2}")
+            if error is not None:
+                res.ok, res.error = False, str(error) + (f" (after {res.attempts} tries)" if res.attempts > 1 else "")
+            res.ms = int((clock() - started) * 1000)
+            result.steps.append(res)
+            if on_step is not None:
+                on_step(res)
+            if not res.ok:
+                result.ok = False
+                break
+    finally:
+        if not result.ok or not wf["steps"] or wf["steps"][-1]["op"] != "close":
+            try:
+                driver.close()
+            except Exception:
+                pass
+    return result
+
+
+class _Runner:
+    def __init__(
+        self,
+        driver: Driver,
+        spec: AppSpec,
+        values: Mapping[str, Any],
+        secret: Callable[[str], Optional[str]],
+        timeout: float,
+        dismiss: List[Mapping[str, Any]],
+        sleep: Callable[[float], None],
+        clock: Callable[[], float],
+        compare_image: Optional[CompareImage],
+    ) -> None:
+        self.driver, self.spec, self.values, self.secret = driver, spec, values, secret
+        self.timeout, self.dismiss, self.sleep, self.clock, self.compare_image = timeout, dismiss, sleep, clock, compare_image
+        self.res = StepResult(index=0, op="", ok=True, ms=0)
+        self.mobile = False
+
+    def dismiss_dialogs(self) -> bool:
+        """Click every ``dismiss`` control that is on screen now; whether any was."""
+        clicked = False
+        for target in self.dismiss:
+            try:
+                control = self.driver.find(target, 0)
+            except ControlNotFound:
+                continue
+            except Exception:
+                continue
+            try:
+                self.driver.click(control)
+                self.res.dismissed.append(_label(target))
+                clicked = True
+            except Exception:
+                pass
+        return clicked
+
+    def find(self, target: Mapping[str, Any], timeout: float, ready: bool = False) -> Any:
+        """The control, waiting up to ``timeout``; a dialog in ``dismiss`` that hides it is closed and the search goes on."""
+        rounds = 0
+        while True:
+            started = self.clock()
+            try:
+                control = self.driver.find(target, timeout)
+                wait_ready = getattr(self.driver, "wait_ready", None)
+                if ready and wait_ready is not None:
+                    wait_ready(control, max(0.0, timeout - (self.clock() - started)))
+                return control
+            except ControlNotFound:
+                # A dialog was in the way: close it and look again, a few times at most (a dialog that keeps coming
+                # back is a failure to see in the report, not a loop).
+                if rounds < MAX_DISMISS_ROUNDS and self.dismiss and self.dismiss_dialogs():
+                    rounds += 1
+                    continue
+                raise
+
+    def run(self, index: int, step: Mapping[str, Any]) -> None:
+        op = step["op"]
+        timeout = float(step.get("timeout", self.timeout))
+        driver = self.driver
+        if op == "launch":
+            if "timeout" in step:
+                driver.launch(self.spec, timeout=timeout)  # type: ignore[call-arg]
+            else:
+                driver.launch(self.spec)
+        elif op == "close":
+            driver.close()
+        elif op == "wait":
+            self.sleep(float(step["seconds"]))
+        elif op == "keys" and self.mobile:
+            driver.press_key(step["keys"])  # type: ignore[attr-defined]
+        elif op == "keys":
+            driver.press(parse_chord(step["keys"]))
+        elif op == "back":
+            driver.back()  # type: ignore[attr-defined]
+        elif op == "hide_keyboard":
+            driver.hide_keyboard()  # type: ignore[attr-defined]
+        elif op == "swipe":
+            control = self.find(step["target"], timeout) if "target" in step else None
+            driver.swipe(step["direction"], control)  # type: ignore[attr-defined]
+        elif op == "scroll_to":
+            self._scroll_to(step, timeout)
+        elif op in ("tap", "double_tap"):
+            driver.click(self.find(step["target"], timeout, ready=True), double=op == "double_tap")
+        elif op == "long_press":
+            driver.long_press(self.find(step["target"], timeout, ready=True))  # type: ignore[attr-defined]
+        elif op == "wait_for":
+            self._wait_for(step, timeout)
+        elif op == "expect_image":
+            self._expect_image(index, step, timeout)
+        else:
+            control = self.find(step["target"], timeout, ready=op in ("click", "double_click", "type", "select"))
+            if op in ("click", "double_click"):
+                driver.click(control, double=op == "double_click")
+            elif op == "type":
+                driver.type_text(control, fill(step["text"], self.values, self.secret))
+            elif op == "select":
+                driver.select(control, fill(step["value"], self.values, self.secret))
+            elif op == "expect" and "text" in step:
+                want = fill(step["text"], self.values, self.secret)
+                got = driver.text_of(control)
+                if want not in got:
+                    if secret_names(step["text"]):
+                        raise AssertionError("the control's text does not contain the expected value (it holds a secret, so it is not shown)")
+                    raise AssertionError(f"expected {want!r} in the control's text, found {got!r}")
+
+    def _scroll_to(self, step: Mapping[str, Any], timeout: float) -> None:
+        """Scroll (default: down the page) until the target is on screen, up to the timeout or MAX_SCROLLS."""
+        direction = step.get("direction", "down")
+        deadline = self.clock() + timeout
+        for _ in range(MAX_SCROLLS):
+            try:
+                self.driver.find(step["target"], 0)
+                return
+            except ControlNotFound:
+                pass
+            if self.clock() >= deadline:
+                break
+            self.driver.scroll(direction)  # type: ignore[attr-defined]
+            self.sleep(POLL_SECONDS)
+        self.driver.find(step["target"], 0)
+
+    def _wait_for(self, step: Mapping[str, Any], timeout: float) -> None:
+        target = step["target"]
+        deadline = self.clock() + timeout
+        if step.get("gone"):
+            while True:
+                try:
+                    self.driver.find(target, 0)
+                except ControlNotFound:
+                    return
+                if self.clock() >= deadline:
+                    raise AssertionError(f"{_label(target)!r} was still there after {timeout:g} s")
+                # A dialog ("Save changes?") can be what keeps it there.
+                self.dismiss_dialogs()
+                self.sleep(POLL_SECONDS)
+        control = self.find(target, timeout)
+        if "text" not in step:
+            return
+        want = fill(step["text"], self.values, self.secret)
+        while True:
+            try:
+                got = self.driver.text_of(control)
+            except Exception:
+                got = ""
+            if want in got:
+                return
+            if self.clock() >= deadline:
+                if secret_names(step["text"]):
+                    raise AssertionError(f"the control did not show the expected value within {timeout:g} s (it holds a secret, so it is not shown)")
+                raise AssertionError(f"expected {want!r} in the control's text within {timeout:g} s, found {got!r}")
+            self.sleep(POLL_SECONDS)
+            try:
+                control = self.driver.find(target, 0)
+            except ControlNotFound:
+                pass
+
+    def _expect_image(self, index: int, step: Mapping[str, Any], timeout: float) -> None:
+        capture = getattr(self.driver, "image_png", None)
+        if capture is None or self.compare_image is None:
+            raise WorkflowError("this driver cannot capture images for expect_image")
+        control = self.find(step["target"], timeout) if "target" in step else None
+        png = capture(control)
+        if not png:
+            raise AssertionError("the control could not be captured (is the window minimised, or the screen locked?)")
+        ok, message, images = self.compare_image(index, step, png)
+        self.res.images = images
+        self.res.note = message if ok else ""
+        if not ok:
+            raise AssertionError(message)