verifaied 0.31.1.dev79__tar.gz → 0.32.0.dev80__tar.gz

{verifaied-0.31.1.dev79 → verifaied-0.32.0.dev80}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verifaied
-Version: 0.31.1.dev79
+Version: 0.32.0.dev80
 Summary: Find what's untested in your code — locally, no account required
 Project-URL: Homepage, https://pypi.org/project/verifaied/
 Author: Kyle Richards
@@ -1054,11 +1054,18 @@ cloud can stop it. A request that fails is reported with the reason and
 the studio carries on — one bad pre-step chain is not a reason for it to
 die.
 
+**Stopping a run from the web.** While a run is replaying, the spinning
+Run button on the page turns into **Stop**. The studio hears it on its next
+beat, ends the replay's whole process group (SIGTERM, then SIGKILL), and
+records the run as failed with "Stopped from the web"; its video and trace
+are not kept. This uses POSIX process groups (`os.killpg`), so it needs
+macOS or Linux — the studio does not support Windows.
+
 **Branches.** The branch is re-detected on every beat, so switching
 branches under a running studio moves what the web shows and what the next
 recording lands against. `--branch` pins it instead.
 
-**Ctrl-C** does the safe thing at either moment. Mid-recording, the
+**Ctrl-C** (and SIGTERM, or the terminal closing) does the safe thing at either moment. Mid-recording, the
 interrupt is forwarded to the recorder exactly as it is for `test record`:
 the browser closes, the spec is saved, the replay runs, the request
 completes — and only then does the studio exit. At the idle prompt it

{verifaied-0.31.1.dev79 → verifaied-0.32.0.dev80}/README.md

@@ -1008,11 +1008,18 @@ cloud can stop it. A request that fails is reported with the reason and
 the studio carries on — one bad pre-step chain is not a reason for it to
 die.
 
+**Stopping a run from the web.** While a run is replaying, the spinning
+Run button on the page turns into **Stop**. The studio hears it on its next
+beat, ends the replay's whole process group (SIGTERM, then SIGKILL), and
+records the run as failed with "Stopped from the web"; its video and trace
+are not kept. This uses POSIX process groups (`os.killpg`), so it needs
+macOS or Linux — the studio does not support Windows.
+
 **Branches.** The branch is re-detected on every beat, so switching
 branches under a running studio moves what the web shows and what the next
 recording lands against. `--branch` pins it instead.
 
-**Ctrl-C** does the safe thing at either moment. Mid-recording, the
+**Ctrl-C** (and SIGTERM, or the terminal closing) does the safe thing at either moment. Mid-recording, the
 interrupt is forwarded to the recorder exactly as it is for `test record`:
 the browser closes, the spec is saved, the replay runs, the request
 completes — and only then does the studio exit. At the idle prompt it

{verifaied-0.31.1.dev79 → verifaied-0.32.0.dev80}/pyproject.toml

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

{verifaied-0.31.1.dev79 → verifaied-0.32.0.dev80}/src/verifaied/client.py

@@ -722,6 +722,7 @@ def post_recorder_heartbeat(
     kinds: list[str] | None = None,
     environment: str | None = None,
     busy: bool = False,
+    working: UUID | None = None,
     timeout: float = 30.0,
 ) -> dict[str, Any]:
     """Say a studio is listening, and collect what to record next.
@@ -769,6 +770,10 @@ def post_recorder_heartbeat(
         body["environment"] = environment
     if busy:
         body["busy"] = True
+    if working is not None:
+        # Which run this busy studio is on, so the service does not stop it
+        # as a run whose studio went away. Sent only when named.
+        body["working"] = str(working)
     try:
         response = _http().post(
             request_url,
@@ -820,6 +825,35 @@ def post_recording_request_status(
         raise ApiError(response.status_code, _detail(response))
 
 
+def cancel_queued_runs(
+    *,
+    api_url: str,
+    token: str,
+    repo_id: UUID,
+    timeout: float = 10.0,
+) -> int:
+    """Take back this user's queued runs in a repository; how many.
+
+    The web's "Stop queued runs", called by a studio on its way out: a run
+    queued for it is one nothing else will pick up, because presence is
+    one studio per user per repository. Runs only, never one a studio has
+    already taken — the endpoint's own rule. A short timeout, because the
+    caller is a process that has been asked to exit.
+    """
+    url = f"{api_url.rstrip('/')}/repositories/{repo_id}/recording-requests"
+    try:
+        response = httpx.delete(
+            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))
+    return int(response.json().get("cancelled", 0))
+
+
 def delete_recorded_test(
     *,
     api_url: str,

{verifaied-0.31.1.dev79 → verifaied-0.32.0.dev80}/src/verifaied/testcmd.py

@@ -125,6 +125,7 @@ from rich.table import Table
 
 from verifaied.client import (
     ApiError,
+    cancel_queued_runs,
     create_recorded_test,
     delete_recorded_test,
     get_browser_test_settings,
@@ -296,6 +297,39 @@ STEP_POST_MIN_INTERVAL = 0.5
 # the web reaches this machine, so an idle studio still has to call.
 HEARTBEAT_INTERVAL = 2.0
 
+# How a run stopped from the web closes. 130 is what a shell reports for a
+# process ended by an interrupt, which is the nearest honest number for "a
+# person ended this", and it is not 1 — so nothing reading the session can
+# mistake a stop for a spec that found a bug, and a retry loop that retries
+# exit 1 never replays a run somebody asked to end.
+STOPPED_EXIT_CODE = 130
+
+# The signals `test studio` treats as Ctrl-C: the terminal's own, its
+# hang-up when the window closes, and a plain `kill` or a make teardown.
+# Looked up by name, because this module is imported by every `verifaied`
+# command and Windows has no SIGHUP: naming it outright would make
+# `verifaied upload` die on import in a Windows CI job.
+STUDIO_SIGNALS: tuple[signal.Signals, ...] = tuple(
+    signum
+    for signum in (
+        getattr(signal, name, None) for name in ("SIGINT", "SIGTERM", "SIGHUP")
+    )
+    if signum is not None
+)
+STOPPED_MESSAGE = "Stopped from the web"
+# How a replay the studio was running closes when the studio itself is
+# interrupted (Ctrl-C, SIGTERM, the terminal closing). The web reads it by
+# these exact words.
+INTERRUPTED_STOP_MESSAGE = "Stopped: the studio was interrupted"
+
+# How long a stopped replay gets to exit on SIGTERM before it is killed.
+# Long enough for Playwright to close its browsers, short enough that the
+# page watching "Stopping…" is not left wondering.
+STOP_GRACE_SECONDS = 5.0
+
+# How often a stoppable child is checked on while it runs.
+STOP_POLL_SECONDS = 0.2
+
 # The faster beat while the studio's assistant is at work. Its steps
 # arrive one tool call at a time, each written after the last one's
 # verdict came back, and the pickup latency of an idle beat would be paid
@@ -530,15 +564,78 @@ def find_runner_dir(root: Path, explicit: Path | None = None) -> Path:
         raise RecordedTestError(str(e)) from e
 
 
+class RunStop(threading.Event):
+    """A request to stop a child, and whether it was actually carried out.
+
+    Setting it asks; ``honoured`` says the child was really stopped — its
+    group signalled, or it was never started. The two differ exactly when
+    a stop lands after the child had already exited on its own, and that
+    run's own exit code and evidence are the truth about it: a stop that
+    arrived too late must not turn a real pass or fail into "stopped".
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.honoured = False
+
+
 def run_process(
-    command: list[str], *, cwd: Path, env: dict[str, str] | None = None
+    command: list[str],
+    *,
+    cwd: Path,
+    env: dict[str, str] | None = None,
+    stop: RunStop | None = None,
+    grace: float = STOP_GRACE_SECONDS,
+    poll: float = STOP_POLL_SECONDS,
 ) -> int:
     """Run a child, inheriting stdio, and return its exit code.
 
     The single seam every subprocess in this module goes through, so tests
     can record the argv, cwd and env without ever launching ``npx``.
+
+    ``stop`` makes the child stoppable from another thread: it is started
+    in a **process group of its own** — ``npx`` is a wrapper around the
+    runner, which is a parent of the browsers, and signalling only the
+    first of them would leave the rest replaying — and when the event is
+    set the whole group gets SIGTERM, then SIGKILL after ``grace``
+    seconds. A stop that arrives before the child exists means it is
+    never started. Either way ``stop.honoured`` is set; a child that exits
+    on its own leaves it unset, however soon after the stop arrives.
+    Without ``stop`` it is the plain call it always was.
     """
-    return subprocess.call(command, cwd=str(cwd), env=env)
+    if stop is None:
+        return subprocess.call(command, cwd=str(cwd), env=env)
+    if stop.is_set():
+        stop.honoured = True
+        return STOPPED_EXIT_CODE
+    child = subprocess.Popen(command, cwd=str(cwd), env=env, start_new_session=True)
+    while True:
+        try:
+            return child.wait(timeout=poll)
+        except subprocess.TimeoutExpired:
+            if stop.is_set():
+                break
+    stop.honoured = _signal_group(child, signal.SIGTERM)
+    try:
+        return child.wait(timeout=grace)
+    except subprocess.TimeoutExpired:
+        _signal_group(child, signal.SIGKILL)
+        return child.wait()
+
+
+def _signal_group(child: subprocess.Popen[Any], signum: int) -> bool:
+    """Signal a child's whole process group; whether it was there to signal.
+
+    ``OSError`` rather than only ``ProcessLookupError``: macOS answers
+    ``killpg`` on a group whose leader has just become a zombie with
+    ``PermissionError``, and a group that is gone either way has nothing
+    left to stop — the child exited on its own, and says so by its code.
+    """
+    try:
+        os.killpg(child.pid, signum)
+    except OSError:
+        return False
+    return True
 
 
 ProcessRunner = Callable[..., int]
@@ -3816,6 +3913,7 @@ def replay_spec(
     progress_poster: Callable[..., None] = post_run_progress,
     replay_override: ReplayConfig | None = None,
     retry_follows: bool = False,
+    stop: RunStop | None = None,
 ) -> int:
     """Run one recorded spec and record everything it produced.
 
@@ -3882,6 +3980,15 @@ def replay_spec(
     that follows is the one the test's results row ends up pointing at,
     and uploading evidence nobody is shown would only slow the retry.
 
+    ``stop`` is how a studio ends this replay because somebody asked from
+    the web. Once it is set the runner is killed, and the run closes as
+    :data:`STOPPED_EXIT_CODE` with :data:`STOPPED_MESSAGE` — a failure, and
+    one that says why — with no step pinned and **no video or trace
+    uploaded**: the runner never got to finish writing them, and a
+    half-written video of a run somebody ended is not evidence of
+    anything. Coverage the browser already sent stays, because those lines
+    really did run.
+
     Returns the run's exit code — the spec's own, except that a clean run
     whose final coverage upload failed returns 2, because coverage nobody
     received looks exactly like coverage nobody produced, and so does a
@@ -4176,10 +4283,31 @@ def replay_spec(
                         console=console,
                         err_console=err_console,
                         flush_kwargs=flush_kwargs,
+                        stop=stop,
                     )
+                except KeyboardInterrupt:
+                    # The studio's Ctrl-C, SIGTERM or hang-up, with this
+                    # replay's group already killed: the session closes
+                    # saying so, rather than as a failure with no words.
+                    # Only a studio passes a stop; a terminal `test run`
+                    # interrupted by its own user says nothing extra.
+                    if stop is not None:
+                        failure_message = INTERRUPTED_STOP_MESSAGE
+                    raise
                 finally:
                     config.unlink(missing_ok=True)
-                if code != 0:
+                # Whether the child was really stopped, not whether a stop
+                # was asked for: one that lands after the runner exited on
+                # its own leaves that run's verdict and evidence standing.
+                stopped = stop is not None and stop.honoured
+                if stopped:
+                    # Whatever the runner exited with, it exited because it
+                    # was killed — its report, if it wrote one, describes a
+                    # run cut short rather than a step that failed.
+                    code = STOPPED_EXIT_CODE
+                    failure_message = STOPPED_MESSAGE
+                    console.print(f"[yellow]{STOPPED_MESSAGE}[/yellow] — {label}")
+                elif code != 0:
                     # Only on a failure, and inside the temp directory's
                     # lifetime — the report is deleted with it, and a passing
                     # run has neither a step to name nor anything to explain
@@ -4187,7 +4315,11 @@ def replay_spec(
                     failed_step, failure_message = failure_from_report(
                         report_file, run_spec.resolve(), line_map, secrets
                     )
-                if session_id is not None and not (code == 1 and retry_follows):
+                if (
+                    session_id is not None
+                    and not stopped
+                    and not (code == 1 and retry_follows)
+                ):
                     upload_artifacts(
                         new_artifacts_under(output_dir),
                         api_url=api_url,
@@ -4249,6 +4381,7 @@ def _run_playwright(
     err_console: Console,
     flush_kwargs: dict[str, Any],
     var_env: dict[str, str] | None = None,
+    stop: RunStop | None = None,
 ) -> int:
     """Run the spec in a worker thread, flushing coverage while it goes.
 
@@ -4262,6 +4395,14 @@ def _run_playwright(
     answered. Layered over this process's own environment rather than
     replacing it: the spec still needs PATH, and the machine's own
     variables are what a ``from_env`` was read out of in the first place.
+
+    ``stop`` is the web asking for this run to end. The runner is handed an
+    event of **this** function's own rather than ``stop`` itself, because
+    there are two reasons to kill a child that runs in its own process
+    group and only one of them is the web: Ctrl-C in the studio's terminal
+    no longer reaches the child directly, so an interrupt here kills it
+    too before being re-raised. Whether the kill was carried out is copied
+    back onto ``stop.honoured``, which is what the caller asks.
     """
     env = {
         **os.environ,
@@ -4278,24 +4419,43 @@ def _run_playwright(
         str(spec_path),
     ]
     result: dict[str, Any] = {}
+    kill = RunStop()
 
     def target() -> None:
         try:
-            result["code"] = runner(command, cwd=runner_dir, env=env)
+            if stop is None:
+                result["code"] = runner(command, cwd=runner_dir, env=env)
+            else:
+                result["code"] = runner(command, cwd=runner_dir, env=env, stop=kill)
         except OSError as e:
             result["error"] = e
 
     worker = threading.Thread(target=target)
     worker.start()
-    while worker.is_alive():
-        worker.join(timeout=interval)
-        if worker.is_alive():
-            _interval_flush(
+    if stop is None:
+        while worker.is_alive():
+            worker.join(timeout=interval)
+            if worker.is_alive():
+                _interval_flush(
+                    collector,
+                    console=console,
+                    err_console=err_console,
+                    flush_kwargs=flush_kwargs,
+                )
+    else:
+        _watch_stoppable(
+            worker,
+            stop=stop,
+            kill=kill,
+            interval=interval,
+            flush=lambda: _interval_flush(
                 collector,
                 console=console,
                 err_console=err_console,
                 flush_kwargs=flush_kwargs,
-            )
+            ),
+        )
+        stop.honoured = kill.honoured
     if "error" in result:
         raise RecordedTestError(
             f"could not run `npx` in {runner_dir}: {result['error']}. Node "
@@ -4304,6 +4464,47 @@ def _run_playwright(
     return int(result.get("code", 1))
 
 
+def _watch_stoppable(
+    worker: threading.Thread,
+    *,
+    stop: threading.Event,
+    kill: threading.Event,
+    interval: float,
+    flush: Callable[[], None],
+    clock: Callable[[], float] = time.monotonic,
+) -> None:
+    """Wait out a stoppable replay, passing a stop on and flushing as it goes.
+
+    Checked every :data:`STOP_POLL_SECONDS` rather than every flush
+    interval, so a stop reaches the child within a beat of the studio
+    hearing it — while coverage still goes up at the interval it always
+    did. Nothing is flushed once the child is being killed: the final
+    flush after it exits is the one that counts.
+
+    Ctrl-C lands here on the studio's main thread, and the child — in a
+    process group of its own — never hears it. So the interrupt kills the
+    child, waits for it to go, and is re-raised: the studio's own handling
+    of an interrupted request is unchanged, and no browser is orphaned.
+    """
+    last_flush = clock()
+    try:
+        while worker.is_alive():
+            if stop.is_set():
+                kill.set()
+            worker.join(timeout=min(interval, STOP_POLL_SECONDS))
+            if (
+                worker.is_alive()
+                and not kill.is_set()
+                and clock() - last_flush >= interval
+            ):
+                flush()
+                last_flush = clock()
+    except KeyboardInterrupt:
+        kill.set()
+        worker.join()
+        raise
+
+
 # --- driving the recorder ---------------------------------------------
 
 
@@ -8264,7 +8465,14 @@ def run_test_studio(
         "[dim]Leave this running. Ctrl-C stops it (a recording in progress "
         "is saved first).[/dim]"
     )
-    previous = signal.signal(signal.SIGINT, state.on_sigint)
+    # SIGTERM and SIGHUP are Ctrl-C too. A replay runs in a process group of
+    # its own so a web stop can end all of it — which also means the
+    # terminal's hang-up and a `kill -TERM -<studio pgid>` no longer reach
+    # it. Handling them exactly as Ctrl-C is what kills that group on the
+    # way out instead of leaving Playwright and its browsers running.
+    previous = {
+        signum: signal.signal(signum, state.on_sigint) for signum in STUDIO_SIGNALS
+    }
     beat_branch = branch
     try:
         while not state.shutdown:
@@ -8293,23 +8501,32 @@ def run_test_studio(
                 sleep(HEARTBEAT_INTERVAL)
                 continue
             request_id = UUID(str(request["id"]))
-
-            def busy_beat(branch_now: str | None = beat_branch) -> None:
+            # Set from the keeper's thread when a beat names this request
+            # among the runs somebody asked, from the web, to stop. Only a
+            # run is ever named — the service marks nothing else.
+            stop_asked = RunStop()
+
+            def busy_beat(
+                branch_now: str | None = beat_branch,
+                taken: UUID = request_id,
+                asked: RunStop = stop_asked,
+            ) -> None:
                 # Presence and nothing else, from the keeper's thread. The
                 # loop's own beat is what takes work; this one says "still
                 # here" while the loop is busy doing it. A blip is swallowed
                 # for the reason the loop swallows one — the next beat is
-                # seconds away. The branch is bound at definition: it is the
-                # one this request was taken on.
+                # seconds away. The branch, the request and its stop flag
+                # are bound at definition: they are this request's.
                 #
-                # Its acknowledgement is discarded, which is deliberate:
-                # the branch it names is registered server-side like any
-                # other beat's, but nothing is printed from this thread —
-                # a line arriving mid-recording, interleaved with the
+                # Nothing is printed from this thread: the branch it names
+                # is registered server-side like any other beat's, but a
+                # line arriving mid-recording, interleaved with the
                 # recorder's own output, is worse than one arriving on the
-                # loop's next beat.
+                # loop's next beat. The one thing read off its answer is a
+                # stop — this is the only beat a replaying studio sends, so
+                # it is the only one that can hear it.
                 try:
-                    post_recorder_heartbeat(
+                    ack = post_recorder_heartbeat(
                         api_url=api_url,
                         token=token,
                         repo_id=repo_id,
@@ -8317,9 +8534,14 @@ def run_test_studio(
                         kinds=list(STUDIO_KINDS),
                         environment=environment,
                         busy=True,
+                        # The run this beat vouches for: a run its studio
+                        # stops mentioning is stopped as disconnected.
+                        working=taken,
                     )
                 except ApiError:
-                    pass
+                    return
+                if str(taken) in {str(i) for i in ack.get("stop") or []}:
+                    asked.set()
 
             try:
                 # A server that predates runs sends no kind, and every
@@ -8335,7 +8557,7 @@ def run_test_studio(
                 with keeper(busy_beat):
                     kind = request.get("kind")
                     if kind in ("run", "run_headless"):
-                        _run_requested(
+                        cancelled = _run_requested(
                             request,
                             # A single Run is somebody sitting in front of
                             # this machine watching one flow; a whole folder
@@ -8358,6 +8580,7 @@ def run_test_studio(
                             env_name=env_name,
                             runner=runner,
                             shell_runner=shell_runner,
+                            stop=stop_asked,
                         )
                     elif kind == "amend":
                         _amend_requested(
@@ -8434,7 +8657,8 @@ def run_test_studio(
                 # A discarded recording is neither: nothing was saved, and
                 # nothing went wrong either, so it gets the ending that
                 # says exactly that rather than being flattened into one
-                # of the other two.
+                # of the other two — and so is a run stopped from the web,
+                # whose verdict ("Stopped from the web") is on its session.
                 post_recording_request_status(
                     api_url=api_url,
                     token=token,
@@ -8477,7 +8701,23 @@ def run_test_studio(
     except KeyboardInterrupt:
         pass
     finally:
-        signal.signal(signal.SIGINT, previous)
+        for signum, handler in previous.items():
+            signal.signal(signum, handler)
+        # Before the goodbye: a run queued for this studio has nothing else
+        # coming for it once it leaves, so it is taken back rather than left
+        # reading Queued. Best-effort — nothing here may hold up an exit;
+        # the service also takes them back when the goodbye lands.
+        try:
+            cancelled = cancel_queued_runs(
+                api_url=api_url, token=token, repo_id=repo_id
+            )
+        except ApiError:
+            cancelled = 0
+        if cancelled:
+            console.print(
+                f"[dim]Took back {cancelled} queued run"
+                f"{'' if cancelled == 1 else 's'} nothing is left to run.[/dim]"
+            )
         try:
             post_recorder_heartbeat(
                 api_url=api_url,
@@ -8758,7 +8998,8 @@ def _run_requested(
     runner: ProcessRunner,
     shell_runner: ShellRunner,
     env_name: str | None = None,
-) -> None:
+    stop: RunStop | None = None,
+) -> bool:
     """Replay the one test a heartbeat handed over.
 
     The same shape as :func:`_record_requested`, and for the same reasons:
@@ -8781,6 +9022,12 @@ def _run_requested(
     leaves the rest of this checkout's configuration standing; a request
     that names none at all — every run started from a terminal, and
     every row queued before this existed — reads as "the repo decides".
+
+    ``stop`` is set by the studio's presence thread when a beat says
+    somebody asked, from the web, for this run to end. Returns whether it
+    did, so the loop settles the request ``cancelled`` rather than
+    ``done``; a stop heard before the replay began means it never begins,
+    and no session is opened for a run nobody wants any more.
     """
     request_id = UUID(str(request["id"]))
     post_recording_request_status(
@@ -8810,6 +9057,10 @@ def _run_requested(
         "from the queue." + ("" if headed else " [dim](headless)[/dim]")
     )
     asked = request.get("video")
+    if stop is not None and stop.is_set():
+        console.print(f"[yellow]{STOPPED_MESSAGE}[/yellow] before it started.")
+        stop.honoured = True
+        return True
     replay_spec(
         api_url=api_url,
         token=token,
@@ -8847,7 +9098,12 @@ def _run_requested(
             if isinstance(asked, dict)
             else None
         ),
+        stop=stop,
     )
+    # Honoured, not merely asked: a stop that arrived after the replay
+    # ended on its own leaves a real verdict on the session, and the
+    # request says ``done`` for it like any finished run.
+    return stop is not None and stop.honoured
 
 
 def _fail_request(

{verifaied-0.31.1.dev79 → verifaied-0.32.0.dev80}/tests/test_client.py

@@ -19,6 +19,7 @@ from verifaied.client import (
     UploadResult,
     _http,
     _media_type,
+    cancel_queued_runs,
     clear_manual_coverage,
     create_recorded_test,
     create_session,
@@ -1420,6 +1421,29 @@ def test_post_recorder_heartbeat_marks_a_presence_only_beat(httpx_mock: HTTPXMoc
     }
 
 
+def test_post_recorder_heartbeat_names_the_run_a_busy_beat_is_on(
+    httpx_mock: HTTPXMock,
+):
+    httpx_mock.add_response(
+        method="POST", status_code=200, json={"request": None, "queue_depth": 0}
+    )
+    working = uuid4()
+    post_recorder_heartbeat(
+        api_url="http://api.test",
+        token="t",
+        repo_id=uuid4(),
+        branch="feature-a",
+        busy=True,
+        working=working,
+    )
+    assert json.loads(httpx_mock.get_request().content) == {
+        "branch": "feature-a",
+        "closing": False,
+        "busy": True,
+        "working": str(working),
+    }
+
+
 def test_post_recorder_heartbeat_raises_on_error(httpx_mock: HTTPXMock):
     httpx_mock.add_response(method="POST", status_code=404, json={"detail": "gone"})
     with pytest.raises(ApiError) as exc:
@@ -1503,6 +1527,36 @@ def test_post_recording_request_status_wraps_a_transport_failure(
     assert "could not reach" in exc.value.message
 
 
+def test_cancel_queued_runs_asks_the_stop_queued_runs_endpoint(
+    httpx_mock: HTTPXMock,
+):
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        method="DELETE",
+        url=f"http://api.test/repositories/{repo_id}/recording-requests",
+        status_code=200,
+        json={"cancelled": 3},
+    )
+    assert (
+        cancel_queued_runs(api_url="http://api.test/", token="t", repo_id=repo_id) == 3
+    )
+    assert httpx_mock.get_request().headers["Authorization"] == "Bearer t"
+
+
+def test_cancel_queued_runs_raises_on_a_refusal(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(method="DELETE", status_code=404, json={"detail": "gone"})
+    with pytest.raises(ApiError) as exc:
+        cancel_queued_runs(api_url="http://api.test", token="t", repo_id=uuid4())
+    assert (exc.value.status_code, exc.value.message) == (404, "gone")
+
+
+def test_cancel_queued_runs_raises_when_unreachable(httpx_mock: HTTPXMock):
+    httpx_mock.add_exception(httpx.ConnectError("refused"))
+    with pytest.raises(ApiError) as exc:
+        cancel_queued_runs(api_url="http://api.test", token="t", repo_id=uuid4())
+    assert exc.value.status_code == 0
+
+
 def test_delete_recorded_test_removes_the_row(httpx_mock: HTTPXMock):
     """The discard's other half: the machine that did the recording is
     what removes the row a first recording left behind."""