viewer-smoke - SKILL.md Agent Skill

name: viewer-smoke description: Run the end-to-end viewer smoke test (`tests/viewer_smoke.sh`). Spawns `rezolus view` in upload-only, file, A/B, and proxy modes, exercises the API endpoints, and verifies experiment attach/detach. Use after any change touching `src/viewer/` or before opening a viewer-related PR.

Viewer smoke test

Runs the viewer in four configurations against checked-in demo parquets and asserts the public API endpoints behave correctly. Designed to be invoked from a PR/commit hook so behavior regressions in src/viewer/ show up before review.

Steps

Run the script:
```
bash tests/viewer_smoke.sh
```
Interpret the result:
- Exit 0 → all assertions passed; viewer behaves correctly across upload-only, file mode, A/B compare mode, and proxy mode, including experiment attach/detach via the HTTP API.
- Exit 1 → first failed assertion is printed, plus the failing viewer's startup log. Read both before guessing — the log usually says exactly what blew up (port collision, missing parquet, panic, etc.).
If the script fails, do not paper over by editing the assertions. The script is the contract. If a behavioral change is intentional (e.g. a renamed JSON field), update the assertion in the same commit that changes the behavior, and call it out in the PR description.

What it covers

/api/v1/mode — loaded, compare_mode, url_loading flags across the four startup configs
/api/v1/sections — navigation list non-empty
/data/<section>.json — at least one group in the lazy-section payload
/api/v1/query_range — PromQL execution returns status:"success"
/api/v1/load_url — 403 envelope when proxy disabled, invalid_parquet envelope when fetching non-parquet bytes from an allowed host
POST /api/v1/captures/experiment — flips compare_mode:true
DELETE /api/v1/captures/experiment — flips compare_mode:false
Static assets — /, /about, /lib/style.css all return 200

What it does not cover

Live mode (rezolus view <agent-url>) — needs an actual rezolus agent listening, not reproducible without one.
Browser-rendered UI — the script only asserts on backend payload shape. Visual regressions in the dashboard need eyeball verification.
Compare-mode UI rendering — the experiment attach/detach assertion only checks the API flag flip; the rendered side-by-side view isn't exercised.

Requirements

cargo — builds the binary if it isn't already built
bash 4+, curl, jq — assertions
Ports 18500-18503 free
Internet access to httpbin.org for the proxy assertion (skipped with a warning if unreachable)

Triggering it from a hook

A typical wiring:

Per-PR (CI) — add a job to .github/workflows/cargo.yml that runs bash tests/viewer_smoke.sh after cargo build.
Per-commit (local) — .git/hooks/pre-push calling the same script. Slow (cold builds take ~60 s + 8 s of viewer warmup), so prefer the CI route unless the dev wants the early signal.
Per Claude Code session — invoke this skill via /viewer-smoke or have the agent call it from a SessionStart / PostToolUse hook that watches src/viewer/**.