verifaied 0.33.0.dev83__tar.gz → 0.34.0.dev84__tar.gz

{verifaied-0.33.0.dev83 → verifaied-0.34.0.dev84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verifaied
-Version: 0.33.0.dev83
+Version: 0.34.0.dev84
 Summary: Find what's untested in your code — locally, no account required
 Project-URL: Homepage, https://pypi.org/project/verifaied/
 Author: Kyle Richards
@@ -669,10 +669,28 @@ await test.step("The token appears in the list", async () => { await expect(page
 ```
 
 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.
+written bare, exactly as before. A run with `--video off` (or
+`replay_pauses = false`) skips every hold with the Pause steps; captions
+are drawn unless `replay_captions = false` or the video is off.
+
+### Headless runs go at full speed
+
+All of that pacing — the cursor, the marks, the typing, the captions,
+the holds — is time a browser spends waiting, and nobody watches a
+headless run. So a headless replay (`test run`, a batch queued from the
+web, CI) runs at full speed and records where each action landed and how
+long each check asked to be held; the paced video is rendered afterwards
+from the run's own frames, following every setting above. While it is
+rendered, in the background, the next test is already running.
+
+A run you watch in a window is always paced live. So is a flow the
+renderer cannot reproduce — one that opens a popup or a second page,
+resizes its own window, or acts on the page without a locator — and the
+run says so in one line. If a render fails after the run, the plain video
+is kept and labelled unpaced. Pause steps always wait, because the page
+may change during one. `--no-render` on `test run`, or
+`replay_render = false` in the file or on the Settings page, paces every
+replay live instead.
 
 ### Running another test inside this one
 
@@ -1152,7 +1170,8 @@ 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
+writes exactly the config the CLI wrote before any of it existed, and
+leaves nothing for a render to pace. 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.
@@ -1198,7 +1217,9 @@ either),
 `--description <text>`, `--pre "<Feature>/<Name>"` (repeatable;
 replaces the stored chain — omit it to keep what the test already has),
 and `--no-replay` to skip the replay. `run` takes `--all` or `--folder
-"<folder path>"` in place of a test name, `--video fast|watch|off`, and
+"<folder path>"` in place of a test name, `--video fast|watch|off`,
+`--no-render` (pace each replay live rather than rendering its video
+afterwards), and
 `--retries <n>` (default 0): a test whose replay **failed** is reset and
 replayed again, up to `n` more times, and the summary says `passed on
 retry 1 of 2` when a later attempt passes. Retries are for infrastructure

{verifaied-0.33.0.dev83 → verifaied-0.34.0.dev84}/README.md

@@ -623,10 +623,28 @@ await test.step("The token appears in the list", async () => { await expect(page
 ```
 
 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.
+written bare, exactly as before. A run with `--video off` (or
+`replay_pauses = false`) skips every hold with the Pause steps; captions
+are drawn unless `replay_captions = false` or the video is off.
+
+### Headless runs go at full speed
+
+All of that pacing — the cursor, the marks, the typing, the captions,
+the holds — is time a browser spends waiting, and nobody watches a
+headless run. So a headless replay (`test run`, a batch queued from the
+web, CI) runs at full speed and records where each action landed and how
+long each check asked to be held; the paced video is rendered afterwards
+from the run's own frames, following every setting above. While it is
+rendered, in the background, the next test is already running.
+
+A run you watch in a window is always paced live. So is a flow the
+renderer cannot reproduce — one that opens a popup or a second page,
+resizes its own window, or acts on the page without a locator — and the
+run says so in one line. If a render fails after the run, the plain video
+is kept and labelled unpaced. Pause steps always wait, because the page
+may change during one. `--no-render` on `test run`, or
+`replay_render = false` in the file or on the Settings page, paces every
+replay live instead.
 
 ### Running another test inside this one
 
@@ -1106,7 +1124,8 @@ 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
+writes exactly the config the CLI wrote before any of it existed, and
+leaves nothing for a render to pace. 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.
@@ -1152,7 +1171,9 @@ either),
 `--description <text>`, `--pre "<Feature>/<Name>"` (repeatable;
 replaces the stored chain — omit it to keep what the test already has),
 and `--no-replay` to skip the replay. `run` takes `--all` or `--folder
-"<folder path>"` in place of a test name, `--video fast|watch|off`, and
+"<folder path>"` in place of a test name, `--video fast|watch|off`,
+`--no-render` (pace each replay live rather than rendering its video
+afterwards), and
 `--retries <n>` (default 0): a test whose replay **failed** is reset and
 replayed again, up to `n` more times, and the summary says `passed on
 retry 1 of 2` when a later attempt passes. Retries are for infrastructure

{verifaied-0.33.0.dev83 → verifaied-0.34.0.dev84}/pyproject.toml

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

{verifaied-0.33.0.dev83 → verifaied-0.34.0.dev84}/src/verifaied/cli.py

@@ -2053,7 +2053,19 @@ def test_run_command(
             "`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."
+            "replay_type_delay_ms / replay_pauses for this run. The run "
+            "itself goes at full speed and the paced video is rendered "
+            "afterwards, unless --no-render."
+        ),
+    ),
+    no_render: bool = typer.Option(
+        False,
+        "--no-render",
+        help=(
+            "Pace each replay live, slowing the browser down so its own "
+            "recording is the paced video, instead of running at full speed "
+            "and rendering the paced video afterwards. Same as "
+            "replay_render = false for this run."
         ),
     ),
     retries: int = typer.Option(
@@ -2112,6 +2124,10 @@ def test_run_command(
     of the app with its own reset. Only this flag turns it on: the
     Settings page's "Tests run at once" is for the studio.
 
+    Each replay runs at full speed and its paced video — cursor, marks,
+    typing, captions and holds — is rendered afterwards, in the background
+    while the next test runs. ``--no-render`` paces each one live instead.
+
     Exit codes:
 
       0  every test replayed cleanly
@@ -2145,6 +2161,7 @@ def test_run_command(
             video=video.value if video is not None else None,
             retries=retries,
             parallel=parallel,
+            no_render=no_render,
         )
     except (RecordedTestError, UploaderError) as e:
         err_console.print(f"[red]VerifAIed error[/red]: {e}")

verifaied-0.34.0.dev84/src/verifaied/finishing.py

@@ -0,0 +1,177 @@
+"""Finishing a replay in the background while the next one runs.
+
+A fast replay is over the moment its runner exits: the verdict is known,
+the coverage has been flushed and the collector has let go of its port.
+What is left — rendering the paced video, uploading the evidence and
+closing the session with the verdict — touches nothing the next replay
+uses. It reads the files in the run's own temp directory and talks to the
+API; it never touches the app, its database or a spec. So it can run
+here, beside the next test, instead of in front of it.
+
+A :class:`FinishPool` runs those jobs on as many threads as the run has
+lanes, and holds at most twice that many outstanding: every lane can hand
+one job over and start its next test while another job is still
+rendering, and a lane whose job cannot be taken waits — which bounds the
+renders running at once by the lanes, and the temp directories waiting
+by twice that, so a long batch never fills a disk with videos nobody has
+rendered yet. A studio, whose lanes change with what the repository asks
+for, resizes it as they do.
+
+Every job is wrapped whole: whatever goes wrong in a render or an upload
+is printed with the test's name, and the session is still closed with the
+run's verdict, because a session nobody closes reads as a run still going.
+Ctrl-C stops the renders and closes what is left with its verdict and no
+video — the user asked to leave, and every verdict is already known.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+from uuid import UUID
+
+from rich.console import Console
+from rich.markup import escape
+
+
+class Stop(Protocol):
+    """What a job is handed to be stopped by (``RunStop`` in testcmd)."""
+
+    def is_set(self) -> bool: ...
+
+    def interrupt(self, message: str) -> None: ...
+
+
+# A job's whole work: given the stop it may be ended by and whether the
+# pool was interrupted (no video then, only the verdict), it finishes the
+# replay and answers its final exit code and what became of its video.
+FinishWork = Callable[[Stop, bool], "tuple[int, str]"]
+
+
+@dataclass
+class FinishJob:
+    """One replay whose finishing was handed over."""
+
+    label: str
+    code: int
+    work: FinishWork
+    stop: Stop
+    # The studio request this replay answers, which its beats must keep
+    # naming until the job is done — or None for a terminal run.
+    request_id: UUID | None = None
+
+
+@dataclass(frozen=True)
+class FinishResult:
+    label: str
+    code: int
+    # "paced", "unpaced: <why>", "live" or "none".
+    video: str = "none"
+
+
+class FinishPool:
+    """A few threads finishing replays; see the module docstring."""
+
+    def __init__(self, workers: int, *, err_console: Console) -> None:
+        self._limit = max(1, workers)
+        self._err_console = err_console
+        self._queue: queue.Queue[FinishJob | None] = queue.Queue()
+        self._lock = threading.Lock()
+        self._changed = threading.Condition(self._lock)
+        self._outstanding: list[FinishJob] = []
+        self._active = 0
+        self._results: list[FinishResult] = []
+        self._threads: list[threading.Thread] = []
+        self._interrupted = False
+
+    # --- what the run asks ---------------------------------------------------
+
+    def has_room(self) -> bool:
+        """Whether a job could be handed over now without waiting."""
+        with self._lock:
+            return len(self._outstanding) < 2 * self._limit
+
+    def in_flight_ids(self) -> list[UUID]:
+        """The studio requests whose replays are still being finished."""
+        with self._lock:
+            return [job.request_id for job in self._outstanding if job.request_id]
+
+    def worst(self) -> int:
+        with self._lock:
+            return max((result.code for result in self._results), default=0)
+
+    def results(self) -> list[FinishResult]:
+        with self._lock:
+            return list(self._results)
+
+    def resize(self, workers: int) -> None:
+        """Run at most ``workers`` jobs at once, and hold twice that."""
+        with self._changed:
+            self._limit = max(1, workers)
+            self._changed.notify_all()
+
+    # --- handing work over ---------------------------------------------------
+
+    def submit(self, job: FinishJob) -> None:
+        """Queue ``job``, waiting while the backlog is full."""
+        with self._changed:
+            while len(self._outstanding) >= 2 * self._limit:
+                self._changed.wait()
+            self._outstanding.append(job)
+            if len(self._threads) < len(self._outstanding):
+                thread = threading.Thread(target=self._work, daemon=True)
+                self._threads.append(thread)
+                thread.start()
+        self._queue.put(job)
+
+    def interrupt(self, message: str) -> None:
+        """Stop every render and finish what is left without its video."""
+        with self._changed:
+            self._interrupted = True
+            jobs = list(self._outstanding)
+            self._changed.notify_all()
+        for job in jobs:
+            job.stop.interrupt(message)
+
+    def drain(self) -> list[FinishResult]:
+        """Wait for every job handed over, and stop the threads."""
+        with self._lock:
+            threads = list(self._threads)
+        for _ in threads:
+            self._queue.put(None)
+        for thread in threads:
+            thread.join()
+        with self._lock:
+            self._threads = []
+        return self.results()
+
+    # --- the workers ---------------------------------------------------------
+
+    def _work(self) -> None:
+        while True:
+            job = self._queue.get()
+            if job is None:
+                return
+            with self._changed:
+                # Never more renders at once than the lanes, unless the user
+                # is leaving — then everything left only closes its session.
+                while self._active >= self._limit and not self._interrupted:
+                    self._changed.wait()
+                self._active += 1
+                interrupted = self._interrupted
+            try:
+                code, video = job.work(job.stop, interrupted)
+            except Exception as e:  # noqa: BLE001 — a finisher never dies silently
+                self._err_console.print(
+                    f"[red]could not finish[/red] {escape(job.label)}: "
+                    f"{escape(str(e) or repr(e))}"
+                )
+                code, video = (2 if job.code == 0 else job.code), "none"
+            with self._changed:
+                self._active -= 1
+                self._results.append(FinishResult(job.label, code, video))
+                self._outstanding.remove(job)
+                self._changed.notify_all()

{verifaied-0.33.0.dev83 → verifaied-0.34.0.dev84}/src/verifaied/record.py

@@ -31,7 +31,7 @@ import subprocess
 import tempfile
 import threading
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from typing import Any
@@ -500,6 +500,7 @@ def upload_artifacts(
     results_root: Path,
     console: Console,
     err_console: Console,
+    labels: Mapping[Path, str] | None = None,
 ) -> int:
     """Attach each harvested file to the session; returns how many landed.
 
@@ -507,6 +508,10 @@ def upload_artifacts(
     is a bonus on top of the coverage the session already uploaded, and
     losing a run's exit code over a failed screenshot upload would be an
     absurd trade.
+
+    ``labels`` names a file whose label is not its place under
+    ``results_root`` — a paced video rendered elsewhere, standing in for
+    the run's own, or a video kept unpaced and saying so.
     """
     uploaded = 0
     for kind, path in items:
@@ -525,7 +530,7 @@ def upload_artifacts(
                 session_id=session_id,
                 path=path,
                 kind=kind,
-                label=artifact_label(path, results_root),
+                label=(labels or {}).get(path) or artifact_label(path, results_root),
             )
         except ApiError as e:
             err_console.print(