verifaied 0.28.0.dev74__tar.gz → 0.29.0.dev76__tar.gz

{verifaied-0.28.0.dev74 → verifaied-0.29.0.dev76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: verifaied
-Version: 0.28.0.dev74
+Version: 0.29.0.dev76
 Summary: Find what's untested in your code — locally, no account required
 Project-URL: Homepage, https://pypi.org/project/verifaied/
 Author: Kyle Richards
@@ -257,6 +257,50 @@ supported shapes.
   uploaded, then exit without contacting the backend. Skips the token
   requirement so you can audit without configuring auth.
 
+## `verifaied collect` — browser coverage from any session
+
+Measures how much of your app a browser session reached, and uploads it
+as it runs. Nothing in a page ever posts anything: the coverage is read
+out of the browser from Node, so an instrumented tab never makes a
+request of its own and never has one refused in its console.
+
+```bash
+# Wrap your e2e suite: the Playwright fixture posts each page's coverage
+# here as the suite runs. Exits with the suite's own code.
+verifaied collect --root . -- npx playwright test
+
+# Or collect by hand: a browser window opens at your app, and every page
+# you click through in it is read from the outside. Close the window or
+# press Ctrl-C to finish.
+verifaied collect --root . --url http://localhost:5173
+```
+
+A wrapped run uploads as the branch's **suite** contribution; a bare
+session uploads as the **manual** dimension, which accumulates until
+`verifaied clear-manual`. Pages in any browser other than the window it
+opened are not collected, by design.
+
+### `collect` flags
+
+- `--url <url>` — where the window a bare session opens should start
+  (default: the proxy when `--proxy` is set, else `base_url` from
+  `.verifaied/config.toml`)
+- `--browser / --no-browser` — open the window (default), or only listen
+  for a harvester of your own posting from Node
+- `--runner-dir <dir>` — where `@playwright/test` is installed, for the
+  window (default: found under `--root` and the repo root)
+- `--port <n>` — collector port, 127.0.0.1 only (default: 4571 for a bare
+  session, any free port when wrapping a command)
+- `--interval <seconds>` — seconds between uploads (default: 10)
+- `--proxy` / `--proxy-target <origin>` / `--proxy-port <n>` — instrument
+  an app with no build step through a local proxy; the window opens at
+  the proxy, because only pages loaded through it are instrumented
+- `--driver <human|agent|suite>` — who drove, for the session ledger
+- `--test-results <dir>` — where a wrapped run leaves Playwright traces
+  and screenshots to attach (default: `./test-results`)
+- `--repo / -r`, `--branch / -b`, `--root <dir>`, `--commit-sha`,
+  `--env <name>`, `--api-url`, `--token` — as for `upload`
+
 ## `verifaied check-done` — the "am I done?" gate
 
 `check-done` is the **stop condition** for an agent's test-writing loop.
@@ -956,7 +1000,9 @@ Shared by `record`, `run` and `studio`:
 - `--root <dir>` — repo root the spec paths resolve against (default: cwd)
 - `--runner-dir <dir>` — where to run `npx playwright` from (default: the
   first directory under `--root` with `@playwright/test` installed)
-- `--port <n>` — coverage collector port, 127.0.0.1 only (default: 4571)
+- `--port <n>` — pin the coverage collector's port, 127.0.0.1 only
+  (default: any free one; a replay's harvest reads the bound port from its
+  own environment)
 - `--interval <seconds>` — seconds between coverage uploads during a
   replay (default: 10)
 - `--env <name>` — which environment from `.verifaied/config.toml` to run

{verifaied-0.28.0.dev74 → verifaied-0.29.0.dev76}/README.md

@@ -211,6 +211,50 @@ supported shapes.
   uploaded, then exit without contacting the backend. Skips the token
   requirement so you can audit without configuring auth.
 
+## `verifaied collect` — browser coverage from any session
+
+Measures how much of your app a browser session reached, and uploads it
+as it runs. Nothing in a page ever posts anything: the coverage is read
+out of the browser from Node, so an instrumented tab never makes a
+request of its own and never has one refused in its console.
+
+```bash
+# Wrap your e2e suite: the Playwright fixture posts each page's coverage
+# here as the suite runs. Exits with the suite's own code.
+verifaied collect --root . -- npx playwright test
+
+# Or collect by hand: a browser window opens at your app, and every page
+# you click through in it is read from the outside. Close the window or
+# press Ctrl-C to finish.
+verifaied collect --root . --url http://localhost:5173
+```
+
+A wrapped run uploads as the branch's **suite** contribution; a bare
+session uploads as the **manual** dimension, which accumulates until
+`verifaied clear-manual`. Pages in any browser other than the window it
+opened are not collected, by design.
+
+### `collect` flags
+
+- `--url <url>` — where the window a bare session opens should start
+  (default: the proxy when `--proxy` is set, else `base_url` from
+  `.verifaied/config.toml`)
+- `--browser / --no-browser` — open the window (default), or only listen
+  for a harvester of your own posting from Node
+- `--runner-dir <dir>` — where `@playwright/test` is installed, for the
+  window (default: found under `--root` and the repo root)
+- `--port <n>` — collector port, 127.0.0.1 only (default: 4571 for a bare
+  session, any free port when wrapping a command)
+- `--interval <seconds>` — seconds between uploads (default: 10)
+- `--proxy` / `--proxy-target <origin>` / `--proxy-port <n>` — instrument
+  an app with no build step through a local proxy; the window opens at
+  the proxy, because only pages loaded through it are instrumented
+- `--driver <human|agent|suite>` — who drove, for the session ledger
+- `--test-results <dir>` — where a wrapped run leaves Playwright traces
+  and screenshots to attach (default: `./test-results`)
+- `--repo / -r`, `--branch / -b`, `--root <dir>`, `--commit-sha`,
+  `--env <name>`, `--api-url`, `--token` — as for `upload`
+
 ## `verifaied check-done` — the "am I done?" gate
 
 `check-done` is the **stop condition** for an agent's test-writing loop.
@@ -910,7 +954,9 @@ Shared by `record`, `run` and `studio`:
 - `--root <dir>` — repo root the spec paths resolve against (default: cwd)
 - `--runner-dir <dir>` — where to run `npx playwright` from (default: the
   first directory under `--root` with `@playwright/test` installed)
-- `--port <n>` — coverage collector port, 127.0.0.1 only (default: 4571)
+- `--port <n>` — pin the coverage collector's port, 127.0.0.1 only
+  (default: any free one; a replay's harvest reads the bound port from its
+  own environment)
 - `--interval <seconds>` — seconds between coverage uploads during a
   replay (default: 10)
 - `--env <name>` — which environment from `.verifaied/config.toml` to run

{verifaied-0.28.0.dev74 → verifaied-0.29.0.dev76}/pyproject.toml

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

{verifaied-0.28.0.dev74 → verifaied-0.29.0.dev76}/src/verifaied/agent_mcp.py

@@ -66,8 +66,14 @@ from verifaied.agent_steps import (
     report,
 )
 from verifaied.config import web_url_for
-from verifaied.stepcheck import MAX_FLOW_STEPS, validate_step_line
+from verifaied.stepcheck import (
+    MAX_FLOW_STEPS,
+    MAX_SCRIPT_CHARS,
+    compose_script,
+    validate_step_line,
+)
 from verifaied.testcmd import (
+    CONSOLE_LABEL,
     ProcessRunner,
     RecordedTestError,
     RecordOutcome,
@@ -186,7 +192,7 @@ Guessing what a page will look like after a click is how flows break.
 
 {_LOCATOR_DOCTRINE}
 
-Each step is ONE of two shapes and nothing else:
+Each step is ONE of three shapes and nothing else:
 
   - an ACTION (kind "action"): `await page.<locator>.<verb>(...);` with
     <verb> one of click, dblclick, fill, press, check, uncheck,
@@ -194,11 +200,32 @@ Each step is ONE of two shapes and nothing else:
     the one action with no locator.
   - an ASSERTION (kind "assert"): `await expect(page...)....;` with any
     @playwright/test matcher.
+  - a SCRIPT (kind "script"): JavaScript that runs inside the page
+    itself, exactly as if it were typed into the browser's dev console.
+    It is for state no click can reach — an event fired from outside the
+    page (`window.dispatchEvent(new Event('offline'))`), a seeded storage
+    key, a flag in the page's own state. Give the script's BODY only: it
+    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".
 
 Rules for the code:
 
-  - One self-contained statement per step, ending in a semicolon. No
-    loops, no variables, no `if`, no comments, no `waitForTimeout`.
+  - An action or an assertion is one self-contained statement, ending in
+    a semicolon. No loops, no variables, no `if`, no comments, no
+    `waitForTimeout`.
+  - A script may run several statements over several lines, and it must
+    be complete on its own: every bracket, string and comment it opens, it
+    closes. It runs in the page, so it cannot name a declared variable —
+    `process.env` does not exist there — nor `page`, a ref or `expect`;
+    find elements with `document.querySelector`. No `/` outside a comment
+    (no regular-expression literal, no division — use `new RegExp('…')`),
+    no `${{...}}`, `require`, `import` or `eval`.
+    At most {MAX_SCRIPT_CHARS} characters.
+  - Reach for a script only when no action can do it. Clicking, typing
+    and navigating are always actions. A script checks nothing and has
+    the same 5 seconds as an action, so do not wait inside it: follow it
+    with an assertion that proves the page reacted.
   - A declared variable may be named as `process.env.VERIFAIED_VAR_<NAME>`,
     unquoted. Nothing else reaches outside the statement: no `require`,
     no `import`, no `${{...}}`.
@@ -276,8 +303,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", "code":
-"<one statement>", "label": "<a few words saying what it does>"}}`."""
+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>"}}`."""
 
 
 # What each ending actually does, so a refusal says why waiting for the
@@ -744,12 +772,22 @@ class AgentRecorderServer:
         for entry in steps:
             fields = entry if isinstance(entry, dict) else {}
             kind = str(fields.get("kind") or "")
-            code = str(fields.get("code") or "").strip()
+            # The raw text as well as the stripped statement: a script's
+            # first line may be indented on purpose, and the composer
+            # keeps it that way.
+            raw = str(fields.get("code") or "")
+            code = raw.strip()
             label = str(fields.get("label") or "").strip() or code
-            reason = validate_step_line(kind, code)
+            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})
             entries.append(
                 AgentStep(

{verifaied-0.28.0.dev74 → verifaied-0.29.0.dev76}/src/verifaied/cli.py

@@ -713,10 +713,37 @@ def record_command(
         "--port",
         help=(
             "Port the collector listens on (127.0.0.1 only). Default: "
-            f"{DEFAULT_PORT} for a bare session (what the in-page reporter "
-            "assumes), an ephemeral port when wrapping a command — the "
-            "child learns the real port from $VERIFAIED_RECORD_PORT, so a "
-            "wrapped run can coexist with a bare session."
+            f"{DEFAULT_PORT} for a bare session, an ephemeral port when "
+            "wrapping a command — the child learns the real port from "
+            "$VERIFAIED_RECORD_PORT, so a wrapped run can coexist with a "
+            "bare session."
+        ),
+    ),
+    url: str | None = typer.Option(
+        None,
+        "--url",
+        help=(
+            "Where the browser window a bare session opens should start, "
+            "e.g. http://localhost:5173. Defaults to the proxy when --proxy "
+            f"is set, else base_url from {CONFIG_PATH}."
+        ),
+    ),
+    browser: bool = typer.Option(
+        True,
+        "--browser/--no-browser",
+        help=(
+            "A bare session opens a browser window and collects from it "
+            "(default). --no-browser only listens, for posting coverage from "
+            "your own Playwright fixture."
+        ),
+    ),
+    runner_dir: Path | None = typer.Option(
+        None,
+        "--runner-dir",
+        help=(
+            "Directory @playwright/test is installed in, for the window a "
+            "bare session opens. Found under --root and the repo root when "
+            "omitted."
         ),
     ),
     interval: float = typer.Option(
@@ -749,9 +776,9 @@ def record_command(
             "Put an instrumenting reverse proxy in front of your running "
             "app, for an app with no build step to hang a coverage plugin "
             "off. Every JavaScript response is rewritten with "
-            "istanbul-lib-instrument and every HTML response gets the "
-            "reporter injected — browse the proxy URL this prints, not the "
-            "app's own port."
+            "istanbul-lib-instrument on the way past; the window a bare "
+            "session opens points at the proxy, and only pages loaded "
+            "through it are instrumented."
         ),
     ),
     proxy_target: str | None = typer.Option(
@@ -796,41 +823,45 @@ def record_command(
     commit. For a named flow you can replay forever, that is
     ``verifaied test record``.
 
-    Runs a localhost-only collector that the in-page reporter (and the
-    Playwright fixture, see ``verifaied instrument``) streams
-    ``window.__coverage__`` to. It merges the chunks and uploads them as
-    browser coverage every ``--interval`` seconds — so the Browser Tests
-    panel fills in as the session runs, with no report files to manage.
+    Runs a localhost-only collector that ``window.__coverage__`` is posted
+    to — from the Playwright fixture (see ``verifaied instrument``) when
+    wrapping a suite, and from the browser window this opens when run
+    bare. Nothing in a page ever posts anything. The collector merges the
+    chunks and uploads them as browser coverage every ``--interval``
+    seconds — so the Browser Tests panel fills in as the session runs,
+    with no report files to manage.
 
     **Wrap your e2e suite** — one command, nothing to start by hand::
 
         verifaied collect --root . -- npx playwright test
 
-    The wrapped command inherits ``VITE_COVERAGE=true`` and
-    ``VERIFAIED_RECORD_PORT``, which Playwright's ``webServer`` forwards to
-    the dev server, turning on instrumentation and the reporter. This exits
+    The wrapped command inherits ``VITE_COVERAGE=true`` (which Playwright's
+    ``webServer`` forwards to the dev server, turning on instrumentation)
+    and ``VERIFAIED_RECORD_PORT`` (which the fixture posts to). This exits
     with the command's own code, so it's transparent in CI.
 
     **Or run it bare, for a manual pass** — two terminals: start your dev
     server instrumented (``VITE_COVERAGE=true``, e.g. ``make frontend-cov``),
-    then run this. Click around, Ctrl-C when done; the final state is
-    flushed on exit.
+    then run this. A browser window opens at your app (``--url``, or
+    ``base_url`` from ``.verifaied/config.toml``); click through it there.
+    Pages in any other browser aren't collected. Close the window or press
+    Ctrl-C when done; the final state is flushed on exit.
 
     **No build step?** Add ``--proxy``. Both forms above assume something
     compiles your JavaScript and can be asked to instrument it on the way
     past. An app that serves hand-written ES modules straight off disk has
     nowhere to put a plugin, so the instrumentation moves to the last place
     the bytes go before the browser: a local proxy in front of your running
-    app, rewriting the JavaScript and injecting the reporter itself::
+    app, rewriting the JavaScript on the way past::
 
         verifaied collect --root . --proxy
 
     It forwards to ``base_url`` from ``.verifaied/config.toml`` (or
     ``--proxy-target``), needs ``istanbul-lib-instrument`` installed in your
-    repo, and changes nothing about the app. Browse the URL it prints — a
-    page loaded from the app's own port bypasses all of this and produces
-    no coverage, which is why the summary at the end says so if none
-    arrived.
+    repo, and changes nothing about the app. The window opens at the proxy
+    — a page loaded from the app's own port bypasses all of this and
+    produces no coverage, which is why the summary at the end says so if
+    none arrived.
 
     The two modes feed two different dimensions, because they answer
     different questions. Wrapping a command uploads as this branch's
@@ -896,6 +927,9 @@ def record_command(
         proxy_target=proxy_target,
         proxy_port=proxy_port,
         env_name=env_name,
+        url=url,
+        browser=browser,
+        runner_dir=runner_dir,
         console=console,
         err_console=err_console,
     )
@@ -1400,11 +1434,11 @@ def test_studio_command(
         ),
     ),
     port: int = typer.Option(
-        DEFAULT_PORT,
+        0,
         "--port",
         help=(
-            "Port the coverage collector listens on during each replay "
-            "(127.0.0.1 only)."
+            "Pin the port the coverage collector listens on during each "
+            "replay (127.0.0.1 only). Default: any free one."
         ),
     ),
     interval: float = typer.Option(
@@ -1556,11 +1590,11 @@ def test_mcp_command(
         ),
     ),
     port: int = typer.Option(
-        DEFAULT_PORT,
+        0,
         "--port",
         help=(
-            "Port the coverage collector listens on during each replay "
-            "(127.0.0.1 only)."
+            "Pin the port the coverage collector listens on during each "
+            "replay (127.0.0.1 only). Default: any free one."
         ),
     ),
     interval: float = typer.Option(
@@ -1722,10 +1756,11 @@ def test_record_command(
         ),
     ),
     port: int = typer.Option(
-        DEFAULT_PORT,
+        0,
         "--port",
         help=(
-            "Port the coverage collector listens on during the replay (127.0.0.1 only)."
+            "Pin the port the coverage collector listens on during the "
+            "replay (127.0.0.1 only). Default: any free one."
         ),
     ),
     interval: float = typer.Option(
@@ -1981,9 +2016,12 @@ def test_run_command(
         ),
     ),
     port: int = typer.Option(
-        DEFAULT_PORT,
+        0,
         "--port",
-        help="Port the coverage collector listens on (127.0.0.1 only).",
+        help=(
+            "Pin the port the coverage collector listens on (127.0.0.1 only). "
+            "Default: any free one."
+        ),
     ),
     interval: float = typer.Option(
         DEFAULT_INTERVAL,
@@ -2137,10 +2175,11 @@ def test_edit_command(
         ),
     ),
     port: int = typer.Option(
-        DEFAULT_PORT,
+        0,
         "--port",
         help=(
-            "Port the coverage collector listens on during the replay (127.0.0.1 only)."
+            "Pin the port the coverage collector listens on during the "
+            "replay (127.0.0.1 only). Default: any free one."
         ),
     ),
     interval: float = typer.Option(

verifaied-0.29.0.dev76/src/verifaied/collect_browser.js

@@ -0,0 +1,242 @@
+// The browser window a bare `verifaied collect` opens.
+//
+// Coverage leaves a page only through Node. The window this opens is a
+// Playwright context, so the counters every page accumulates are read out
+// of it from here — a binding call on unload, and a timer read for pages
+// still open — and posted to the collector the CLI already bound. No
+// script in any page ever makes a network request of its own.
+//
+// Same sidecar shape as `recorder_driver.js` and `instrumenter.js`: the
+// config arrives as a JSON file named by argv[2], events go out as JSON
+// lines on stdout, and commands come in as JSON lines on stdin. It
+// resolves `@playwright/test` from the directory the CLI spawned it in —
+// the user's own runner directory — because this file ships inside a
+// Python wheel with no node_modules above it.
+//
+// Protocol
+//   in   {cmd:"close"}                       finish: final read, then exit
+//   out  {type:"ready"}                      the window is open
+//        {type:"warning", message}           something non-fatal to print
+//        {type:"error",   message}           could not open; exit 1 follows
+//        {type:"closed",  reason}            "asked" (stdin) or "window"
+//                                            (the user closed it); exit 0
+
+const crypto = require("crypto");
+const fs = require("fs");
+const readline = require("readline");
+
+// Line-delimited JSON on fd 1, written synchronously — the same helper
+// every driver the CLI spawns carries, for the same reason: an async
+// stdout would lose whatever was buffered if the process went away.
+function emit(event) {
+  const line = Buffer.from(JSON.stringify(event) + "\n");
+  let written = 0;
+  while (written < line.length) {
+    try {
+      written += fs.writeSync(1, line, written);
+    } catch (err) {
+      if (err.code !== "EAGAIN") return;
+    }
+  }
+}
+
+function loadPlaywright() {
+  const entry = require.resolve("@playwright/test", { paths: [process.cwd()] });
+  return require(entry);
+}
+
+const BINDING = "__verifaiedHarvest";
+
+// Serialised into every document by `addInitScript`, so it references
+// nothing from this file's scope.
+function unloadHook() {
+  window.addEventListener("beforeunload", () => {
+    const w = window;
+    if (w.__coverage__ && w.__verifaiedHarvest) {
+      w.__verifaiedHarvest(JSON.stringify(w.__coverage__));
+    }
+  });
+}
+
+function readCoverage() {
+  return window.__coverage__ ? JSON.stringify(window.__coverage__) : null;
+}
+
+function digest(text) {
+  return crypto.createHash("sha1").update(text).digest("hex");
+}
+
+/**
+ * Open the window and keep reading it until asked to stop or it closes.
+ *
+ * `chromium`, `input`, `emit` and `fetchImpl` are parameters so a test can
+ * drive this with a fake browser and a fake stdin; `main` below is the
+ * only place the real ones are wired in. Resolves to the exit code.
+ */
+async function run({ chromium, config, input, emit, fetchImpl = fetch }) {
+  const { url, port, userDataDir } = config;
+  const intervalMs = config.intervalMs || 5000;
+  const sink = `http://127.0.0.1:${port}/coverage`;
+
+  // Every post is tracked so the final step can wait for the ones a
+  // closing window fired through the binding a moment ago.
+  const pending = new Set();
+  const post = (body) => {
+    const request = fetchImpl(sink, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+    }).catch(() => {});
+    pending.add(request);
+    request.finally(() => pending.delete(request));
+    return request;
+  };
+
+  let context;
+  try {
+    context = await chromium.launchPersistentContext(userDataDir, {
+      headless: false,
+      viewport: null,
+    });
+  } catch (err) {
+    emit({
+      type: "error",
+      message: `could not open a browser window: ${(err && err.message) || err}`,
+    });
+    return 1;
+  }
+  await context.exposeBinding(BINDING, (_source, body) => post(body));
+  await context.addInitScript(unloadHook);
+
+  // One read per page per change: the counters are cumulative, so an
+  // unchanged snapshot carries nothing the collector hasn't merged.
+  const lastSent = new WeakMap();
+  const readPage = async (page) => {
+    let body;
+    try {
+      body = await page.evaluate(readCoverage);
+    } catch {
+      return; // navigating, or already gone
+    }
+    if (!body) return;
+    const hash = digest(body);
+    if (lastSent.get(page) === hash) return;
+    lastSent.set(page, hash);
+    await post(body);
+  };
+  // One read at a time, and the read in flight is kept rather than
+  // dropped: the final read on close has to wait for a tick that is
+  // still walking the pages and then walk them all again itself, or the
+  // pages that tick had not reached would lose their last counters.
+  let inflight = null;
+  const readAll = () => {
+    if (inflight) return inflight;
+    inflight = (async () => {
+      try {
+        for (const page of context.pages()) await readPage(page);
+      } finally {
+        inflight = null;
+      }
+    })();
+    return inflight;
+  };
+
+  let finished;
+  const done = new Promise((resolve) => {
+    finished = resolve;
+  });
+  let closing = false;
+  let timer = null;
+
+  const finish = async (reason) => {
+    if (closing) return;
+    closing = true;
+    if (timer !== null) clearInterval(timer);
+    if (reason === "asked") {
+      // Whatever a tick was in the middle of, then everything once more:
+      // nothing is lost between the last tick and now.
+      if (inflight) await inflight.catch(() => {});
+      await readAll().catch(() => {});
+      try {
+        await context.close();
+      } catch {
+        // Already closed underneath us.
+      }
+    }
+    await Promise.allSettled([...pending]);
+    emit({ type: "closed", reason });
+    finished(0);
+  };
+
+  // Registered before the first navigation, which can take a while: a
+  // window the user shuts during it has to be reported, not missed.
+  context.on("close", () => {
+    finish("window").catch(() => finished(0));
+  });
+  const lines = readline.createInterface({ input });
+  lines.on("line", (line) => {
+    let command;
+    try {
+      command = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (command && command.cmd === "close") finish("asked").catch(() => finished(0));
+  });
+  // EOF on stdin is the parent going away: finish as if asked.
+  lines.on("close", () => {
+    finish("asked").catch(() => finished(0));
+  });
+
+  const first = context.pages()[0] || (await context.newPage());
+  if (url && !closing) {
+    try {
+      await first.goto(url);
+    } catch (err) {
+      if (!closing) {
+        emit({
+          type: "warning",
+          message: `could not open ${url}: ${(err && err.message) || err}`,
+        });
+      }
+    }
+  }
+  if (closing) return done;
+  emit({ type: "ready" });
+  timer = setInterval(() => {
+    if (!closing) readAll().catch(() => {});
+  }, intervalMs);
+
+  return done;
+}
+
+function main() {
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+  } catch (err) {
+    emit({ type: "error", message: `could not read the config: ${err.message}` });
+    process.exit(1);
+  }
+  let playwright;
+  try {
+    playwright = loadPlaywright();
+  } catch (err) {
+    emit({
+      type: "error",
+      message: `could not load @playwright/test from ${process.cwd()}: ${err.message}`,
+    });
+    process.exit(1);
+  }
+  run({ chromium: playwright.chromium, config, input: process.stdin, emit }).then(
+    (code) => process.exit(code),
+    (err) => {
+      emit({ type: "error", message: String((err && err.message) || err) });
+      process.exit(1);
+    },
+  );
+}
+
+module.exports = { run, BINDING };
+
+if (require.main === module) main();