verifaied 0.21.1.dev45__tar.gz → 0.23.0.dev47__tar.gz

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verifaied
-Version: 0.21.1.dev45
+Version: 0.23.0.dev47
 Summary: Find what's untested in your code — locally, no account required
 Project-URL: Homepage, https://pypi.org/project/verifaied/
 Author: Kyle Richards

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/pyproject.toml

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

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/src/verifaied/cli.py

@@ -142,10 +142,12 @@ def upload_command(
         False,
         "--browser",
         help=(
-            "Upload as browser-session coverage (the independent 'which code "
-            "was exercised in a browser' dimension) instead of test-suite "
-            "coverage. Accepts Istanbul (frontend harvest) or pytest-cov "
-            "(coverage-instrumented backend); incompatible with --junit."
+            "Upload as browser coverage (the independent 'which code was "
+            "exercised in a browser' dimension) instead of test-suite "
+            "coverage. Counts as this branch's suite run, replacing what the "
+            "last wrapped run contributed and nothing else. Accepts Istanbul "
+            "(frontend harvest) or pytest-cov (coverage-instrumented "
+            "backend); incompatible with --junit."
         ),
     ),
     commit_sha: str | None = typer.Option(
@@ -523,9 +525,10 @@ def clear_manual_command(
     accumulation and start fresh: every function goes back to Unexercised,
     but the Manual Recording view stays visible.
 
-    The e2e dimension (`verifaied upload --browser`, or
-    `verifaied collect -- <cmd>`) has no clear: each run replaces the
-    previous one, so that column always shows the latest.
+    Browser coverage (`verifaied upload --browser`, `verifaied test run`, or
+    `verifaied collect -- <cmd>`) has no clear: it is the union of what each
+    producer last reached, and every producer replaces its own contribution
+    on its next run.
 
     Exit codes:
       0  cleared
@@ -809,13 +812,14 @@ def record_command(
     arrived.
 
     The two modes feed two different dimensions, because they answer
-    different questions. Wrapping a command uploads as **e2e**: a suite run
-    is a complete snapshot, so each run **replaces** the last and the
-    Browser Tests column on the branch view always shows the current one —
-    there is nothing to clear. A bare session uploads as **manual**: a
-    person covers a flow, stops, comes back, so those **accumulate** on the
-    Manual Recording page until ``verifaied clear-manual`` starts a fresh
-    pass.
+    different questions. Wrapping a command uploads as this branch's
+    **suite** contribution to its Browser coverage: a suite run is a
+    complete snapshot of itself, so each wrapped run **replaces** the last
+    one's contribution — and nothing else's, so replaying a single recorded
+    test never withdraws it. There is nothing to clear. A bare session
+    uploads as **manual**: a person covers a flow, stops, comes back, so
+    those **accumulate** on the Manual Recording page until
+    ``verifaied clear-manual`` starts a fresh pass.
 
     For a repeatable, named flow, use ``verifaied test record`` instead —
     it drives Playwright's recorder through verifAIed's own driver, saves
@@ -1728,12 +1732,20 @@ def test_run_command(
         metavar="[[<feature path>/]<name>]",
         help=(
             'Which test to run, e.g. "Settings/API tokens". The feature path '
-            "is optional and may nest. Omit with --all."
+            "is optional and may nest. Omit with --all or --folder."
         ),
     ),
     run_all: bool = typer.Option(
         False, "--all", help="Run every recorded test, in order, and report the worst."
     ),
+    folder: str | None = typer.Option(
+        None,
+        "--folder",
+        help=(
+            'Run every recorded test under one folder, e.g. --folder "Settings" '
+            "— nested folders included."
+        ),
+    ),
     proxy: bool = typer.Option(
         False,
         "--proxy",
@@ -1822,11 +1834,20 @@ def test_run_command(
 ) -> None:
     """Replay a recorded test, capturing video, trace and coverage.
 
+    Three forms, exactly one at a time: a test by name, ``--folder
+    "<folder path>"`` for everything nested under one folder, or ``--all``
+    for every recorded test in the repository. A folder is matched the way a
+    name is — by slug — so it is the same path the web composes.
+
     Each run opens a session on the branch, so the video and the lines it
     reached sit together in verifAIed, and the run's pass/fail becomes the
     branch's answer for that test — which is what clears the
     ``unverified_recorded_test`` gap in ``check_done``.
 
+    The coverage becomes **this test's** contribution to the branch's
+    Browser coverage, replacing what the same test last reached and never
+    touching the suite's or another test's.
+
     ``--env`` picks which environment from ``.verifaied/config.toml``
     every spec in this run is pointed at: its ``base_url`` becomes
     Playwright's ``baseURL``, its ``reset`` runs before **each** spec so
@@ -1840,7 +1861,7 @@ def test_run_command(
       0  every test replayed cleanly
       *  the worst exit code across the run
       2  a run was clean but its final coverage upload failed
-      1  usage / config error (no token, unknown test, no Playwright)
+      1  usage / config error (no token, unknown test or folder, no Playwright)
     """
     resolved_url, resolved_token, repo_id = _test_prelude(
         repo=repo, api_url=api_url, token=token
@@ -1855,6 +1876,7 @@ def test_run_command(
             commit_sha=commit_sha,
             ref=ref,
             run_all=run_all,
+            folder=folder,
             runner_dir=runner_dir,
             port=port,
             interval=interval,

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/src/verifaied/client.py

@@ -785,10 +785,11 @@ def clear_manual_coverage(
     """DELETE the accumulated manual dimension for a (repo, branch).
 
     Manual `collect` sessions accumulate server-side; this resets them so
-    the next pass starts fresh. The e2e dimension is untouched — it is
-    replaced by each run and has no clear. Returns the parsed response
-    (``{cleared_functions}``). Raises ``ApiError`` on any non-2xx — a 404
-    means the branch has no local analysis to clear.
+    the next pass starts fresh. Browser coverage is untouched — every
+    producer there replaces its own contribution, so it has no clear.
+    Returns the parsed response (``{cleared_functions}``). Raises
+    ``ApiError`` on any non-2xx — a 404 means the branch has no local
+    analysis to clear.
     """
     url = f"{api_url.rstrip('/')}/repositories/{repo_id}/manual-coverage"
     try:

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/src/verifaied/record.py

@@ -336,11 +336,13 @@ def flush_upload(
 ) -> UploadResult | None:
     """Upload the merged state as session coverage, if it changed.
 
-    ``coverage_kind`` picks the dimension: ``"browser"`` (the e2e one) when
-    this collector is wrapping a suite command, ``"manual"`` for a bare
-    interactive session. They differ server-side — e2e replaces per run,
-    manual accumulates until cleared — which is exactly the difference
-    between "a suite just ran" and "someone is clicking around".
+    ``coverage_kind`` picks the dimension: ``"browser"`` when this collector
+    is wrapping a suite command, ``"manual"`` for a bare interactive
+    session. They differ server-side — a browser upload becomes this
+    branch's suite contribution, replacing what the last wrapped run
+    contributed and nothing else, while manual accumulates until cleared —
+    which is exactly the difference between "a suite just ran" and "someone
+    is clicking around".
 
     Returns None when nothing new arrived since the last *successful*
     upload. The merged JSON goes through a tempfile so the existing
@@ -396,9 +398,9 @@ def flush_upload(
 def format_upload_summary(result: UploadResult, coverage_kind: str = "manual") -> str:
     """One line per upload: what *this* session's dimension now looks like.
 
-    A session must report its own numbers. Printing the e2e counts after a
-    hand-driven pass would tell the operator their clicking had no effect —
-    the two dimensions move independently by design.
+    A session must report its own numbers. Printing the branch's browser
+    counts after a hand-driven pass would tell the operator their clicking
+    had no effect — the two dimensions move independently by design.
     """
     if coverage_kind == "browser":
         exercised = result.browser_exercised_count
@@ -1103,10 +1105,10 @@ def run_record(
     flow), exiting 0 — or 2 if the final upload failed. Uploads as the
     **manual** dimension.
 
-    With ``command``: run it with the collector alongside (the e2e flow,
+    With ``command``: run it with the collector alongside (the suite flow,
     ``verifaied collect -- npx playwright test``), then flush and exit with
     the command's own code, so the wrapper is transparent to CI. Uploads as
-    the **e2e** dimension.
+    this branch's **suite** contribution to its browser coverage.
 
     ``port=None`` resolves per mode: the reporter's fixed default for a
     bare session, an ephemeral port for a wrapped one.
@@ -1138,12 +1140,14 @@ def run_record(
     thread = threading.Thread(target=server.serve_forever, daemon=True)
     thread.start()
 
-    # Wrapping a command means a suite just ran, which is the e2e
-    # dimension (replaced per run). A bare session is a person clicking
-    # around, which is the manual one (accumulated until cleared). The mode
-    # already tells us which, so the user never has to.
+    # Wrapping a command means a suite just ran, which is the branch's
+    # suite contribution to its browser coverage (replacing what the last
+    # wrapped run contributed, and nothing else's). A bare session is a
+    # person clicking around, which is the manual dimension (accumulated
+    # until cleared). The mode already tells us which, so the user never
+    # has to.
     coverage_kind = "browser" if command else "manual"
-    dimension = "e2e" if command else "manual"
+    dimension = "suite" if command else "manual"
     console.print(
         f"[green]Recording[/green] {dimension} browser coverage on "
         f"[bold]http://{HOST}:{bound_port}[/bold] → branch "
@@ -1154,8 +1158,8 @@ def run_record(
         console.print(
             f"[dim]Running: {' '.join(command)} "
             f"(VITE_COVERAGE=true, VERIFAIED_RECORD_PORT={bound_port}). "
-            "Results land in the Browser Tests column of the branch "
-            "view.[/dim]"
+            "Results land on the branch's Browser coverage page as the "
+            "suite's contribution.[/dim]"
         )
     elif not proxy:
         console.print(

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/src/verifaied/testcmd.py

@@ -189,7 +189,7 @@ RUN_PROGRESS_MIN_INTERVAL = 0.5
 # the whole compatibility contract in one place: a CLI that predates runs
 # sends no field at all, is stored as record-only, and never takes a run
 # it would not know how to answer.
-STUDIO_KINDS: tuple[str, ...] = ("record", "run", "edit", "amend")
+STUDIO_KINDS: tuple[str, ...] = ("record", "run", "run_headless", "edit", "amend")
 
 # ``major.minor`` prefixes of ``@playwright/test`` the recorder driver has
 # been verified against. **Fail-closed**: the driver reaches an internal
@@ -2828,9 +2828,14 @@ def replay_spec(
 
     This is where a recorded test becomes evidence: the spec runs with
     video and trace on, under the coverage collector, against a session
-    linked to the test. Video, trace and browser coverage all land on that
-    session, and the session's exit code becomes the branch's pass/fail for
-    the test when it closes.
+    linked to the test. Video, trace and coverage all land on that session,
+    and the session's exit code becomes the branch's pass/fail for the test
+    when it closes.
+
+    The coverage becomes **this test's** contribution to the branch's
+    browser coverage, replacing what the same test last reached and never
+    touching the suite's or another test's — which is what makes "wrap your
+    suite" and "run this test" two remedies that no longer undo each other.
 
     With pre-steps, what actually runs is a **composed** spec — their
     bodies then this one, in a throwaway file — and the coverage that
@@ -3223,8 +3228,8 @@ def _run_playwright(
 
     The child runs on a thread rather than in the foreground so the
     collector can upload on an interval — a long flow's coverage shouldn't
-    all land in one lump at the end, and the Browser Tests column filling
-    in as the replay proceeds is what makes a slow run legible.
+    all land in one lump at the end, and the branch's Browser coverage
+    filling in as the replay proceeds is what makes a slow run legible.
 
     ``var_env`` is the selected environment's variables, which is where a
     normalized spec's ``process.env.VERIFAIED_VAR_*`` references are
@@ -6801,9 +6806,16 @@ def run_test_studio(
                 # against a service that hasn't been deployed yet.
                 cancelled = False
                 with keeper(busy_beat):
-                    if request.get("kind") == "run":
+                    kind = request.get("kind")
+                    if kind in ("run", "run_headless"):
                         _run_requested(
                             request,
+                            # A single Run is somebody sitting in front of
+                            # this machine watching one flow; a whole folder
+                            # or a whole branch is not, and forty windows
+                            # opening in front of them is why nobody would
+                            # click it twice.
+                            headed=kind == "run",
                             api_url=api_url,
                             token=token,
                             repo_id=repo_id,
@@ -6820,7 +6832,7 @@ def run_test_studio(
                             runner=runner,
                             shell_runner=shell_runner,
                         )
-                    elif request.get("kind") == "amend":
+                    elif kind == "amend":
                         _amend_requested(
                             request,
                             api_url=api_url,
@@ -6840,7 +6852,7 @@ def run_test_studio(
                             runner=runner,
                             shell_runner=shell_runner,
                         )
-                    elif request.get("kind") == "edit":
+                    elif kind == "edit":
                         cancelled = _edit_requested(
                             request,
                             api_url=api_url,
@@ -7185,6 +7197,7 @@ def _amend_requested(
 def _run_requested(
     request: dict[str, Any],
     *,
+    headed: bool,
     api_url: str,
     token: str,
     repo_id: UUID,
@@ -7201,7 +7214,7 @@ def _run_requested(
     shell_runner: ShellRunner,
     env_name: str | None = None,
 ) -> None:
-    """Replay the one test a heartbeat handed over, headed.
+    """Replay the one test a heartbeat handed over.
 
     The same shape as :func:`_record_requested`, and for the same reasons:
     ``recording`` goes out first because replaying a chain of pre-steps can
@@ -7209,10 +7222,13 @@ def _run_requested(
     it otherwise, and the rows are re-listed rather than trusted from the
     request, because the spec path and the stored chain live on the row.
 
-    Headed, unlike ``verifaied test run``: somebody clicked Run and is
-    sitting in front of this machine, so watching the browser do it is the
-    point. The run's own verdict lands on the session as it always does —
-    this reports only that the replay happened.
+    ``headed`` is the whole difference between the two run kinds. A single
+    Run is somebody clicking one test and sitting in front of this machine,
+    so watching the browser do it is the point; a folder or a whole branch
+    queued at once is nobody watching, and opening forty windows in front of
+    them would be the reason they never clicked it again. The run's own
+    verdict lands on the session either way — this reports only that the
+    replay happened.
     """
     request_id = UUID(str(request["id"]))
     post_recording_request_status(
@@ -7239,7 +7255,7 @@ def _run_requested(
     console.print(
         f"[green]Running[/green] "
         f"[bold]{ref_of(test['feature'], test['name'])}[/bold] "
-        "from the queue."
+        "from the queue." + ("" if headed else " [dim](headless)[/dim]")
     )
     replay_spec(
         api_url=api_url,
@@ -7258,7 +7274,7 @@ def _run_requested(
         console=console,
         err_console=err_console,
         all_rows=rows,
-        headed=True,
+        headed=headed,
         env_name=env_name,
         runner=runner,
         shell_runner=shell_runner,
@@ -7291,6 +7307,34 @@ def _fail_request(
         err_console.print(f"[yellow]could not report the failure[/yellow]: {e}")
 
 
+def in_folder(row: dict[str, Any], folder_slug: str) -> bool:
+    """Whether one listed test lives under a folder, at any depth.
+
+    Matched on the **slug**, the way :func:`find_test` matches a name, so
+    ``--folder "API tokens"`` and ``--folder api-tokens`` are the same
+    folder — and so the flag agrees with the path the web composes.
+
+    Nested tests count: a folder is a place, and "run Settings" meaning "but
+    not the tests in Settings/Tokens" is a distinction nobody drew when they
+    filed them there. The ``/`` in the prefix test is what keeps
+    ``settings-api`` out of ``settings``.
+    """
+    slug = str(row.get("feature_slug") or "")
+    return slug == folder_slug or slug.startswith(f"{folder_slug}/")
+
+
+def no_folder_match(folder: str, rows: list[dict[str, Any]]) -> str:
+    """What to say when ``--folder`` named nothing that can be run.
+
+    The folders that do exist are the fix, so they are the message: a typo
+    is answered by the list the user meant to pick from rather than by
+    "nothing matched".
+    """
+    folders = sorted({str(row.get("feature") or "") for row in rows} - {""})
+    known = ", ".join(folders) if folders else "none yet"
+    return f'no recorded tests under "{folder}" — the folders here are: {known}'
+
+
 def run_test_run(
     *,
     api_url: str,
@@ -7301,6 +7345,7 @@ def run_test_run(
     commit_sha: str | None,
     ref: str | None,
     run_all: bool,
+    folder: str | None = None,
     runner_dir: Path | None,
     port: int,
     interval: float,
@@ -7313,7 +7358,13 @@ def run_test_run(
     runner: ProcessRunner = run_process,
     shell_runner: ShellRunner = run_shell_process,
 ) -> int:
-    """Replay one recorded test, or every ready one.
+    """Replay one recorded test, every ready one, or a folder of them.
+
+    Exactly one of the three says what to run: a name, ``--all``, or
+    ``--folder "<path>"``. A folder is matched by **slug**, the way a name
+    is, and it takes everything nested under it — a folder is a place, and
+    "run Settings" meaning "not the tests in Settings/Tokens" would be a
+    distinction nobody drew when they filed them there.
 
     Returns the **worst** exit code across the run: one broken flow in ten
     is a failure, and reporting the last one's code would let it hide
@@ -7329,24 +7380,40 @@ def run_test_run(
     one answer for the whole invocation, because "--all against stage"
     is one question.
     """
-    if (ref is None) == (not run_all):
+    chosen = sum((ref is not None, run_all, folder is not None))
+    if chosen != 1:
         raise RecordedTestError(
-            'name a test — `verifaied test run "<feature path>/<name>"` — '
-            "or pass --all to run every recorded test"
+            "say what to run, and only one of the three: name a test — "
+            '`verifaied test run "<feature path>/<name>"` — or pass '
+            '--folder "<folder path>" for everything under one folder, or '
+            "--all for every recorded test"
+        )
+    # Before the listing, because it is a question about the flag rather
+    # than about the repo: ``slugify_feature_path("")`` is ``""``, which
+    # matches the rootless tests and nothing else — a silent answer to a
+    # question the user did not ask.
+    if folder is not None and not folder.strip():
+        raise RecordedTestError(
+            "`--folder` needs a folder path; use --all to run every recorded test"
         )
     resolved_branch = branch if branch is not None else detect_branch()
     resolved_runner_dir = find_runner_dir(root, runner_dir)
     rows = list_recorded_tests(
         api_url=api_url, token=token, repo_id=repo_id, branch=resolved_branch
     )
-    if run_all:
+    if run_all or folder is not None:
         ready = [r for r in rows if r.get("status") == "ready"]
+        if folder is not None:
+            folder_slug = slugify_feature_path(folder)
+            scoped = [r for r in ready if in_folder(r, folder_slug)]
+        else:
+            scoped = ready
         # Suite rows are born ready, so they would otherwise be swept up
         # by --all and replayed under a config that isn't theirs — see
         # ``suite_origin_error`` for why that is destructive rather than
         # merely useless.
-        targets = [r for r in ready if not is_suite_row(r)]
-        skipped = len(ready) - len(targets)
+        targets = [r for r in scoped if not is_suite_row(r)]
+        skipped = len(scoped) - len(targets)
         if skipped:
             console.print(
                 f"[dim]Skipping {skipped} test(s) tracked from your Playwright "
@@ -7354,6 +7421,12 @@ def run_test_run(
                 "`verifaied collect`.[/dim]"
             )
         if not targets:
+            if folder is not None:
+                # A named folder with nothing in it is a typo far more often
+                # than it is an empty folder, so it is a refusal rather than
+                # the clean zero ``--all`` answers with — and it names the
+                # folders that do exist, which is the fix.
+                raise RecordedTestError(no_folder_match(folder, rows))
             console.print(
                 "[dim]No recorded tests to run yet — record one with "
                 '`verifaied test record "<Feature path>/<Name>" --url <url>`. '

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/tests/test_record.py

@@ -1160,12 +1160,13 @@ def test_wrapped_session_says_where_the_results_land(
         err_console=MagicMock(),
     )
     printed = " ".join(str(c) for c in console.print.call_args_list)
-    assert "e2e browser coverage" in printed
-    assert "Browser Tests column" in printed
+    assert "suite browser coverage" in printed
+    assert "Browser coverage page as the suite's contribution" in printed
 
 
 def test_summary_reports_the_session_s_own_dimension():
-    """A hand-driven pass must not be told the e2e numbers — the two move
+    """A hand-driven pass must not be told the branch's browser numbers — the
+    two move
     independently, and reporting the wrong one reads as "your clicking did
     nothing"."""
     result = _result(

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/tests/test_testcmd.py

@@ -2523,11 +2523,131 @@ def test_run_refuses_a_draft_and_names_the_record_command(tmp_path: Path):
         _run(tmp_path, rows=[_test_row(status="draft")], codes=[0])
 
 
-def test_run_needs_exactly_one_of_a_ref_or_all(tmp_path: Path):
-    with pytest.raises(RecordedTestError, match="--all"):
-        _run(tmp_path, rows=[], codes=[], ref=None, run_all=False)
-    with pytest.raises(RecordedTestError, match="--all"):
-        _run(tmp_path, rows=[], codes=[], ref="Settings/API tokens", run_all=True)
+def test_run_needs_exactly_one_of_a_ref_all_or_folder(tmp_path: Path):
+    """Three ways to say what to run, and saying two of them is as much a
+    usage error as saying none."""
+    for overrides in (
+        {"ref": None, "run_all": False},
+        {"ref": "Settings/API tokens", "run_all": True},
+        {"ref": "Settings/API tokens", "folder": "Settings"},
+        {"ref": None, "run_all": True, "folder": "Settings"},
+    ):
+        with pytest.raises(RecordedTestError, match="--folder") as excinfo:
+            _run(tmp_path, rows=[], codes=[], **overrides)
+        assert "--all" in str(excinfo.value)
+
+
+def test_run_folder_replays_everything_nested_under_it(tmp_path: Path):
+    """A folder is a place: "run Settings" including Settings/Tokens is
+    what anybody filing a test there meant."""
+    top = _test_row(
+        feature="Settings", name="Profile", feature_slug="settings", name_slug="profile"
+    )
+    nested = _test_row(
+        feature="Settings/Tokens",
+        name="Revoke",
+        feature_slug="settings/tokens",
+        name_slug="revoke",
+    )
+    elsewhere = _test_row(
+        feature="Settings-api",
+        name="Ping",
+        feature_slug="settings-api",
+        name_slug="ping",
+    )
+    rootless = _test_row(feature="", name="Log in", feature_slug="", name_slug="log-in")
+
+    code, replayed = _run(
+        tmp_path,
+        rows=[top, nested, elsewhere, rootless],
+        codes=[0, 0],
+        ref=None,
+        folder="Settings",
+    )
+
+    assert code == 0
+    assert [c.kwargs["test"] for c in replayed.call_args_list] == [top, nested]
+
+
+def test_run_folder_matches_on_the_slug(tmp_path: Path):
+    """The same rule `find_test` uses for a name, so the flag agrees with
+    the path the web composes."""
+    row = _test_row(
+        feature="API tokens",
+        name="Revoke",
+        feature_slug="api-tokens",
+        name_slug="revoke",
+    )
+
+    code, replayed = _run(
+        tmp_path, rows=[row], codes=[0], ref=None, folder="api-tokens"
+    )
+
+    assert code == 0
+    assert replayed.call_args.kwargs["test"] is row
+
+
+def test_run_folder_skips_drafts_and_suite_rows(tmp_path: Path):
+    console = _console()
+    ready = _test_row(
+        feature="Settings", name="Profile", feature_slug="settings", name_slug="profile"
+    )
+    draft = _test_row(
+        feature="Settings",
+        name="Later",
+        feature_slug="settings",
+        name_slug="later",
+        status="draft",
+    )
+    suite = _test_row(
+        feature="Settings",
+        name="Their own",
+        feature_slug="settings",
+        name_slug="their-own",
+        origin="suite",
+    )
+
+    code, replayed = _run(
+        tmp_path,
+        rows=[ready, draft, suite],
+        codes=[0],
+        ref=None,
+        folder="Settings",
+        console=console,
+    )
+
+    assert code == 0
+    assert [c.kwargs["test"] for c in replayed.call_args_list] == [ready]
+    printed = " ".join(str(c.args[0]) for c in console.print.call_args_list)
+    assert "Skipping 1 test(s) tracked from your Playwright suite" in printed
+
+
+def test_run_folder_with_no_match_refuses_and_names_the_folders(tmp_path: Path):
+    """A typo is not a clean zero, unlike --all: the folders that do exist
+    are the fix, so they are the message."""
+    rows = [
+        _test_row(
+            feature="Settings/Tokens",
+            name="Revoke",
+            feature_slug="settings/tokens",
+            name_slug="revoke",
+        ),
+        _test_row(feature="", name="Log in", feature_slug="", name_slug="log-in"),
+    ]
+
+    with pytest.raises(RecordedTestError) as excinfo:
+        _run(tmp_path, rows=rows, codes=[], ref=None, folder="Setings")
+
+    assert str(excinfo.value) == (
+        'no recorded tests under "Setings" — the folders here are: Settings/Tokens'
+    )
+
+
+def test_run_folder_refuses_a_blank_path_before_it_slugs_it(tmp_path: Path):
+    """`slugify_feature_path("")` is `""`, which matches the rootless
+    tests and nothing else — an answer to a question nobody asked."""
+    with pytest.raises(RecordedTestError, match="needs a folder path"):
+        _run(tmp_path, rows=[_test_row()], codes=[], ref=None, folder="   ")
 
 
 def test_run_all_skips_drafts_and_reports_the_worst_code(tmp_path: Path):
@@ -2778,6 +2898,28 @@ def test_test_run_command_forwards_all(monkeypatch):
     assert run.call_args.kwargs["branch"] == "feature-a"
 
 
+def test_test_run_command_forwards_the_folder(monkeypatch):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    with patch("verifaied.cli.run_test_run", return_value=0) as run:
+        result = runner.invoke(
+            app,
+            [
+                "test",
+                "run",
+                "--folder",
+                "Settings/Tokens",
+                "--repo",
+                str(uuid4()),
+                "--api-url",
+                "http://api.test",
+            ],
+        )
+    assert result.exit_code == 0
+    assert run.call_args.kwargs["folder"] == "Settings/Tokens"
+    assert run.call_args.kwargs["run_all"] is False
+    assert run.call_args.kwargs["ref"] is None
+
+
 def test_test_run_command_propagates_the_worst_code(monkeypatch):
     monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
     with patch("verifaied.cli.run_test_run", return_value=3):
@@ -8580,7 +8722,7 @@ def test_studio_declares_every_kind_on_every_beat(tmp_path: Path):
     """The service claims only what a studio says it can do, so this is
     the whole compatibility contract in one field."""
     studio = _studio(tmp_path, acks=[_ack()])
-    assert STUDIO_KINDS == ("record", "run", "edit", "amend")
+    assert STUDIO_KINDS == ("record", "run", "run_headless", "edit", "amend")
     working = [beat for beat in studio.beats if not beat.get("closing")]
     assert working
     assert all(beat["kinds"] == list(STUDIO_KINDS) for beat in working)
@@ -8608,6 +8750,25 @@ def test_studio_replays_a_run_request_headed_and_records_nothing(
     assert [s["status"] for s in studio.statuses] == ["recording", "done"]
 
 
+def test_studio_replays_a_headless_run_request_with_no_window(tmp_path: Path):
+    """A batch is nobody watching, and forty windows opening in front of
+    somebody is the reason they would never click it twice."""
+    row = _test_row()
+    studio = _studio(
+        tmp_path,
+        acks=[_ack(_studio_request(row["id"], kind="run_headless"))],
+        rows=[row],
+    )
+
+    assert studio.records == []
+    assert len(studio.replays) == 1
+    call = studio.replays[0]
+    assert call["headed"] is False
+    assert call["driver"] == "suite"
+    assert call["test"] is row
+    assert [s["status"] for s in studio.statuses] == ["recording", "done"]
+
+
 def test_studio_reports_done_for_a_run_that_failed_its_assertions(
     tmp_path: Path,
 ):

{verifaied-0.21.1.dev45 → verifaied-0.23.0.dev47}/uv.lock

@@ -442,7 +442,7 @@ wheels = [
 
 [[package]]
 name = "verifaied"
-version = "0.21.1"
+version = "0.23.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },