Skip to content

t1k:web:testing:chrome-devtools

FieldValue
Moduletesting
Version1.14.9
Efforthigh
Tools—

Keywords: browser, devtools, puppeteer, scraping, screenshots, testing

/t1k:web:testing:chrome-devtools
[url or task]

Browser automation via Puppeteer scripts with persistent sessions. All scripts output JSON.

Most of this skill is judgment work — choosing a selector strategy for an unknown layout, diagnosing a JavaScript error from a console trace, deciding whether a screenshot shows a real regression — and stays on a reasoning tier. Two narrow slices are fully mechanical once the script has run (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
Run performance.js and report the Core Web Vitals numbers into a table (no verdict on whether they regressed)t1k-metrics-reporter
Run console.js / network.js and quote the captured log verbatimt1k-fact-fetcher

Everything upstream of those two calls — which selector to use, what the console trace means, whether a screenshot diff is a real regression — reads the captured output and forms a judgment, so it stays on a reasoning tier. A cheap agent should never be the one deciding a page “looks broken.”

Skills can exist in project-scope or user-scope. Priority: project-scope > user-scope.

Terminal window
# Detect skill location (no cd needed - scripts use __dirname for paths)
SKILL_DIR=""
if [ -d ".claude/skills/t1k-web-testing-chrome-devtools/scripts" ]; then
SKILL_DIR=".claude/skills/t1k-web-testing-chrome-devtools/scripts"
elif [ -d "$HOME/.claude/skills/t1k-web-testing-chrome-devtools/scripts" ]; then
SKILL_DIR="$HOME/.claude/skills/t1k-web-testing-chrome-devtools/scripts"
fi
# Run scripts with full path: bun "$SKILL_DIR/script.js" --args
ScenarioApproach
Source-available sitesRead source code first, write selectors directly
Unknown layoutsUse aria-snapshot.js for semantic discovery
Visual inspectionTake screenshots to verify rendering
Debug issuesCollect console logs, analyze with session storage
Accessibility auditUse ARIA snapshot for semantic structure analysis

Browser visibility is resolved automatically by resolveHeadless() in lib/browser.js:

EnvironmentDefaultWhy
macOS / WindowsHeaded (visible)Better debugging, OAuth login support
Linux / WSLHeadlessServers typically have no display
CI (CI, GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL env vars)HeadlessNo display available

Override with --headless true or --headless false on any script.

  • Run multiple scripts/sessions in parallel to simulate real user interactions.
  • Run multiple scripts/sessions in parallel to simulate different device types (mobile, tablet, desktop).

Full ARIA snapshot guide: see references/aria-snapshot-guide.md.

IMPORTANT: Never browse local HTML files via file:// protocol. Always serve via local server: Why: file:// protocol blocks many browser features (CORS, ES modules, fetch API, service workers). Local server ensures proper HTTP behavior.

Terminal window
# Option 1: bunx serve (recommended)
bunx serve ./dist -p 3000 &
bun "$SKILL_DIR/navigate.js" --url http://localhost:3000
# Option 2: Python http.server
python -m http.server 3000 --directory ./dist &
bun "$SKILL_DIR/navigate.js" --url http://localhost:3000

Note: when port 3000 is busy, find an available port with lsof -i :3000 and use a different one.

Terminal window
# Install dependencies (one-time setup)
bun install --cwd "$SKILL_DIR"
# Test (browser stays running for session reuse)
bun "$SKILL_DIR/navigate.js" --url https://example.com
# Output: {"success": true, "url": "...", "title": "..."}

Linux/WSL only: Run "$SKILL_DIR/install-deps.sh" first for Chrome system libraries.

Browser state persists across script executions via WebSocket endpoint file (.browser-session.json).

Default behavior: Scripts disconnect but keep browser running for session reuse.

Terminal window
# First script: launches browser, navigates, disconnects (browser stays running)
bun "$SKILL_DIR/navigate.js" --url https://example.com/login
# Subsequent scripts: connect to existing browser, reuse page state
bun "$SKILL_DIR/fill.js" --selector "#email" --value "user@example.com"
bun "$SKILL_DIR/fill.js" --selector "#password" --value "secret"
bun "$SKILL_DIR/click.js" --selector "button[type=submit]"
# Close browser when done
bun "$SKILL_DIR/navigate.js" --url about:blank --close true

All in .claude/skills/t1k-web-testing-chrome-devtools/scripts/:

ScriptPurpose
navigate.jsNavigate to URLs
screenshot.jsCapture screenshots (auto-compress >5MB via Sharp)
click.jsClick elements
fill.jsFill form fields
evaluate.jsExecute JS in page context
snapshot.jsExtract interactive elements (JSON format)
aria-snapshot.jsGet ARIA accessibility tree (YAML format with refs)
select-ref.jsInteract with elements by ref from ARIA snapshot
console.jsMonitor console messages/errors
network.jsTrack HTTP requests/responses
performance.jsMeasure Core Web Vitals
ws-debug.jsDebug WebSocket connections (basic)
ws-full-debug.jsDebug WebSocket with full events/frames
inject-auth.jsInject cookies/tokens for authentication
import-cookies.jsImport cookies from JSON/Netscape file
connect-chrome.jsConnect to Chrome with remote debugging
  1. Execute focused script for single task
  2. Observe JSON output
  3. Assess completion status
  4. Decide next action
  5. Repeat until done

Full screenshots, console log, and patterns reference: see references/script-command-reference.md.

Terminal window
# Inject single cookie
bun "$SKILL_DIR/inject-auth.js" --url https://site.com \
--cookies '[{"name":"session","value":"abc123","domain":".site.com"}]'
Terminal window
# Open browser at login page, wait for redirect to dashboard after OAuth
bun "$SKILL_DIR/navigate.js" --url https://app.example.com/login \
--wait-for-login "/dashboard"

If script fails:

Terminal window
# 1. Capture current state
bun "$SKILL_DIR/screenshot.js" --output ./.claude/skills/t1k-web-testing-chrome-devtools/screenshots/debug.png
# 2. Get console errors
bun "$SKILL_DIR/console.js" --url about:blank --types error --duration 1000
# 3. Discover correct selector
bun "$SKILL_DIR/snapshot.js" | jq '.elements[] | select(.text | contains("Submit"))'
ErrorSolution
Cannot find package 'puppeteer'Run bun install in scripts directory
libnss3.so missing (Linux)Run ./install-deps.sh
Element not foundUse snapshot.js to find correct selector
Script hangsUse --timeout 60000 or --wait-until load
Screenshot >5MBAuto-compressed; use --max-size 3 for lower
Session staleDelete .browser-session.json and retry
  • ./references/cdp-domains.md - Chrome DevTools Protocol domains
  • ./references/puppeteer-reference.md - Puppeteer API patterns
  • ./references/performance-guide.md - Core Web Vitals optimization