Browser check — proving a UI works, in numbers

Three places in this plugin order a browser pass — the conductor's quality gates, the reviewer, the implementer — and fidelity-gate asks for computed styles on top. None of them said how. This is the how, and it exists so that "I checked it in the browser" stops being a sentence and starts being a counter someone else can re-run.

A browser pass is a measurement. It returns numbers: pages visited, links resolved, console errors, failed responses. Looks fine, renders correctly and no obvious issues are REJECTED by the evidence contract exactly like a test report with no output, and for the same reason — nothing in them can be wrong.

Before you promise a run

1. The browser exists. npx playwright --version, and install only chromium (npx playwright install chromium) — a full browser install is several GB for two extra engines nobody asked for.
2. The server is up and SERVING WHAT YOU THINK. Fetch one known URL and check the status before automating anything. A dev server that is still compiling, or is serving a stale build on a port you forgot to kill, produces a page of failures that have nothing to do with your change.
3. Build first when the target is a static site. Testing the dev server and shipping the build tests two different programs.

Waits are deterministic — never a sleep

Wait for a condition: a response, a selector, a network-idle state, a font ready promise. waitForTimeout is a guess that is simultaneously too long on your machine and too short in CI, and the failures it produces are indistinguishable from real ones. The only defensible fixed wait is settling an animation you cannot observe, and it says so in a comment.

Warm the routes before a batch run. The first request to a route compiles it; a cold compile times out and reads as a defect in the page. Hitting every route once before measuring costs one pass and removes a whole class of false finding.

What you collect, and what you return

Subscribe before you navigate — listeners attached after the first goto miss everything that page already did:

• console events of type error
• pageerror — uncaught exceptions, which are NOT console errors and are routinely missed by checking only the first
• response with status >= 400, including the ones fired by the page's own fetches, which no amount of clicking will reveal
• every in-page link, resolved once and cached by URL

Return them as counts plus the first few offenders, then a single verdict line. A pass with 0 console errors is a fact; "the console was clean" is a recollection.

When the UI claims to change something the SERVER acts on — a mapping, a setting, a value the next request depends on — a clean console and a 2xx are not proof it arrived. The evidence has to follow the value to what got STORED, not stop at what got RENDERED: capture the request body you actually sent, or read the value back with a second request or a reload, and assert on THAT. This is not hypothetical. A column-mapping override shipped with a perfect browser pass — 15/15 columns visible, 0 console errors, the mapping visibly changed by hand — while the server re-derived the source type from the uploaded bytes and discarded the mapping, answering 201 either way. Only a reviewer reading the server route caught it; nothing in the browser measurement could have, because it never inspected what the server persisted.

Selectors that do not go blind

Anchor on what the user sees — a role, a label, the text — not on a container class or an nth-child. This is not a style preference. A selector scoped to the markup it was written against keeps passing while silently checking LESS of the page as the page grows, and it reports the narrowed number as success. That has already happened in this repo: a link check named two regions of one framework's chrome, and went from checking every link to checking half of them on the day a page was added outside that chrome — with no failure anywhere.

So: assert the COUNT you expected as well as the condition. 24 links checked, 0 broken catches the regression that 0 broken cannot.

When the disagreement is about appearance

Settle it with getComputedStyle, dumped to JSON, compared against the inventory. Never by looking, and never by asking a model to look:

await page.$$eval(SELECTORS, (els) => els.map((el) => {
  const s = getComputedStyle(el);
  return { text: el.textContent.trim(), fontSize: s.fontSize, fontWeight: s.fontWeight, color: s.color };
}));

Two rules that keep this a measurement:

• Assert the element's text alongside its geometry. A structural selector with no text assertion measures the wrong element when the markup is renumbered, and reports a confident wrong number instead of a loud miss.
• A zero-size box is a failure, not a pass. An element that renders with no width, or a glyph that inherits fill: none, is present in the DOM and invisible on the screen. Check the bounding box whenever you check anything visual, or the check passes on a page nobody can read.

For a frozen reference, this step belongs to fidelity-gate, which owns the inventory, the relics list and the verdict format. Do not invent a second one.

Artefacts and cleanup

Screenshots, JSON dumps and logs go under .tyran/, never /tmp — they are evidence for a report, and evidence a colleague cannot open is not evidence. Name them for the run, not screenshot.png.

End the way you started: close the browser, and stop the server you started with SIGTERM so it can release its port. kill -9 leaves the port held and the next run fails for a reason that has nothing to do with the code.

The report

PAGES 13 · LINKS 24/24 · CONSOLE ERRORS 0 · PAGE ERRORS 0 · HTTP>=400 0
BROWSER PASS: OK

Then the failures, if any, with the URL that produced each. State plainly what you did NOT drive — the viewport you skipped, the flow behind a login, the browser you do not have. An unchecked area named in the report is a decision for the conductor; an unchecked area left out of it is a claim.