Regenerate Dashboard Documentation Screenshots

Refresh the website's dashboard screenshots after UI changes. The flow brings up a fully-populated demo dashboard, then captures one crisp PNG per tab at the same geometry as the existing images so they drop in with no <img> edits.

TL;DR

cd mockserver-ui
npm install                       # first time only — fetches playwright
npx playwright install chromium   # first time only — fetches the browser binary
npm run screenshots:all           # demo up → capture every tab → demo down

screenshots:all writes 17 PNGs straight into jekyll-www.mock-server.com/images/ (the live website paths). Review the diff, then commit the changed images.

How it works

screenshots:all runs the demo in two phases, because load injection and the screenshots want opposite things (see "Why two phases" below):

flowchart TB
  subgraph P1["Phase 1 — content tabs"]
    A1["demo --with-broker\n(NO load injection)"] --> A2["capture 15 content tabs\n(Traffic, Sessions, Mocks, Chaos, …)"]
  end
  subgraph P2["Phase 2 — chart tabs"]
    B1["demo --with-broker --with-load-injection"] --> B2["warm up ~90s"] --> B3["capture Metrics + Performance"]
  end
  P1 --> P2 --> C["MockServer<Tab>.png → jekyll-www.../images/"]

Each phase: background npm run demo, wait for the "Ready — populated demo environment" line, run the Playwright capture, tear the demo down (trap EXIT).

Two scripts, both in mockserver-ui/scripts/:

Curated tab states

The capture doesn't just navigate — for several tabs it drives a richer documentation state (each is a best-effort prepare step in the .mjs; a failure is logged and the shot still happens):

Why two phases

The dashboard keeps only the most recent ~100 traffic items. A load scenario firing thousands of requests/sec evicts the seeded LLM conversations (and can saturate the WebSocket so panels never reach "Connected"). So content tabs are shot against a quiet demo. The Metrics/Performance charts, conversely, need live sustained throughput to draw non-empty series — so they get their own load-injection phase with a warm-up. Set SKIP_CHARTS=true to run only phase 1.

Matching the existing screenshots

The clarity of the current images comes from Retina capture: a 1920-wide viewport at deviceScaleFactor: 2, producing ~3840px-wide PNGs. The capture script defaults to exactly this (WIDTH=1920 HEIGHT=900 SCALE=2). Keep these to stay consistent with the on-site images. Filenames reuse the existing MockServer<Name>.png convention, so regenerated tabs overwrite in place.

Prerequisites

• Docker running if you pass --with-broker (the Async tab's recorded

messages need a Mosquitto broker). Without it, drop --with-broker.

• Node via nvm — the repo's node is nvm-managed (v22.x). Homebrew node (v26)

breaks the UI build. If node is shadowed by an _load_nvm shell function, use the absolute path ~/.nvm/versions/node/v22*/bin/node.

• Playwright browser installed once: npx playwright install chromium.

Common variations

cd mockserver-ui

# Content tabs only — skip the slower phase-2 load-injection chart pass:
SKIP_CHARTS=true npm run screenshots:all

# Capture into a scratch dir first to eyeball before overwriting the live images:
OUT_DIR=.tmp/shots npm run screenshots:all

# Longer chart warm-up (default 90s) for fuller Metrics/Performance series:
CHART_WARMUP_S=180 npm run screenshots:all

# Iterate on one screen against an already-running demo (two terminals):
npm run demo -- --with-broker                          # terminal 1 (quiet demo)
ONLY=traffic,composer,chaos npm run screenshots        # terminal 2

The orchestrator passes --with-broker itself; you don't add demo flags to screenshots:all. To drive a demo you started yourself, use npm run screenshots (the bare capture) with ONLY= / OUT_DIR= as needed.

Orchestrator knobs (env vars on capture-docs-screenshots.sh)

Capture knobs (env vars on capture-dashboard-screenshots.mjs)

Tab inventory

The capture covers all 17 dashboard tabs in NAV_TABS order (mockserver-ui/src/components/AppBar.tsx). Navigation clicks the inline [data-nav-tab] toggle, falling back to the overflow / hamburger menu by aria-label when a tab is collapsed. Lazy-loaded tabs (Mocks/Composer, Performance, LLM Optimise, Metrics) wait for their "Loading…" placeholder to clear before the shot.

Tabs added since the existing website images (Performance, LLM Optimise, gRPC, Contract, Cluster) produce new files. To surface them on the site, add an <img> reference in jekyll-www.mock-server.com/mock_server/mockserver_ui.html following the existing <img class="ui_image" …> pattern.

After capturing

1. git status jekyll-www.mock-server.com/images/ — confirm only intended PNGs changed.
2. Open a few PNGs to sanity-check they're fully rendered (no spinners, data present).
3. Commit the images (and any new mockserver_ui.html references) via the normal

pre-commit workflow.

Troubleshooting

• Traffic / Sessions empty ("No captured requests yet") — either the page

wasn't "Connected" when shot, or load injection evicted the seeded traffic past the ~100-item UI cap. screenshots:all already shoots these in the quiet phase-1 demo; if running the bare capture, point it at a npm run demo --with-broker (no --with-load-injection).

• A tab is blank / shows a spinner — raise SETTLE_MS (or the per-tab

SLOW_SETTLE_MS), or the panel needs more demo data (extend mockserver-ui/scripts/populate-demo-data.mjs).

• Metrics/Performance charts say "collecting…" — the demo hasn't generated

enough samples; raise CHART_WARMUP_S (orchestrator) or CHART_SETTLE_MS.

• A `prepare` step is skipped (logged ! <tab> prepare step skipped) — a UI

selector drifted (e.g. the Advanced toggle, the Conversation tab, the HTTP chaos header). The shot still happens, just without the curated state; update the prepare selector in capture-dashboard-screenshots.mjs.

• Demo never reports ready — check the temp log path printed by the

orchestrator; MockServer or Vite likely failed to start (port in use, JAR build error). Raise DEMO_TIMEOUT for slow first-time JAR builds.

• `_load_nvm: command not found` — node is shadowed by the nvm shell

function; invoke the absolute nvm node path (see Prerequisites).

• Async tab empty — Docker isn't running, so --with-broker was a no-op.