t1k:web:testing:chrome-devtools
| Field | Value |
|---|---|
| Module | testing |
| Version | 1.14.9 |
| Effort | high |
| Tools | — |
Keywords: browser, devtools, puppeteer, scraping, screenshots, testing
How to invoke
Section titled “How to invoke”/t1k:web:testing:chrome-devtools[url or task]Chrome DevTools Agent Skill
Section titled “Chrome DevTools Agent Skill”Browser automation via Puppeteer scripts with persistent sessions. All scripts output JSON.
Executed by
Section titled “Executed by”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”):
| Step | Agent |
|---|---|
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 verbatim | t1k-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.”
Skill Location
Section titled “Skill Location”Skills can exist in project-scope or user-scope. Priority: project-scope > user-scope.
# 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" --argsChoosing Your Approach
Section titled “Choosing Your Approach”| Scenario | Approach |
|---|---|
| Source-available sites | Read source code first, write selectors directly |
| Unknown layouts | Use aria-snapshot.js for semantic discovery |
| Visual inspection | Take screenshots to verify rendering |
| Debug issues | Collect console logs, analyze with session storage |
| Accessibility audit | Use ARIA snapshot for semantic structure analysis |
Automation Browsing Running Mode
Section titled “Automation Browsing Running Mode”Browser visibility is resolved automatically by resolveHeadless() in lib/browser.js:
| Environment | Default | Why |
|---|---|---|
| macOS / Windows | Headed (visible) | Better debugging, OAuth login support |
| Linux / WSL | Headless | Servers typically have no display |
CI (CI, GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL env vars) | Headless | No 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).
ARIA Snapshot (Element Discovery)
Section titled “ARIA Snapshot (Element Discovery)”Full ARIA snapshot guide: see references/aria-snapshot-guide.md.
Local HTML Files
Section titled “Local HTML Files”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.
# Option 1: bunx serve (recommended)bunx serve ./dist -p 3000 &bun "$SKILL_DIR/navigate.js" --url http://localhost:3000
# Option 2: Python http.serverpython -m http.server 3000 --directory ./dist &bun "$SKILL_DIR/navigate.js" --url http://localhost:3000Note: when port 3000 is busy, find an available port with lsof -i :3000 and use a different one.
Quick Start
Section titled “Quick Start”# 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.
Session Persistence
Section titled “Session Persistence”Browser state persists across script executions via WebSocket endpoint file (.browser-session.json).
Default behavior: Scripts disconnect but keep browser running for session reuse.
# 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 statebun "$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 donebun "$SKILL_DIR/navigate.js" --url about:blank --close trueAvailable Scripts
Section titled “Available Scripts”All in .claude/skills/t1k-web-testing-chrome-devtools/scripts/:
| Script | Purpose |
|---|---|
navigate.js | Navigate to URLs |
screenshot.js | Capture screenshots (auto-compress >5MB via Sharp) |
click.js | Click elements |
fill.js | Fill form fields |
evaluate.js | Execute JS in page context |
snapshot.js | Extract interactive elements (JSON format) |
aria-snapshot.js | Get ARIA accessibility tree (YAML format with refs) |
select-ref.js | Interact with elements by ref from ARIA snapshot |
console.js | Monitor console messages/errors |
network.js | Track HTTP requests/responses |
performance.js | Measure Core Web Vitals |
ws-debug.js | Debug WebSocket connections (basic) |
ws-full-debug.js | Debug WebSocket with full events/frames |
inject-auth.js | Inject cookies/tokens for authentication |
import-cookies.js | Import cookies from JSON/Netscape file |
connect-chrome.js | Connect to Chrome with remote debugging |
Workflow Loop
Section titled “Workflow Loop”- Execute focused script for single task
- Observe JSON output
- Assess completion status
- Decide next action
- Repeat until done
Screenshots
Section titled “Screenshots”Full screenshots, console log, and patterns reference: see references/script-command-reference.md.
Authentication & Cookies
Section titled “Authentication & Cookies”Method 1: Inject Cookies Directly
Section titled “Method 1: Inject Cookies Directly”# Inject single cookiebun "$SKILL_DIR/inject-auth.js" --url https://site.com \ --cookies '[{"name":"session","value":"abc123","domain":".site.com"}]'Method 2: Interactive Login (OAuth/SSO)
Section titled “Method 2: Interactive Login (OAuth/SSO)”# Open browser at login page, wait for redirect to dashboard after OAuthbun "$SKILL_DIR/navigate.js" --url https://app.example.com/login \ --wait-for-login "/dashboard"Error Recovery
Section titled “Error Recovery”If script fails:
# 1. Capture current statebun "$SKILL_DIR/screenshot.js" --output ./.claude/skills/t1k-web-testing-chrome-devtools/screenshots/debug.png
# 2. Get console errorsbun "$SKILL_DIR/console.js" --url about:blank --types error --duration 1000
# 3. Discover correct selectorbun "$SKILL_DIR/snapshot.js" | jq '.elements[] | select(.text | contains("Submit"))'Troubleshooting
Section titled “Troubleshooting”| Error | Solution |
|---|---|
Cannot find package 'puppeteer' | Run bun install in scripts directory |
libnss3.so missing (Linux) | Run ./install-deps.sh |
| Element not found | Use snapshot.js to find correct selector |
| Script hangs | Use --timeout 60000 or --wait-until load |
| Screenshot >5MB | Auto-compressed; use --max-size 3 for lower |
| Session stale | Delete .browser-session.json and retry |
Reference Documentation
Section titled “Reference Documentation”./references/cdp-domains.md- Chrome DevTools Protocol domains./references/puppeteer-reference.md- Puppeteer API patterns./references/performance-guide.md- Core Web Vitals optimization