Code reached

Unit coverage says a test ran a function. Code reached says a real browser ran it, in your running app.

What it shows

Every function is in one of three groups: Unexercised, Partially exercised or Fully exercised. The Code reached tile on a branch's Browser tests page is the headline number. Click it to open the Browser coverage section, which lists the functions in each group.

The numbers come from three places:

  • Every replay of a recorded browser test. Each test keeps what its own latest replay reached.
  • Your existing Playwright suite, when you run it through verifaied collect.
  • Manual sessions, where you click through the app by hand. These are kept apart, on the Manual tab.

In React .tsx files, inline event handlers and conditional render branches are tracked one by one, under Handlers & render branches on a function's page.

Whether an unexercised function blocks a branch from being done is the Unexercised in browser switch. See Definition of done.

Instrument your app

A browser can only report what it ran if your app's JavaScript is instrumented. How you do that depends on what builds the app. Run this in the app's directory and it prints the setup for the stack it finds:

verifaied instrument

Or pick your stack here:

Your app has a vite.config.ts.

Vite instrumentation (vite-plugin-istanbul)
// 1. install as a dev dependency:
//    npm i -D vite-plugin-istanbul   (or pnpm add -D / yarn add -D)

// 2. import at the top of your Vite config:
import istanbul from "vite-plugin-istanbul";

// 3. add to the `plugins` array in defineConfig({ plugins: [...] }):
istanbul({
  // Inert unless VITE_COVERAGE is set, so normal dev and production
  // builds are completely unaffected. @vitest/coverage-istanbul stays
  // your unit-test coverage provider — this is separate.
  requireEnv: true,
  include: "src/*",
  extension: [".js", ".ts", ".jsx", ".tsx"],
})

The Vite and Babel setups only switch on when an environment flag is set, so normal development and production builds do not change. To check that an app is instrumented, for example in CI:

verifaied instrument --check

An app with no build step has nowhere to put a plugin. Use the proxy instead: verifaied collect --proxy for a suite or a manual session, and verifaied test run --proxy for recorded tests. It instruments the JavaScript on its way to the browser and needs no change to the app. Only pages loaded through the proxy are measured.

Measure your Playwright suite

First, add this fixture to your suite and import test from it in your specs. It sends what each page ran to the collector. It captures when a page unloads as well as at the end of the test, because a full page load clears what the page had collected.

import { test as base } from "@playwright/test";

const ON = process.env.VITE_COVERAGE === "true";
const URL = `http://127.0.0.1:${process.env.VERIFAIED_RECORD_PORT ?? 4571}/coverage`;

// Node-side fetch: no CORS, no browser payload limits. Fire-and-forget —
// with no collector listening the POST just fails, silently.
const post = (body) =>
  fetch(URL, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body,
  }).catch(() => {});

export const test = base.extend({
  page: async ({ page }, use) => {
    if (ON) {
      // Hook 1 of 2. window.__coverage__ is reset by every hard navigation
      // (each page.goto starts a fresh document), so without this the
      // end-of-test snapshot below would only ever see the LAST page —
      // every earlier page's coverage would be silently lost.
      await page.exposeFunction("__verifaiedPost", post);
      await page.addInitScript(() =>
        window.addEventListener("beforeunload", () => {
          if (window.__coverage__)
            window.__verifaiedPost(JSON.stringify(window.__coverage__));
        }),
      );
    }
    await use(page);
    if (ON) {
      // Hook 2 of 2. Playwright closes pages without reliably firing
      // beforeunload, so the final page needs an explicit read.
      try {
        const c = await page.evaluate(() => window.__coverage__ ?? null);
        if (c) await post(JSON.stringify(c));
      } catch {
        // Page already gone — hook 1 banked it.
      }
    }
  },
});

Then run the suite through verifaied collect. It starts the collector, runs your command, uploads the result and exits with the suite's own exit code, so it is safe in CI.

# Wrap your e2e suite — one command. VITE_COVERAGE and the collector port
# are injected into it, and Playwright's webServer forwards them to the dev
# server. Exits with the suite's own code, so it's CI-safe:
verifaied collect --root . -- npx playwright test

# Add --trace on to keep a trace from every test, including passing ones.
# Playwright's usual on-first-retry default writes no trace at all when the
# suite is green, so a clean run would attach nothing:
verifaied collect --root . -- npx playwright test --trace on

# Or drive the app by hand, in two terminals.
# Terminal 1 — your dev server, instrumented:
VITE_COVERAGE=true npm run dev
# Terminal 2 — opens a browser window at your app; click through it there.
# Uploads every 10s; close the window or Ctrl-C to flush and exit:
verifaied collect --root . --url http://localhost:5173

Each wrapped run replaces what the last wrapped run reached, and nothing else. Failure screenshots and traces that Playwright leaves in test-results are attached to the run, under Other activity on the Browser tests page.

Coverage must point at your original source files. An upload that names only build output such as dist/ is rejected.

Already have a merged coverage report, for example one downloaded from CI? Upload it directly:

# Already have a merged coverage report? Upload it straight to the browser
# dimension — no collector needed. Run from the directory the coverage
# paths are relative to, or point --root at it:
verifaied upload --browser --coverage coverage/coverage-final.json --root .

Click through by hand

Run verifaied collect with no command and it opens a browser window at your app. Click through the app there. Close the window or press Ctrl-C when you are done.

verifaied collect --url http://localhost:5173

Without --url the window opens at base_url from .verifaied/config.toml. Your app has to be running with instrumentation on, or behind --proxy.

What you touch shows up on the branch's Manual tab while you click, and it accumulates: each session adds to the last. When you want a fresh start, Clear on that page puts every function back to Unexercised. So does this command:

verifaied clear-manual

Only manual sessions have a clear. A test or a suite replaces its own numbers on its next run.

Include your backend

Code reached is not limited to the frontend. Run your API server under coverage.py while the browser drives it, then upload the report the same way. That turns “the suite reached this page” into “the suite reached this endpoint”.

# .coveragerc (or [tool.coverage.run] in pyproject.toml) — relative_files
# keeps recorded paths repo-relative, so they match what --root points at
# below and verifAIed can find the sources:
#   [run]
#   relative_files = true
#   # Several workers (gunicorn -w, uvicorn --workers)? Add parallel = true
#   # as well — each worker writes its own data file — and run
#   # `coverage combine` before the `coverage json` in step 3.

# 1. Start the API under coverage, with NO --reload. The reloader serves
#    every request from a child process that `coverage run` never wrapped,
#    so the run measures nothing and the report comes back empty:
coverage run -m uvicorn app.main:app   # your server entrypoint

# 2. Exercise it through the browser — the same e2e run that drives your
#    frontend — then stop it with a real SIGINT/SIGTERM: Ctrl-C in its
#    terminal, or `kill -TERM <pid>`. coverage.py only writes on that exit
#    hook, so a SIGKILL loses the whole report and says nothing.

# 3. Once it has actually stopped, convert to JSON and upload as the same
#    browser dimension:
coverage json -o coverage.json
verifaied upload --browser --coverage coverage.json --root .

Two mistakes produce an empty report without any error:

  • Starting the server with --reload. Requests are served by a child process that is not measured.
  • Killing the server. The report is written when the server shuts down, so stop it with Ctrl-C or kill -TERM, never SIGKILL.

In a container, start the server in exec form so it receives the stop signal, and mount the directory the data file lands in so it reaches your machine:

# docker-compose.override.yml — an overlay you layer on for coverage runs,
# so your normal stack is untouched. Two things matter, both because
# `docker compose stop` sends SIGTERM to PID 1 in the container and to
# nothing else:
services:
  api:
    # Exec form — a YAML list, never a shell string. `sh -c "coverage run
    # ..."` makes the shell PID 1, and it swallows the signal before
    # coverage ever sees it.
    command:
      - coverage
      - run
      - -m
      - uvicorn
      - app.main:app
      - --host
      - "0.0.0.0"
    # The data file is written inside the container, so bind-mount the
    # directory it lands in — you probably already do — or `docker cp` it
    # out after stopping.
    volumes:
      - ./backend:/app

# Then, from the host, after the browser session is done:
docker compose stop api   # SIGTERM → graceful shutdown → the data file

# Convert from the directory the recorded paths start at — the container
# recorded them relative to its own workdir, and `coverage json` reads
# your sources relative to ITS cwd, so from the repo root it fails with
# "No source for code" instead of writing a report:
(cd backend && coverage json -o ../coverage.json)
verifaied upload --browser --coverage coverage.json --root backend

Run coverage json from the directory the recorded paths start at, and point --root at that same directory. A backend upload does not replace what the frontend reached: an upload only replaces the languages it measured.

Set it up with your agent

Rather than wiring this by hand, paste the prompt below into your coding agent. It finds your build setup, adds the instrumentation and the fixture, sets up backend capture if you have an API, and runs the first upload.

Paste into your coding agent
Have your agent wire up browser coverage in your repo end to end.
I want to add browser-coverage harvesting to my project so verifAIed can track which of my functions actually run during real browser sessions (e2e tests, agent runs, manual clicking). This is a separate dimension from my unit-test coverage — it must not change how my app builds or runs normally.

# HARD REQUIREMENTS — DO NOT DEVIATE

1. **Instrument the app, gated on an env flag.** Which plugin depends on what builds my app, but the gate never does: with the flag unset, dev and production builds MUST be byte-identical.
   - **Vite** — `vite-plugin-istanbul` in the config's `plugins` array with `requireEnv: true`, gated on `VITE_COVERAGE`. Do NOT remove or weaken `requireEnv`.
   - **webpack / Next.js / CRA / Angular / Rollup** — `babel-plugin-istanbul` in my Babel config, under an `env` key so it only applies when I ask for it.
   - **No build step** (JavaScript served exactly as it is on disk) — there is nothing to wire. Skip to `verifaied collect --proxy`, below; it instruments at request time and needs no change to my app at all.

   Either way, do NOT touch the `@vitest/coverage-istanbul` unit-test provider; this is independent of it.

2. **Coverage keys must be ORIGINAL, source-mapped source paths** — `.ts`/`.tsx`/`.js`/`.jsx` files, not compiled bundles. verifAIed rejects any upload whose paths point at `dist/`, `build/`, `out/`, or `.next/` — it can't map coverage of bundled output back to my sources. `vite-plugin-istanbul` and `babel-plugin-istanbul` both apply source maps for you; just make sure the harvested report references my `src/` files. With no build step the served file IS the source, so the paths are already right.

3. **NEVER pass `--junit` together with `--browser`.** A browser session produces coverage, not test results — the two flags are incompatible and the CLI will reject the combination.

4. **Never add a script to my pages that sends coverage anywhere.** Not a reporter, not a beacon, not a fetch on a timer. A browser logs a refused request in its console whatever the script that made it does about it, and nothing may ever appear there. Coverage leaves the page only from Node: the Playwright fixture below, or the browser window `verifaied collect` opens for a manual pass.

5. **The Playwright fixture must keep BOTH capture hooks.** `window.__coverage__` is reset by every hard navigation, so an end-of-test snapshot alone captures only the LAST page and silently loses every earlier one; and Playwright closes pages without reliably firing `beforeunload`, so the init-script hook alone loses each test's tail. Keep (a) `page.exposeFunction` + `page.addInitScript` registering a `beforeunload` POST, AND (b) a final `page.evaluate` snapshot after the test, wrapped in try/catch. Do not "simplify" this to one hook — the loss is silent.

6. **If you capture my backend too, it must be stopped by a real signal, and `--reload` must be OFF.** Both mistakes produce a successful-looking run and an empty report. `coverage.py` writes its data file from an exit hook, so a `SIGKILL` — `kill -9`, or a `docker compose stop` that runs past its grace period into one — writes nothing at all. And uvicorn's `--reload` serves every request from a child process that `coverage run` never wrapped, so that run measures nothing whatever it is sent. In Docker, `command:` MUST be exec form (a YAML list) — `sh -c "coverage run ..."` makes the shell PID 1, and `docker compose stop` signals PID 1 and nothing else, so the shell swallows it. Do not report the capture as working until you have seen a non-empty `coverage.json` with my source paths in it.

# What to build

- **Add a Playwright coverage fixture.** Extend the `page` fixture so it POSTs `window.__coverage__` to `http://127.0.0.1:<VERIFAIED_RECORD_PORT or 4571>/coverage` — a Node-side `fetch`, fire-and-forget with `.catch(() => {})` — all gated on `process.env.VITE_COVERAGE === "true"`. It must keep BOTH hooks (see HARD REQUIREMENT 5). No merging, no teardown file, and NO `istanbul-lib-coverage` dependency: `verifaied collect` does the merging. If I use a different browser runner, adapt the same two-hook pattern to it.

- **For manual sessions, nothing to add.** `verifaied collect --url <my app>` with no command opens a browser window at my instrumented dev server and reads the coverage out of every page I click through, from Node. Tell me to start the dev server with the coverage flag first and to click through the app in that window, not in another browser.

- **Run the suite through the collector.** One command: it injects `VITE_COVERAGE=true` and the collector port into the suite (Playwright's `webServer` forwards them to the dev server), merges everything the fixture sends, uploads additively, and exits with the suite's own code so it stays CI-safe:
  ```
  verifaied collect --root <frontend-dir> -- npx playwright test
  ```
  Point `--root` at the directory the coverage paths are relative to (your frontend app).

- **No build step? Use the proxy instead of all of the above.** If nothing compiles my JavaScript, install `istanbul-lib-instrument` as a dev dependency and run `verifaied collect --root . --proxy` with my app running. It stands a local proxy in front of the app and rewrites every JavaScript response on the way past — no plugin, no fixture, no change to my app — and opens a browser window at the proxy. Tell me to click through the app in that window rather than at the app's own port, because a page loaded from the app's port bypasses all of it.

- **Capture the backend too, if my browser sessions hit my own API.** That is the other half of the same dimension, and it is worth wiring: it is what turns "an e2e run reached this page" into "an e2e run reached this endpoint". Set `relative_files = true` in `.coveragerc` or `[tool.coverage.run]` (plus `parallel = true` and a `coverage combine` step if the server runs several workers), start the server under `coverage run` with no `--reload`, drive it with the same e2e run, stop it with a real SIGINT/SIGTERM, and only then `coverage json -o coverage.json` and `verifaied upload --browser --coverage coverage.json --root <backend-dir>`. **Run `coverage json` from the directory those relative paths start at**, and point `--root` at that same directory: `coverage json` reads my sources relative to its own working directory, so running it one level up fails with `No source for code` rather than writing a report. If my API runs in Docker for the e2e stack, use an overlay compose file with an exec-form `command:`, no `--reload`, and a bind mount (or `docker cp`) so the data file reaches the host — and remember the paths it recorded start at the container's workdir, not at my repo root. See HARD REQUIREMENT 6 for why each of those is load-bearing. Uploading it does **not** disturb the frontend harvest: both land as this branch's suite contribution, but an upload only replaces the languages it actually measured, so the two halves accumulate in either order. Any language's coverage of code run during the session belongs to the same browser dimension.

- **Finish by checking the verdict.** Run `verifaied check-done` and iterate until there are no `unexercised_browser` gaps left for the functions I changed.

# Determine my stack yourself

Don't ask me unless it's genuinely ambiguous after looking:
- **Easiest**: run `verifaied instrument`. It detects which of the three shapes my app is and prints the exact wiring — that is the same answer as everything below.
- **Vite**: `vite.config.ts` (or `.mts`/`.cts`/`.js`/`.mjs`/`.cjs`), including in a subdirectory like `frontend/` or `web/` in a monorepo.
- **Babel-based**: `next.config.*`, `angular.json`, `craco.config.*`, `webpack.config.*` or `rollup.config.*`, or the matching dependency in package.json.
- **No build step**: an HTML file loading a `<script type="module" src="...">` whose target is a real file in the repo — nothing generates it, so nothing can instrument it at build time.
- **Package manager**: `pnpm-lock.yaml` → pnpm; `yarn.lock` → yarn; `package-lock.json` → npm. Use the matching install command.
- **Browser runner**: look for an existing Playwright config and match its style. If I use Cypress or another tool instead, keep the same harvest shape (`window.__coverage__` merged into `coverage-final.json`).

# Output

Make the changes, then show me the exact commands to run the instrumented suite and upload. If the instrumentation is already wired, say so and skip re-adding it.