visual-crawl

Visual Crawl

Randomized visual QA using bdg (browser-debugger-cli). Opens the project, crawls pages at varied breakpoints, screenshots issues, and produces a findings report. No two runs cover the same ground.

Prerequisites

• bdg installed globally (npm install -g browser-debugger-cli@alpha)
• Project dev server running (know the URL and port)
• macOS tiling WM users (AeroSpace, yabai, etc.): after --no-headless, float the browser window to free its viewport

Invocation

User says /visual-crawl or asks for a visual QA pass. Before starting, confirm:

1. Project URL (e.g., http://localhost:4173)
2. Route list — discover from router config or ask the user
3. Dynamic/parameterized routes (/items/[id], /users/:id, etc.) — do any exist, and do they need seeded data to render real content instead of a 404 or empty state? See "Seeding data for dynamic routes" in Phase 0 below.

For keyboard-navigated apps (sections accessed via key bindings rather than URL routing), ask the user for the key-to-section mapping and use bdg dom pressKey to navigate.

The Crawl

Phase 0: Setup

# Check for existing session first
bdg status 2>&1 || true

# Start bdg session (headless only when there is no display; on a Mac it opens a window)
bdg <project-url>

# Create screenshot output directory
OUTDIR="/tmp/visual-crawl-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$OUTDIR"

Store $OUTDIR path — all screenshots go here.

Target-identity guard. bdg attaches to a Chrome instance, and its active target can silently drift to another open tab between commands — you reload and suddenly you're screenshotting a different app on a different port. A URL check isn't enough (two apps can share a path). Before the crawl and before every screenshot, confirm the page is the app you mean by a stable marker — document.title, an app-specific selector, or both — and abort on mismatch rather than capturing the wrong app:

# Set EXPECT to a substring unique to this app's title (or use an app-only selector)
EXPECT="MyApp"
guard() {
  t=$(bdg dom eval "document.title" 2>&1 | tail -1)
  echo "$t" | grep -q "$EXPECT" || { echo "WRONG TARGET ($t) — bdg drifted; stop, restart on the right URL, re-pin"; return 1; }
}
guard || exit 1