toolkit

Screenshots · Playbook

Screenshot capture & visual regression — high-level pointers (local fallback)

viewvee captures what a page looks like, across devices, reliably. The detailed, current capture & visual-regression standards — which device suite to use for which client tier, how to clear a stubborn bot-challenge beyond --channel chrome, fail-over thresholds per site type, and baseline-refresh cadence — live in the team wiki (set OUTLINE + OUTLINE_API_URL and the report links them directly). This file is the minimal high-level fallback for when the wiki isn’t configured: direction only, deliberately not step-by-step, so there’s no detailed content to drift out of sync with the wiki.

  • Leave lazy-load handling on — the default auto-scroll + animation-freeze + image-decode wait is what makes full-page shots of image-heavy sites come out complete; only disable it to debug.
  • A bot-challenge capture is not a real capture — never save a ⚠ possible bot-challenge screenshot as a baseline; retry with --channel chrome --headed first. That retry clears simpler bot walls but not a Turnstile managed/under-attack challenge — Cloudflare re-checks the automated browser’s own fingerprint on every request, so not even a real Chrome profile’s live cf_clearance cookie gets through one. The only real path is a human clearing it once, or the site operator pausing Under Attack/Bot-Fight mode (issue #530).
  • --dismiss-overlays is best-effort, --hide is deterministic — for a baseline that must be reproducible (visual regression), prefer explicit --hide <selector> over relying on the best-effort overlay dismissal.
  • PNG for diffing, JPEG for archiving — viewvee diff only compares PNG captures; switch to --format jpeg for sharing or long-term storage, not for a pair you intend to diff later.
  • A THIN batch result usually means lazy-load didn’t finish — it auto-retries once with a longer settle; if it’s still THIN, raise --settle rather than trusting the short capture.
  • Tracking is blocked by default — a run never registers in a site’s live GA4/GTM; only pass --allow-tracking when you specifically need to verify tag firing.
  • A WAF-skip header is for zones you control — the browser applies -H to every request the page makes, including third-party subresources; don’t send a secret to hosts you don’t own.

Full playbook → the team wiki’s screenshot-capture & visual-regression standards.