Rendering the viewer for real
Why this exists
Three layers of viewer testing already exist and none of them can see the page:
tests/*.test.mjs — pure frontend logic, no DOM by design (CLAUDE.md: "no
bundler, no jsdom").tests/viewer_smoke.sh — API envelopes. Its own "what it does not cover"
section says "Browser-rendered UI … visual regressions need eyeball
verification."- CI — compiles both backends. Compilation is not rendering.
So a change can be green everywhere and still ship a label at the disabled
contrast tier, a chip strip that wraps out of the navbar, or a mithril keyed
fragment that warns on every redraw. This renders the page in Chrome and
reports what actually got drawn.
Two traps, both of which bite on the first run
1. Set REZOLUS_NO_OPEN=1. A second after binding, rezolus view opens the
dashboard in the user's real browser (src/viewer/mod.rs). It is an environment
variable, not a CLI flag, so it is easy to miss — and a headless session that
starts seven viewers across a review silently opens seven tabs on someone's
desktop. Always set it.
2. Build with --features developer-mode. The binary embeds
src/viewer/assets/ at compile time. A normal cargo build bakes in whatever
the assets were when it last ran, so you screenshot the old frontend, see your
change missing — or worse, see something plausible and conclude it works.
cargo build --bin rezolus --features developer-mode # assets from disk
REZOLUS_NO_OPEN=1 target/debug/rezolus view --listen 127.0.0.1:4299 /tmp/x.rez &
If the render disagrees with the source you are reading, it is trap 2.
Setup
puppeteer-core plus a browser already on the machine. Do not add either to
the repo — it deliberately carries no JS toolchain, and puppeteer (without
-core) downloads ~150 MB of Chromium you do not need.
mkdir -p /tmp/viewer-render && (cd /tmp/viewer-render && npm i puppeteer-core)
export PUPPETEER_CORE=/tmp/viewer-render/node_modules/puppeteer-core
export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
CHROME_PATH is optional where Chrome sits in a standard location; the script
probes the usual macOS and Linux paths.
Plain chrome --headless --screenshot=out.png <url> hangs on this page —
the dashboard never reaches the quiescent state that flag waits for. Use the
script, which waits on networkidle2 plus a selector.
Use it
# 1. Assets from disk, and no browser tab on the user's desktop.
cargo build --bin rezolus --features developer-mode
REZOLUS_NO_OPEN=1 target/debug/rezolus view --listen 127.0.0.1:4299 /tmp/three.rez &
# 2. Render and inspect.
node scripts/viewer_render.mjs \
--url http://127.0.0.1:4299 \
--selector '.compare-badge' \
--children '.compare-badge-label' \
--out /tmp/badge.png
Stdout is a JSON block: tag, classes, computed colours, box geometry, per-child
text/title/colour/truncation, rowTops, wrapped, consoleProblems,
failedRequests. Two PNGs land beside --out: the element, and the top band of
the page for layout context.
--children matters more than it looks. It defaults to direct children, and
in this UI the node carrying the text, the tooltip and the truncation is usually
a grandchild — a label inside a chip. Point it at that node or the interesting
fields all read null.
Read the JSON, not just the picture
The screenshot is for the human in the PR. The JSON is what you assert on:
wrapped / rowTops — distinct child row tops mean the content broke
onto more than one line. Sweep --width 1440 1280 1100 1000 820 to find the
point where it happens; one screenshot at one width hides this entirely.children[].truncated — scrollWidth past the painted width means an
ellipsis is eating text. If that child has no title, the text is
unrecoverable by the user. Truncation plus a missing tooltip is a finding.children[].color — resolve the actual computed colour. --fg-muted is
the disabled tier (#484f58 on dark); --fg-secondary (#8b949e) is
"dimmer but meant to be read". Picking the wrong one looks fine in the CSS and
wrong on screen.consoleProblems — mithril keyed-fragment violations, exceptions in a
redraw, and every console.warn (the viewer warns when it drops a link
parameter the recording cannot satisfy, so a check on such a link expects
those entries rather than an empty list). Silent in every other test layer.failedRequests — a 404 on a newly added shared module means a missing
site/viewer/lib symlink (see the viewer-parity skill), which breaks the
static viewer completely.
Check both themes
Colours are CSS custom properties overridden under [data-theme="light"], and
--fg-muted inverts between them. --theme light / --theme dark sets the
attribute directly, so one run per theme covers both.
Where the script lives, and why not tests/
scripts/viewer_render.mjs. CI runs node --test tests/*.mjs, and that glob
takes every .mjs in the directory, not just *.test.mjs — a tool parked
there gets executed as a test and fails the suite.
Fixtures
rez's fixture writer caps at four recordings:
cargo run -p rez --features test-support --example write_rez_fixture -- /tmp/four.rez 4
For more arms — worth doing, since layout problems only appear at scale —
combine archives:
target/debug/rezolus recording combine /tmp/four.rez /tmp/three.rez -o /tmp/seven.rez
Known noise
A bare fixture has no systeminfo, so /api/v1/systeminfo and
/api/v1/selection 404 and surface in failedRequests. Not your change.
What this still does not cover
- The WASM/static viewer. This drives
rezolus view (the axum server). The
frontend is symlinked and therefore identical, but the backend answering
/api/v1/* is not — see the viewer-parity skill. To render that side you
need ./crates/viewer/build.sh and a static server over site/.
- Interaction. Hover, click, drag, dropdown open/close. Puppeteer can do all
of it; the script just does not, yet.
- Pixel regression. No baseline images are stored, deliberately — they rot.
The JSON facts are the durable assertion.