verifaied 0.29.0.dev76__tar.gz → 0.30.0.dev77__tar.gz

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verifaied
-Version: 0.29.0.dev76
+Version: 0.30.0.dev77
 Summary: Find what's untested in your code — locally, no account required
 Project-URL: Homepage, https://pypi.org/project/verifaied/
 Author: Kyle Richards
@@ -470,8 +470,10 @@ verifaied test run --all
 verifaied test run --all --env stage
 
 # How much of the run's clock goes on making the video watchable.
-# `fast` (the default) marks what each step clicks and moves on;
-# `watch` lingers on every action; `off` records without annotations.
+# `fast` (the default) glides a cursor to what each step acts on, marks
+# it, types at five characters a second and draws each step's caption;
+# `watch` lingers on every action; `off` records without any of it and
+# skips the flow's Pause steps and the holds after its checks.
 verifaied test run "Settings/API tokens" --video watch
 
 # What's recorded, and how each last went on this branch.
@@ -599,7 +601,67 @@ the delete is **refused and the step comes back** rather than taking a
 neighbour with it.
 
 Once the spec is saved it is a plain file in your repo, and your editor is
-the better tool for it.
+the better tool for it — though every step's caption, and a check's hold,
+can still be changed from the test's page without recording anything: the
+pencil on a block stages the change, and one Save rewrites the file and
+replays it.
+
+### Holds and captions — what the video says
+
+A replay's video is the record a person reviews, so two things are drawn
+on it beyond the steps themselves. **Every check holds**: after an
+assertion passes the replay lingers for a moment — two seconds by default
+— so the viewer sees the state that was checked before the next step
+moves on. **Every step is captioned**: a short line in plain English —
+"Open the settings page", "The token appears in the list" — drawn at the
+bottom of the video while the step runs.
+
+Both are settings on `[browser-tests]` in `.verifaied/config.toml` — or,
+for the whole repository at once, on its Settings page in the web under
+**Browser tests**, where every replay-video key sits beside them. A
+value saved on the page applies to every machine that records or replays
+the repository and wins over the file; a key left on the machine default
+keeps reading the file, and a `--video` flag or the Video settings menu
+still wins over both for one run:
+
+```toml
+[browser-tests]
+# How long the replay holds after each check passes. 0 for no hold.
+assertion_pause_ms = 2000
+# Whether steps are captioned as they land while recording.
+captions = true
+```
+
+The studio reads them when it connects and shows them under **Settings**
+beside Variables, where either can be changed for one recording. Any
+check can be given its own hold from its Edit form, and any step's caption
+can be edited, regenerated or switched off from the flow — a caption you
+switch off stays off. While a recording is live the studio page writes
+the captions itself, one per step as it lands, from a model given the
+line and its place in the flow; it is a paid call at the cheapest tier,
+and a plan or spend cap that refuses it stops the auto-captioning for that
+recording and says so, leaving the steps to be captioned by hand. The
+assistant captions the steps it writes, and an agent recording through
+`verifaied test mcp` passes a `caption` with each step and `hold_seconds`
+with each check — nothing captions a step behind your back.
+
+Generated captions are short, concise and in simplified technical
+English: one sentence, one idea, present tense, active voice, at most ten
+words, naming what a person sees and never a selector, a value or a
+password. A typed one may be anything up to 120 characters on one line,
+except the words a caption-less step is called (`Pause 2s`, `Hold 2s`).
+
+In the spec a captioned or held step is one named step around the line:
+
+```ts
+await test.step("The token appears in the list", async () => { await expect(page.getByText("tok_…")).toBeVisible(); await page.waitForTimeout(2000); });
+```
+
+A held check with no caption is titled `Hold 2s`; a step with neither is
+written bare, exactly as before. Holds wait in every replay except one
+run with `--video off` (or `replay_pauses = false`), which skips them
+with the Pause steps; captions are drawn unless `replay_captions = false`
+or the video is off. Neither counts against the replay's time budget.
 
 ### Running another test inside this one
 
@@ -976,9 +1038,14 @@ was clicked with `video.show`. 1.60 is where the last of those shipped,
 so it is a floor and not an allowlist: anything newer is allowed, and
 anything older is refused rather than opening a browser that would
 record nothing. `test run` stays ungated. Below 1.60 the annotation is
-not available, so set `replay_show_actions_ms = 0` and
-`replay_video_step_banner = false` there — that writes exactly the
-config the CLI wrote before this option existed.
+not available, so use `--video off` there, or set every replay key to
+its off value (`replay_show_actions_ms = 0`, `replay_cursor_ms = 0`,
+`replay_type_delay_ms = 0`, `replay_pauses = false`,
+`replay_captions = false` and `replay_video_step_banner = false`) — that
+writes exactly the config the CLI wrote before any of it existed. Every
+one of those keys can also be set once for the repository on its
+Settings page, which the CLI reads at the start of each recording and
+replay and lays over the file.
 
 ### Exit codes
 

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/README.md

@@ -424,8 +424,10 @@ verifaied test run --all
 verifaied test run --all --env stage
 
 # How much of the run's clock goes on making the video watchable.
-# `fast` (the default) marks what each step clicks and moves on;
-# `watch` lingers on every action; `off` records without annotations.
+# `fast` (the default) glides a cursor to what each step acts on, marks
+# it, types at five characters a second and draws each step's caption;
+# `watch` lingers on every action; `off` records without any of it and
+# skips the flow's Pause steps and the holds after its checks.
 verifaied test run "Settings/API tokens" --video watch
 
 # What's recorded, and how each last went on this branch.
@@ -553,7 +555,67 @@ the delete is **refused and the step comes back** rather than taking a
 neighbour with it.
 
 Once the spec is saved it is a plain file in your repo, and your editor is
-the better tool for it.
+the better tool for it — though every step's caption, and a check's hold,
+can still be changed from the test's page without recording anything: the
+pencil on a block stages the change, and one Save rewrites the file and
+replays it.
+
+### Holds and captions — what the video says
+
+A replay's video is the record a person reviews, so two things are drawn
+on it beyond the steps themselves. **Every check holds**: after an
+assertion passes the replay lingers for a moment — two seconds by default
+— so the viewer sees the state that was checked before the next step
+moves on. **Every step is captioned**: a short line in plain English —
+"Open the settings page", "The token appears in the list" — drawn at the
+bottom of the video while the step runs.
+
+Both are settings on `[browser-tests]` in `.verifaied/config.toml` — or,
+for the whole repository at once, on its Settings page in the web under
+**Browser tests**, where every replay-video key sits beside them. A
+value saved on the page applies to every machine that records or replays
+the repository and wins over the file; a key left on the machine default
+keeps reading the file, and a `--video` flag or the Video settings menu
+still wins over both for one run:
+
+```toml
+[browser-tests]
+# How long the replay holds after each check passes. 0 for no hold.
+assertion_pause_ms = 2000
+# Whether steps are captioned as they land while recording.
+captions = true
+```
+
+The studio reads them when it connects and shows them under **Settings**
+beside Variables, where either can be changed for one recording. Any
+check can be given its own hold from its Edit form, and any step's caption
+can be edited, regenerated or switched off from the flow — a caption you
+switch off stays off. While a recording is live the studio page writes
+the captions itself, one per step as it lands, from a model given the
+line and its place in the flow; it is a paid call at the cheapest tier,
+and a plan or spend cap that refuses it stops the auto-captioning for that
+recording and says so, leaving the steps to be captioned by hand. The
+assistant captions the steps it writes, and an agent recording through
+`verifaied test mcp` passes a `caption` with each step and `hold_seconds`
+with each check — nothing captions a step behind your back.
+
+Generated captions are short, concise and in simplified technical
+English: one sentence, one idea, present tense, active voice, at most ten
+words, naming what a person sees and never a selector, a value or a
+password. A typed one may be anything up to 120 characters on one line,
+except the words a caption-less step is called (`Pause 2s`, `Hold 2s`).
+
+In the spec a captioned or held step is one named step around the line:
+
+```ts
+await test.step("The token appears in the list", async () => { await expect(page.getByText("tok_…")).toBeVisible(); await page.waitForTimeout(2000); });
+```
+
+A held check with no caption is titled `Hold 2s`; a step with neither is
+written bare, exactly as before. Holds wait in every replay except one
+run with `--video off` (or `replay_pauses = false`), which skips them
+with the Pause steps; captions are drawn unless `replay_captions = false`
+or the video is off. Neither counts against the replay's time budget.
 
 ### Running another test inside this one
 
@@ -930,9 +992,14 @@ was clicked with `video.show`. 1.60 is where the last of those shipped,
 so it is a floor and not an allowlist: anything newer is allowed, and
 anything older is refused rather than opening a browser that would
 record nothing. `test run` stays ungated. Below 1.60 the annotation is
-not available, so set `replay_show_actions_ms = 0` and
-`replay_video_step_banner = false` there — that writes exactly the
-config the CLI wrote before this option existed.
+not available, so use `--video off` there, or set every replay key to
+its off value (`replay_show_actions_ms = 0`, `replay_cursor_ms = 0`,
+`replay_type_delay_ms = 0`, `replay_pauses = false`,
+`replay_captions = false` and `replay_video_step_banner = false`) — that
+writes exactly the config the CLI wrote before any of it existed. Every
+one of those keys can also be set once for the repository on its
+Settings page, which the CLI reads at the start of each recording and
+replay and lays over the file.
 
 ### Exit codes
 

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "verifaied"
-version = "0.29.0.dev76"
+version = "0.30.0.dev77"
 description = "Find what's untested in your code — locally, no account required"
 readme = "README.md"
 requires-python = ">=3.10"

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/src/verifaied/agent_mcp.py

@@ -44,6 +44,7 @@ from __future__ import annotations
 
 import asyncio
 import atexit
+import math
 import queue as queue_module
 import signal
 import subprocess
@@ -66,10 +67,12 @@ from verifaied.agent_steps import (
     report,
 )
 from verifaied.config import web_url_for
+from verifaied.repo_config import RepoConfigError, web_authoring_keys
 from verifaied.stepcheck import (
     MAX_FLOW_STEPS,
     MAX_SCRIPT_CHARS,
     compose_script,
+    validate_caption_text,
     validate_step_line,
 )
 from verifaied.testcmd import (
@@ -80,6 +83,8 @@ from verifaied.testcmd import (
     SessionHooks,
     ShellRunner,
     StreamRunner,
+    authoring_settings,
+    compose_pause,
     detect_playwright_version,
     discard_test_row,
     ensure_supported_playwright,
@@ -87,6 +92,10 @@ from verifaied.testcmd import (
     list_recorded_tests,
     normalize_start_url,
     parse_test_ref,
+    pause_label,
+    pause_refusal,
+    read_repo_config,
+    read_service_settings,
     record_one,
     ref_of,
     resolve_or_create_test,
@@ -192,7 +201,7 @@ Guessing what a page will look like after a click is how flows break.
 
 {_LOCATOR_DOCTRINE}
 
-Each step is ONE of three shapes and nothing else:
+Each step is ONE of four shapes and nothing else:
 
   - an ACTION (kind "action"): `await page.<locator>.<verb>(...);` with
     <verb> one of click, dblclick, fill, press, check, uncheck,
@@ -208,6 +217,22 @@ Each step is ONE of three shapes and nothing else:
     is wrapped in `await page.evaluate(async () => {{ … }});` for you, so
     `await` works inside it. It lands in the flow as an action labelled
     "Run a script in the page".
+  - a PAUSE (kind "pause"): `{{"kind": "pause", "seconds": 2}}`, no code.
+    It holds the replay's video still for that long so a reader can see
+    the result of the step before it — a toast, a filled form, a page
+    that just arrived. Between 0.1 and 30 seconds. It is skipped when the
+    video is off, so it must never be what a flow *depends* on: a pause
+    never waits for the app — an assertion does that, and waits until
+    the page agrees.
+
+Any step may carry a `"caption"`: one short sentence shown under the
+video while the step runs, for a reviewer who does not read code — one
+idea, present tense, active voice, at most 8 words; an action is an
+imperative ("Open the settings page"), a check says what is true ("The
+token appears in the list"), a pause says what the viewer watches ("The
+chart loads"); name what a person sees, never a selector or a value.
+An `assert` may carry `"hold_seconds"`: how long the video holds on what
+it checked (0 for none); left out, the repo's own default applies.
 
 Rules for the code:
 
@@ -303,9 +328,9 @@ today and fails next week. Replace it: `delete_step` the line and queue a
 corrected one naming the stable part yourself (`getByText(/Matches/)`,
 `toContainText('Matches')`).
 
-Arguments: `steps` is a list of `{{"kind": "action"|"assert"|"script", "code":
-"<one statement, or a script's body>", "label": "<a few words saying what it
-does>"}}`."""
+Arguments: `steps` is a list of `{{"kind": "action"|"assert"|"script"|"pause",
+"code": "<one statement, or a script's body>", "label": "<a few words saying
+what it does>"}}` — a pause carries `"seconds"` instead of code."""
 
 
 # What each ending actually does, so a refusal says why waiting for the
@@ -445,6 +470,18 @@ class AgentRecorderServer:
         self.token = token
         self.repo_id = repo_id
         self.root = root
+        # The repo's authoring defaults: what a check holds the video for
+        # when the agent says nothing, and whether captions are expected.
+        # Read once; the MCP process is one recording long.
+        try:
+            service = read_service_settings(
+                api_url=api_url, token=token, repo_id=repo_id
+            )
+            self._settings = authoring_settings(
+                read_repo_config(root, service).authoring, web_authoring_keys(service)
+            )
+        except (RecordedTestError, RepoConfigError):
+            self._settings = {}
         self.branch = branch
         self.commit_sha = commit_sha
         self.env_name = env_name
@@ -778,17 +815,78 @@ class AgentRecorderServer:
             raw = str(fields.get("code") or "")
             code = raw.strip()
             label = str(fields.get("label") or "").strip() or code
-            reason = validate_step_line(kind, raw if kind == "script" else code)
-            if reason:
-                entries.append(f"REFUSED — {reason}")
+            # A caption and, on a check, a hold ride beside the line and
+            # are composed into the step by the session — the line itself
+            # stays what every validator reads. The hold defaults to the
+            # repo's own, so an agent that says nothing gets the same
+            # video a person does.
+            caption = fields.get("caption")
+            if caption is not None:
+                reason = validate_caption_text(caption)
+                if reason:
+                    entries.append(f"REFUSED — {reason}")
+                    continue
+                caption = str(caption).strip()
+            hold_ms: int | None = None
+            if kind == "assert":
+                hold_seconds = fields.get("hold_seconds")
+                if hold_seconds is None:
+                    hold_ms = self._settings.get("assertion_pause_ms") or None
+                elif isinstance(hold_seconds, bool) or not isinstance(
+                    hold_seconds, (int, float)
+                ):
+                    entries.append(
+                        "REFUSED — `hold_seconds` is a number of seconds, or 0"
+                    )
+                    continue
+                elif not math.isfinite(float(hold_seconds)):
+                    entries.append(
+                        "REFUSED — `hold_seconds` is a number of seconds, or 0"
+                    )
+                    continue
+                else:
+                    ms = round(float(hold_seconds) * 1000)
+                    if ms != 0 and pause_refusal(hold_seconds):
+                        entries.append(
+                            f"REFUSED — a hold {pause_refusal(hold_seconds)[8:]}"
+                        )
+                        continue
+                    hold_ms = ms or None
+            elif fields.get("hold_seconds") is not None:
+                entries.append(
+                    "REFUSED — a hold follows a check — only an `assert` holds"
+                )
                 continue
+            if kind == "pause":
+                # No code to validate: the seconds are the whole of it,
+                # and the line is composed here exactly as the studio's
+                # Pause tab composes it, so the block reopens there.
+                reason = pause_refusal(fields.get("seconds"))
+                if reason:
+                    entries.append(f"REFUSED — {reason}")
+                    continue
+                ms = round(float(fields.get("seconds")) * 1000)
+                kind, code, label = "action", compose_pause(ms), pause_label(ms)
+            else:
+                reason = validate_step_line(kind, raw if kind == "script" else code)
+                if reason:
+                    entries.append(f"REFUSED — {reason}")
+                    continue
             if kind == "script":
                 # The body is the agent's; the wrapper and the label are
                 # not. Composed exactly as the studio's Run Code tab
                 # composes, so the block reopens there and keeps its name
                 # once the spec is saved.
                 kind, code, label = "action", compose_script(raw), CONSOLE_LABEL
-            accepted.append({"kind": kind, "code": code, "label": label})
+            accepted.append(
+                {
+                    "kind": kind,
+                    "code": code,
+                    "label": label,
+                    "caption": caption,
+                    "hold_ms": hold_ms,
+                }
+            )
             entries.append(
                 AgentStep(
                     handle=recording.next_handle(),
@@ -817,6 +915,10 @@ class AgentRecorderServer:
                 "flow_index": position - 1,
                 "flow_size": len(accepted),
             }
+            if step.get("caption") is not None:
+                payload["caption"] = step["caption"]
+            if step.get("hold_ms"):
+                payload["hold_ms"] = step["hold_ms"]
             if recording.page.snapshot_id is not None:
                 # Which look at the page this line's refs were read from.
                 # The driver compares it against the tree it holds and

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/src/verifaied/cli.py

@@ -1818,9 +1818,12 @@ def test_record_command(
         "--video",
         help=(
             "How the replay that follows this recording should be paced. "
-            "`fast` marks each click and moves on; `watch` lingers on "
-            "every action; `off` records without annotations. Overrides "
-            "replay_show_actions_ms / replay_slow_mo_ms for this run."
+            "`fast` moves a cursor to each target, marks it and types at a "
+            "readable pace; `watch` lingers on every action; `off` records "
+            "without any of it and skips the pauses the flow asks for. "
+            "Overrides replay_show_actions_ms / replay_slow_mo_ms / "
+            "replay_cursor_ms / replay_type_delay_ms / replay_pauses for "
+            "this run."
         ),
     ),
 ) -> None:
@@ -2042,10 +2045,12 @@ def test_run_command(
         None,
         "--video",
         help=(
-            "How the video should be paced. `fast` (the default) marks "
-            "each click and moves on; `watch` lingers on every action; "
-            "`off` records without annotations. Overrides "
-            "replay_show_actions_ms / replay_slow_mo_ms for this run."
+            "How the video should be paced. `fast` (the default) moves a "
+            "cursor to each target, marks it and types at a readable pace; "
+            "`watch` lingers on every action; `off` records without any of "
+            "it and skips the pauses the flow asks for. Overrides "
+            "replay_show_actions_ms / replay_slow_mo_ms / replay_cursor_ms / "
+            "replay_type_delay_ms / replay_pauses for this run."
         ),
     ),
 ) -> None:

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/src/verifaied/client.py

@@ -386,6 +386,37 @@ def _media_type(path: Path) -> str:
     return _MEDIA_TYPES.get(path.suffix.lower(), "application/octet-stream")
 
 
+def get_browser_test_settings(
+    *,
+    api_url: str,
+    token: str,
+    repo_id: UUID,
+    timeout: float = 10.0,
+) -> dict[str, Any]:
+    """The repository's browser-test settings as saved on the web.
+
+    The keys are the ``[browser-tests]`` keys, each null when the web
+    never set it — the CLI lays what is set over the file
+    (``apply_service_settings``). Raises :class:`ApiError` for anything
+    but a settings object, and the caller turns that into "the file
+    decides".
+    """
+    url = f"{api_url.rstrip('/')}/repositories/{repo_id}/browser-test-settings"
+    try:
+        response = httpx.get(
+            url, headers={"Authorization": f"Bearer {token}"}, timeout=timeout
+        )
+    except httpx.HTTPError as e:
+        raise ApiError(0, f"could not reach {url}: {e}") from e
+    if response.status_code >= 400:
+        raise ApiError(response.status_code, _detail(response))
+    data = response.json()
+    settings = data.get("settings") if isinstance(data, dict) else None
+    if not isinstance(settings, dict):
+        raise ApiError(0, f"unexpected response from {url}: no settings object")
+    return settings
+
+
 def list_recorded_tests(
     *,
     api_url: str,

{verifaied-0.29.0.dev76 → verifaied-0.30.0.dev77}/src/verifaied/recorder_driver.js

@@ -232,12 +232,18 @@ function loadPlaywright() {
 // locator expression, for the same reason.
 const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
 
+// What `test` means inside a body run this way. A saved spec wraps an
+// inserted test and a pause in `test.step(...)`, which only exists under
+// the test runner; here the step is simply its body, run — so a pause in
+// a chain waits during the recording's warm-up, and a nested insert runs.
+const TEST_SHIM = { step: async (_title, body) => body() };
+
 async function runPreSteps(preSteps, page, expect) {
   for (let index = 0; index < preSteps.length; index += 1) {
     const step = preSteps[index];
     emit({ type: "pre_step", index, label: step.label, status: "running" });
-    const body = new AsyncFunction("page", "expect", step.body);
-    await body(page, expect);
+    const body = new AsyncFunction("page", "expect", "test", step.body);
+    await body(page, expect, TEST_SHIM);
     emit({ type: "pre_step", index, label: step.label, status: "done" });
   }
 }
@@ -831,6 +837,7 @@ async function main() {
     "new-tab": "a new tab opened — actions in it are not recorded yet",
     dialog: "a browser dialog is not recorded yet",
     download: "a download is not recorded yet",
+    key: "a key this keyboard layout types is not recorded yet",
   };
   async function note(reason) {
     let docId = "";
@@ -1324,9 +1331,10 @@ async function main() {
     let timer = null;
     await setState({ selfActing: true });
     try {
-      const run = new AsyncFunction("page", "expect", body)(
+      const run = new AsyncFunction("page", "expect", "test", body)(
         page,
         playwright.expect,
+        TEST_SHIM,
       );
       // Attached before the race: a rejection arriving after the deadline
       // would otherwise be an unhandled rejection, and Node kills the