@capagents/forgeqe 2.2.1 → 2.2.3

package/py/forgeqe_engine/service.py

@@ -46,11 +46,18 @@ from .llm import (
     _agent_usage,
 )
 from .browser import (
+    VIDEO_FILE,
     FreshTabAfterPassword,
     browser_connection_label,
     browser_launch_kwargs,
     local_browser_launch_kwargs,
+    maximize_window,
     settle_page,
+    start_video,
+    stop_video,
+    video_available,
+    wants_maximized,
+    window_launch_kwargs,
     _shutdown_browser_instance,
     _stop_agent_instance,
     browser_profile,
@@ -1004,6 +1011,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
     browser_provider = str(browser_cfg.get("provider") or "local")
     browser_remote = browser_cfg.get("remote") if isinstance(browser_cfg.get("remote"), dict) else {}
     browser_kw = browser_launch_kwargs(provider=browser_provider, remote=browser_remote, headless=headless)
+    browser_kw.update(window_launch_kwargs(browser_cfg, headless=headless))
     if allowed_domains is not None:
         browser_kw["allowed_domains"] = allowed_domains
     logins = parse_logins(req.logins)
@@ -1142,6 +1150,21 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                 shared = mem.store.shared_start(goal, normalized_initial)
                 if shared:
                     flow, kind = shared, "shared"
+        maximize = wants_maximized(browser_cfg, headless=headless)
+        video = browser_cfg.get("video") is True
+        if video and not video_available():
+            emit({"type": "log", "level": "warn", "text": "No video for this run: the engine's video packages are missing. Run: forgeqe setup"})
+            video = False
+        if maximize or video:
+            # Started before the agent so the window is maximised, and the video sized, before the first page opens.
+            try:
+                await browser.start()
+                if maximize and not await maximize_window(browser):
+                    emit({"type": "log", "level": "debug", "text": "The browser window could not be maximised"})
+                if video and await start_video(browser, out_dir) is None:
+                    emit({"type": "log", "level": "warn", "text": "No video for this run: recording did not start"})
+            except Exception as ex:
+                logger.debug("early browser start failed: %s", ex)
         if flow and kind and flow.get("steps"):
             if kind == "interrupted":
                 replay_text = (
@@ -1668,6 +1691,8 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
             await _save_logins()
         if overlay is not None:
             overlay.close()
+        if await stop_video(browser):
+            emit({"type": "log", "level": "info", "text": "Video saved: video.mp4"})
         await _shutdown_browser_instance(browser)
 
 
@@ -1694,5 +1719,9 @@ async def run_with_events(req: RunRequest, emit: Emit, cancel_event: asyncio.Eve
         except Exception as ex:
             logger.warning("artifact write failed: %s", ex)
             out["files"] = []
+    # The video is finished when the browser closes, after the other files were written.
+    video = Path(req.out_dir) / VIDEO_FILE
+    if video.is_file() and str(video) not in out["files"]:
+        out["files"].append(str(video))
     emit({"type": "done", "result": {k: v for k, v in out.items() if k != "step_events"}})
     return out

package/py/forgeqe_engine/webrecord.py

@@ -0,0 +1,589 @@
+"""
+Recording a web test by hand: the tester does the steps in the browser once, and ForgeQE writes them as the steps of a
+run (workflow.yaml), in the same shape as the browser agent's, so the replay check and the coding agent take them as
+they are.
+
+This module turns what the tester did into steps; ``recordsession.py`` watches the browser and feeds it. What is recorded:
+
+- a click on a control → ``click`` (two on the same control → ``dblclick``). A click on an item of a menu that opened
+  when the pointer went over its trigger gets a ``hover`` on the trigger first;
+- text typed into a field → one ``input`` step with the field's final text, when the tester moves on; a click into that
+  field just before is dropped. A password field, or text equal to a saved login's value, is written as ``text_env``:
+  the typed characters of a password never reach this module;
+- a choice in a drop-down → ``select`` (the click that opened it is part of the select);
+- Enter and Escape, arrows in an autocomplete field, and key chords outside a text field → ``press``;
+- a page the tester opened by hand → ``navigate``; going back → ``back``. Pages opened by a click, a key, or a form are
+  part of that step;
+- the tester's checks → ``expect``; values kept for later steps → ``capture`` (text typed later that equals a kept
+  value is written as ``{{name}}``); a wait for an element → ``wait_for``; notes → ``note`` on the step before.
+
+Uploads and drag and drop are not recorded; the result lists them.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
+from urllib.parse import urlparse
+
+from . import dynamic
+from .memory import FLOW_STEP_LOCATORS, TEST_ID_ATTRS, element_label, looks_generated, page_id
+
+FORMAT_SOURCE = "recorded"
+# A page that loads this soon after a click, a key, or a typed value came from it, not from the address bar (for a
+# navigation the browser did not report as the page's own).
+NAV_CAUSED_SECONDS = 1.5
+DOUBLE_CLICK_SECONDS = 0.5
+MAX_TEXT = 200
+EXPECT_KINDS = ("text", "visible", "hidden", "value", "checked", "url", "title", "intent")
+# Keys recorded inside a text field; any other key there is typing.
+FIELD_KEYS = ("Enter", "Escape")
+AUTOCOMPLETE_KEYS = ("ArrowDown", "ArrowUp")
+_NAME = re.compile(r"[^a-z0-9_]+")
+# Files never recorded for an upload, as ForgeQE's attachments refuse them (src/mcp/attachtools.ts): credentials and keys.
+SECRET_FILE = re.compile(r"^(?:forgeqe\.ya?ml|credentials\.json|auth\.json|llms\.json|id_(?:rsa|dsa|ecdsa|ed25519)|.*\.(?:pem|key|pfx|p12|kdbx))$", re.I)
+
+
+def upload_path(path: str, work_dir: str) -> Tuple[Optional[str], str]:
+    """
+    (path relative to the working folder, "") for a file the tester chose that a test may use, or (None, why not): it
+    must be inside the working folder, outside its hidden files and folders, and not named like a file of credentials.
+    """
+    if not path or not work_dir:
+        return None, "the file's path is not known"
+    real, work = os.path.realpath(path), os.path.realpath(work_dir)
+    rel = os.path.relpath(real, work)
+    if rel == os.pardir or rel.startswith(os.pardir + os.sep) or os.path.isabs(rel):
+        return None, f"{os.path.basename(real)} is outside the working folder; put it in the repository's test data and record again"
+    if any(part.startswith(".") for part in rel.split(os.sep)):
+        return None, f"{os.path.basename(real)} is in a hidden folder or is a hidden file, which can hold secrets"
+    if SECRET_FILE.match(os.path.basename(real)):
+        return None, f"{os.path.basename(real)} is named like a file of credentials or keys"
+    return rel.replace(os.sep, "/"), ""
+_ENV = re.compile(r"[^A-Z0-9_]+")
+
+
+def _clip(text: Any, n: int = MAX_TEXT) -> str:
+    return " ".join(str(text or "").split())[:n]
+
+
+def var_name(text: str, taken: Any = ()) -> str:
+    """A variable name from a label: "Order number" → order_number; numbered when taken."""
+    base = _NAME.sub("_", (text or "").lower()).strip("_")[:30] or "value"
+    if base[0].isdigit():
+        base = f"v_{base}"
+    name, n = base, 2
+    while name in taken:
+        name, n = f"{base}_{n}", n + 1
+    return name
+
+
+def secret_env_for(host: str) -> str:
+    """The variable a recorded password is read from when no saved login names one: shop.example.com → SHOP_EXAMPLE_COM_PASSWORD."""
+    base = _ENV.sub("_", (host or "SITE").upper()).strip("_") or "SITE"
+    if base.startswith("WWW_"):
+        base = base[4:]
+    # A shell variable cannot start with a digit (127.0.0.1).
+    if base[0].isdigit():
+        base = f"SITE_{base}"
+    return f"{base}_PASSWORD"
+
+
+@dataclass
+class Target:
+    """An element the tester acted on: the page it was on, its facts, and its locators (verified on the live page first)."""
+
+    url: str
+    facts: Dict[str, Any]
+    locators: List[Dict[str, Any]]
+
+    @property
+    def tag(self) -> str:
+        return str(self.facts.get("tag") or "").lower()
+
+    @property
+    def input_type(self) -> str:
+        return str((self.facts.get("attributes") or {}).get("type") or "").lower()
+
+    @property
+    def key(self) -> Tuple[str, str]:
+        """What makes two targets the same element: the page and its best locator."""
+        best = self.locators[0] if self.locators else {}
+        return (page_id(self.url) or self.url, f"{best.get('type')}:{best.get('value')}")
+
+
+def element_step(op: str, t: Target) -> Dict[str, Any]:
+    """A step on an element, as memory.compact_step writes the browser agent's."""
+    locs = t.locators[:FLOW_STEP_LOCATORS]
+    f = t.facts
+    return {
+        "op": op,
+        "page": page_id(t.url) or t.url,
+        "label": _clip(element_label(f), 120),
+        "best_locator": locs[0].get("playwright") if locs else None,
+        "locators": [
+            {"type": l["type"], "value": l["value"], "confidence": l.get("confidence"), **{k: l[k] for k in ("css", "attr", "verified") if l.get(k)}}
+            for l in locs
+            if l.get("type") and l.get("value")
+        ],
+        "locator": {k: v for k, v in {"tag": (f.get("tag") or "").upper(), "role": f.get("role"), "name": f.get("name")}.items() if v},
+    }
+
+
+def describe(step: Dict[str, Any]) -> str:
+    """One line for the step list in the Recorder and the terminal."""
+    op = step.get("op") or ""
+    label = step.get("label") or (step.get("locator") or {}).get("name") or "element"
+    if op == "navigate":
+        return f"open {step.get('url')}"
+    if op in ("click", "dblclick", "hover"):
+        return f"{'double-click' if op == 'dblclick' else op} {label}"
+    if op == "input":
+        if step.get("text_env"):
+            return f"type ${step['text_env']} into {label}"
+        if step.get("generated") == "date":
+            return f"type a date {step.get('text')} into {label} ({step.get('example')!r} today)"
+        if step.get("generated") == "unique":
+            return f"type {step.get('text')!r} into {label}, new on each run ({step.get('example')!r} this time)"
+        return f"type {step.get('text')!r} into {label}" + (f" (test data: {step['param']})" if step.get("param") else "")
+    if op == "select":
+        return f"choose {step.get('text')!r} in {label}"
+    if op == "press":
+        return f"press {step.get('keys')}"
+    if op == "back":
+        return "go back"
+    if op == "wait_for":
+        return f"wait for {label}"
+    if op == "upload":
+        return f"upload {', '.join(step.get('files') or [])} into {label}"
+    if op == "capture":
+        return f"keep {label} as {{{{{step.get('name')}}}}}"
+    if op == "expect":
+        kind = step.get("kind")
+        if kind == "intent":
+            return f"check: {step.get('expected')} (to be resolved)"
+        if kind in ("url", "title"):
+            return f"check the page {kind} contains {step.get('text')!r}"
+        if kind in ("visible", "hidden"):
+            return f"check {label} is {kind}"
+        if kind == "checked":
+            return f"check {label} is {'checked' if step.get('text') != 'false' else 'not checked'}"
+        what = "value" if kind == "value" else "text"
+        if step.get("equals"):
+            return f"check {label} {what} contains {{{{{step['equals']}}}}} (kept earlier: {step.get('text')!r} this time)"
+        keep = f", kept as {{{{{step['keep']['name']}}}}}" if step.get("keep") else ""
+        return f"check {label} {what} {'matches the pattern of' if step.get('dynamic') else 'contains'} {step.get('text')!r}{keep}"
+    return op
+
+
+@dataclass
+class WebRecorder:
+    start_url: str
+    name: str = ""
+    # Saved logins' values by the variable they come from, so text equal to one is written as that variable.
+    login_values: Mapping[str, str] = field(default_factory=dict)
+    # The password variable of each saved login, by the hosts it signs in to.
+    login_passwords: Mapping[str, str] = field(default_factory=dict)
+    clock: Callable[[], float] = lambda: 0.0
+    # The test case being recorded: its steps ({n, action, expected}), shown as a checklist; each recorded step belongs
+    # to the case step the tester is on.
+    case_steps: List[Dict[str, Any]] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self.steps: List[Dict[str, Any]] = [{"op": "navigate", "url": self.start_url}]
+        self.skipped: List[Dict[str, Any]] = []
+        self.variables: Dict[str, str] = {}
+        self.secrets: List[str] = []
+        self.paused = False
+        self.url = self.start_url
+        self._history: List[str] = [self.start_url]
+        self._last_action = -1e9
+        self._last_click: Optional[Tuple[Tuple[str, str], float]] = None
+        self.case_at = 1 if self.case_steps else 0
+
+    # -- what the tester did ----------------------------------------------------------------------------------------
+
+    def on_navigate(self, url: str, how: str = "") -> Optional[str]:
+        """
+        A page loaded in the tab: `how` is "page" (the page itself navigated: a link, a form, a script), "reload",
+        "back", "forward", or "" (the address bar, a bookmark).
+        """
+        if not url.startswith(("http://", "https://")):
+            return None
+        at = self.clock()
+        previous, self.url = self.url, url
+        if how == "reload" or url == previous:
+            return None
+        caused = how == "page" or at - self._last_action <= NAV_CAUSED_SECONDS
+        if how == "back" and not caused:
+            if self.paused:
+                return None
+            self._history.append(url)
+            self._add({"op": "back"})
+            return "go back"
+        self._history.append(url)
+        if caused or self.paused:
+            return None
+        self._add({"op": "navigate", "url": url})
+        return f"open {url}"
+
+    def on_click(self, t: Target, *, hover: Optional[Target] = None) -> Optional[str]:
+        if self.paused:
+            return None
+        at = self.clock()
+        self._last_action = at
+        last = self._last_click
+        if last is not None and last[0] == t.key and at - last[1] <= DOUBLE_CLICK_SECONDS and self.steps[-1].get("op") == "click":
+            self.steps[-1] = {**self.steps[-1], "op": "dblclick"}
+            self._last_click = None
+            return describe(self.steps[-1])
+        if hover is not None and hover.key != t.key:
+            prev = self.steps[-1]
+            if not (prev.get("op") == "hover" and _same(prev, hover)):
+                self._add({**element_step("hover", hover), "inferred": True})
+        self._add(element_step("click", t))
+        self._last_click = (t.key, at)
+        return describe(self.steps[-1])
+
+    def on_dblclick(self, t: Target) -> Optional[str]:
+        """The browser's own double-click event: the two clicks before it on the element become one double-click."""
+        if self.paused:
+            return None
+        self._last_action = self.clock()
+        if self.steps[-1].get("op") == "dblclick" and _same(self.steps[-1], t):
+            return None
+        while len(self.steps) > 1 and self.steps[-1].get("op") == "click" and _same(self.steps[-1], t):
+            self.steps.pop()
+        self._add(element_step("dblclick", t))
+        self._last_click = None
+        return describe(self.steps[-1])
+
+    def on_fill(self, t: Target, value: Optional[str], *, password: bool = False) -> Optional[str]:
+        """The final text of a field the tester typed in; `value` is None for a password field (never sent)."""
+        if self.paused:
+            return None
+        self._last_action = self.clock()
+        self._last_click = None
+        # The click that put the caret in the field, and an earlier fill of the same field just before: one step.
+        while len(self.steps) > 1 and self.steps[-1].get("op") in ("click", "input") and _same(self.steps[-1], t):
+            self.steps.pop()
+        step = element_step("input", t)
+        step["clear"] = True
+        host = urlparse(t.url).hostname or ""
+        if password or value is None:
+            env = self._password_env(host)
+            step.update(text="", text_env=env)
+            if env not in self.secrets:
+                self.secrets.append(env)
+        else:
+            env = next((k for k, v in self.login_values.items() if v and value == v), None)
+            if env:
+                step.update(text="", text_env=env)
+            else:
+                var = next((k for k, v in self.variables.items() if v and value == v), None)
+                step["text"] = "{{%s}}" % var if var else value
+                # A date typed as itself changes meaning tomorrow: it is kept as days from today.
+                fresh = None if var else dynamic.relative_date(value)
+                if fresh:
+                    step.update(text=fresh, example=value, generated="date")
+        self._add(step)
+        return describe(step)
+
+    def on_select(self, t: Target, text: str) -> Optional[str]:
+        if self.paused:
+            return None
+        self._last_action = self.clock()
+        self._last_click = None
+        if len(self.steps) > 1 and self.steps[-1].get("op") == "click" and _same(self.steps[-1], t):
+            self.steps.pop()
+        step = element_step("select", t)
+        step["text"] = _clip(text)
+        self._add(step)
+        return describe(step)
+
+    def on_press(self, keys: str, *, in_field: bool = False, autocomplete: bool = False) -> Optional[str]:
+        if self.paused or not keys:
+            return None
+        key = keys.split("+")[-1]
+        if in_field and "+" not in keys and key not in FIELD_KEYS and not (autocomplete and key in AUTOCOMPLETE_KEYS):
+            return None
+        self._last_action = self.clock()
+        self._last_click = None
+        self._add({"op": "press", "keys": keys})
+        return describe(self.steps[-1])
+
+    def on_upload(self, t: Target, files: List[str], refused: List[str]) -> Optional[str]:
+        """Files the tester chose in a file field: `files` relative to the working folder, `refused` why others are not."""
+        if self.paused:
+            return None
+        self._last_action = self.clock()
+        self._last_click = None
+        for why in refused:
+            self._skip("upload", why)
+        if not files:
+            return f"not recorded: upload: {refused[0]}" if refused else None
+        if len(self.steps) > 1 and self.steps[-1].get("op") == "click" and _same(self.steps[-1], t):
+            self.steps.pop()
+        self._add({**element_step("upload", t), "files": files})
+        return describe(self.steps[-1])
+
+    def on_unsupported(self, action: str, reason: str) -> str:
+        """Something the tester did that cannot be a step yet (an upload, a drag): listed in the result."""
+        if not self.paused:
+            self._last_action = self.clock()
+        return self._skip(action, reason)
+
+    # -- what the tester added ----------------------------------------------------------------------------------------
+
+    def add_expect(self, kind: str, t: Optional[Target] = None, text: str = "", *, expected: str = "", dynamic: bool = False, source: str = "picked") -> str:
+        # On a case step with an expected result, the check is that result unless the tester said otherwise.
+        expected = expected or self._case_expected()
+        if kind not in EXPECT_KINDS:
+            return self._skip("check", f"unknown kind of check {kind!r}")
+        if kind in ("url", "title", "intent"):
+            step: Dict[str, Any] = {"op": "expect", "kind": kind}
+        elif t is None:
+            return self._skip("check", "no element was picked")
+        else:
+            if kind == "value" and t.input_type == "password":
+                return self._skip("check", "a password field is never checked")
+            step = {**element_step("expect", t), "kind": kind, "_facts": t.facts}
+        text = _clip(text)
+        if kind not in ("visible", "hidden", "intent"):
+            if not text and kind != "checked":
+                return self._skip("check", "the element shows no text; check that it is visible instead")
+            step["text"] = text
+        if kind == "intent":
+            if not _clip(expected):
+                return self._skip("check", "say what to check")
+        if expected:
+            step["expected"] = _clip(expected)
+        if dynamic:
+            step["dynamic"] = True
+        # A check of a value the test makes fresh on each run (a date from today, a unique part) checks the same fresh value.
+        made = next((s for s in reversed(self.steps) if s.get("op") == "input" and s.get("generated") and s.get("example") == text), None)
+        if made is not None:
+            step["text"] = made["text"]
+        elif kind in ("text", "value") and text:
+            self._live(step, text, explicit=dynamic)
+        step["source"] = source
+        self._add(step)
+        return describe(step)
+
+    def _live(self, step: Dict[str, Any], text: str, *, explicit: bool = False) -> None:
+        """
+        A check of data that changes: the same value an earlier step checked or kept becomes that variable; else the
+        check is of its pattern, not this run's value.
+        """
+        found = dynamic.values(text)
+        for v in found:
+            name = self._kept_as(v, step)
+            if name:
+                step.update(equals=name, dynamic=True)
+                step.pop("pattern", None)
+                return
+        pattern = dynamic.pattern_of(text) if found else None
+        if pattern:
+            step.update(dynamic=True, pattern=pattern)
+        elif explicit:
+            step["dynamic"] = True
+
+    def _kept_as(self, value: str, step: Dict[str, Any]) -> Optional[str]:
+        """The variable an earlier check or keep step holds `value` in, made so when that step checked it."""
+        for name, v in self.variables.items():
+            if v == value and (step.get("keep") or {}).get("name") != name:
+                return name
+        at = next((i for i, x in enumerate(self.steps) if x is step), len(self.steps))
+        for prev in reversed(self.steps[:at]):
+            if prev.get("op") != "expect" or prev.get("kind") not in ("text", "value") or value not in dynamic.values(str(prev.get("text") or "")):
+                continue
+            if prev.get("keep"):
+                return str(prev["keep"]["name"])
+            name = var_name(_name_hint(prev.get("_facts") or {}) or str(prev.get("label") or ""), self.variables)
+            pattern = next(dynamic._token_pattern(k, value, m) for s_, e_, k, m in dynamic._spans(value))
+            prev["keep"] = {"name": name, "pattern": pattern}
+            self.variables[name] = value
+            return name
+        return None
+
+    def add_capture(self, t: Target, text: str, name: str = "") -> str:
+        text = _clip(text)
+        if not text:
+            return self._skip("variable", "the element shows no text to keep")
+        if t.input_type == "password":
+            return self._skip("variable", "a password field is never kept")
+        name = var_name(name or _name_hint(t.facts), self.variables)
+        self.variables[name] = text
+        self._add({**element_step("capture", t), "name": name, "text": text})
+        return describe(self.steps[-1])
+
+    def add_wait(self, t: Target) -> str:
+        self._add(element_step("wait_for", t))
+        return describe(self.steps[-1])
+
+    def add_note(self, text: str) -> str:
+        text = _clip(text, 400)
+        if not text:
+            return self._skip("note", "the note is empty")
+        step = self.steps[-1]
+        step["note"] = f"{step['note']} {text}" if step.get("note") else text
+        return f"note on step {len(self.steps)}: {text}"
+
+    def mark_param(self, name: str = "") -> str:
+        """The last typed value becomes test data: the test reads it from its data instead of spelling it out."""
+        step = next((s for s in reversed(self.steps) if s.get("op") == "input"), None)
+        if step is None or step.get("text_env") or "{{" in str(step.get("text") or ""):
+            return self._skip("test data", "no typed value to turn into test data")
+        taken = {s.get("param") for s in self.steps if s.get("param")}
+        step["param"] = var_name(name or step.get("label") or "", taken)
+        return describe(step)
+
+    def undo(self) -> str:
+        if len(self.steps) <= 1:
+            return "nothing to undo"
+        step = self.steps.pop()
+        if step.get("op") == "capture":
+            self.variables.pop(str(step.get("name")), None)
+        self._last_click = None
+        return f"removed: {describe(step)}"
+
+    def delete(self, n: int) -> str:
+        """Remove step `n` (1-based); the first step, opening the start page, stays."""
+        if n <= 1 or n > len(self.steps):
+            return f"no step {n} to remove"
+        step = self.steps.pop(n - 1)
+        if step.get("op") == "capture":
+            self.variables.pop(str(step.get("name")), None)
+        self._last_click = None
+        return f"removed step {n}: {describe(step)}"
+
+    def set_kind(self, n: int, kind: str) -> str:
+        if not (1 <= n <= len(self.steps)) or self.steps[n - 1].get("op") != "expect":
+            return f"step {n} is not a check"
+        step = self.steps[n - 1]
+        if kind not in ("text", "visible", "hidden", "value") or step.get("kind") in ("url", "title", "intent"):
+            return f"a check of this element cannot be {kind!r}"
+        step["kind"] = kind
+        if kind in ("visible", "hidden"):
+            step.pop("text", None)
+        return describe(step)
+
+    def set_dynamic(self, n: int, live: bool) -> str:
+        """The tester's say on live data: a check of its pattern or of this value; a typed date as typed or from today."""
+        if not (1 <= n <= len(self.steps)):
+            return f"no step {n}"
+        step = self.steps[n - 1]
+        if step.get("op") == "input" and step.get("generated"):
+            if not live:
+                step.update(text=step.pop("example"), generated=None)
+                step.pop("generated", None)
+            return describe(step)
+        if step.get("op") != "expect":
+            return f"step {n} is not a check"
+        if live:
+            step["dynamic"] = True
+            if step.get("text") and not step.get("equals"):
+                self._live(step, str(step["text"]), explicit=True)
+        else:
+            for k in ("dynamic", "pattern", "equals"):
+                step.pop(k, None)
+        return describe(step)
+
+    # -- the test case --------------------------------------------------------------------------------------------------
+
+    def set_case_step(self, n: int) -> str:
+        if not self.case_steps:
+            return "no test case is being recorded"
+        if not 1 <= n <= len(self.case_steps):
+            return f"the test case has no step {n}"
+        self.case_at = n
+        return f"on case step {n}: {_clip(self.case_steps[n - 1].get('action'), 120)}"
+
+    def next_case_step(self) -> str:
+        return self.set_case_step(min(self.case_at + 1, len(self.case_steps))) if self.case_steps else "no test case is being recorded"
+
+    def case_gaps(self) -> List[Dict[str, Any]]:
+        """The case steps with an expected result and no check recorded on them."""
+        checked = {s.get("case_step") for s in self.steps if s.get("op") == "expect"}
+        return [{"n": i + 1, "expected": _clip(c.get("expected"))} for i, c in enumerate(self.case_steps) if _clip(c.get("expected")) and (i + 1) not in checked]
+
+    def case_view(self) -> List[Dict[str, Any]]:
+        checked = {s.get("case_step") for s in self.steps if s.get("op") == "expect"}
+        done = {s.get("case_step") for s in self.steps}
+        return [
+            {"n": i + 1, "action": _clip(c.get("action"), 160), **({"expected": _clip(c.get("expected"))} if c.get("expected") else {}), "current": i + 1 == self.case_at, "checked": (i + 1) in checked, "done": (i + 1) in done}
+            for i, c in enumerate(self.case_steps)
+        ]
+
+    def _case_expected(self) -> str:
+        if not self.case_at or self.case_at > len(self.case_steps):
+            return ""
+        return _clip(self.case_steps[self.case_at - 1].get("expected"))
+
+    def _add(self, step: Dict[str, Any]) -> None:
+        if self.case_at:
+            step.setdefault("case_step", self.case_at)
+        self.steps.append(step)
+
+    # -- the result ---------------------------------------------------------------------------------------------------
+
+    @property
+    def checks(self) -> int:
+        return sum(1 for s in self.steps if s.get("op") == "expect")
+
+    def view(self) -> List[Dict[str, Any]]:
+        """The steps as the Recorder lists them."""
+        return [
+            {
+                "n": i + 1,
+                "op": s.get("op"),
+                "text": describe(s),
+                **({"kind": s["kind"]} if s.get("kind") else {}),
+                **({"dynamic": True} if s.get("dynamic") else {}),
+                **({"note": s["note"]} if s.get("note") else {}),
+                **({"inferred": True} if s.get("inferred") else {}),
+                **({"case_step": s["case_step"]} if s.get("case_step") else {}),
+                **({"generated": s["generated"]} if s.get("generated") else {}),
+            }
+            for i, s in enumerate(self.steps)
+        ]
+
+    def summary(self) -> str:
+        n = len(self.steps)
+        parts = [f"{n} step{'s' if n != 1 else ''}"]
+        if self.checks:
+            parts.append(f"{self.checks} check{'s' if self.checks != 1 else ''}")
+        if self.variables:
+            parts.append(f"{len(self.variables)} variable{'s' if len(self.variables) != 1 else ''}")
+        return ", ".join(parts)
+
+    # -- helpers ------------------------------------------------------------------------------------------------------
+
+    def _password_env(self, host: str) -> str:
+        host = host.lower()
+        for hosts, env in self.login_passwords.items():
+            if any(host == h or host.endswith("." + h) for h in hosts.split(",") if h):
+                return env
+        return secret_env_for(host)
+
+    def _skip(self, action: str, reason: str) -> str:
+        self.skipped.append({"index": len(self.skipped) + 1, "action": action, "reason": reason})
+        return f"not recorded: {action}: {reason}"
+
+
+def _name_hint(facts: Dict[str, Any]) -> str:
+    """What to call a kept value: the element's test id, id, name, or label (data-testid="order-id" → order_id), not its text."""
+    a = facts.get("attributes") or {}
+    for k in (*TEST_ID_ATTRS, "id", "name", "aria-label", "title"):
+        v = str(a.get(k) or "")
+        if v and not looks_generated(v):
+            return v
+    return str(facts.get("name") or "") if facts.get("tag") in ("input", "select", "textarea") else ""
+
+
+def _same(step: Dict[str, Any], t: Target) -> bool:
+    """Whether a recorded step acted on target `t`: the same page and the same best locator."""
+    locs = step.get("locators") or []
+    best = locs[0] if locs else {}
+    return (step.get("page"), f"{best.get('type')}:{best.get('value')}") == t.key