t1k:web:testing:chrome-devtools

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	testing
Version	1.7.0
Effort	high
Tools	—

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

How to invoke

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

---

Chrome DevTools Agent Skill

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

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/chrome-devtools/scripts" ]; then
  SKILL_DIR=".claude/skills/chrome-devtools/scripts"
elif [ -d "$HOME/.claude/skills/chrome-devtools/scripts" ]; then
  SKILL_DIR="$HOME/.claude/skills/chrome-devtools/scripts"
fi
# Run scripts with full path: node "$SKILL_DIR/script.js" --args

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

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)

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

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: npx serve (recommended)
npx serve ./dist -p 3000 &
node "$SKILL_DIR/navigate.js" --url http://localhost:3000

# Option 2: Python http.server
python -m http.server 3000 --directory ./dist &
node "$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.

Quick Start

# Install dependencies (one-time setup)
npm install --prefix "$SKILL_DIR"

# Test (browser stays running for session reuse)
node "$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

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)
node "$SKILL_DIR/navigate.js" --url https://example.com/login

# Subsequent scripts: connect to existing browser, reuse page state
node "$SKILL_DIR/fill.js" --selector "#email" --value "[email protected]"
node "$SKILL_DIR/fill.js" --selector "#password" --value "secret"
node "$SKILL_DIR/click.js" --selector "button[type=submit]"

# Close browser when done
node "$SKILL_DIR/navigate.js" --url about:blank --close true

Available Scripts

All in .claude/skills/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

1. Execute focused script for single task
2. Observe JSON output
3. Assess completion status
4. Decide next action
5. Repeat until done

Screenshots

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

Authentication & Cookies

Method 1: Inject Cookies Directly

# Inject single cookie
node "$SKILL_DIR/inject-auth.js" --url https://site.com \
  --cookies '[{"name":"session","value":"abc123","domain":".site.com"}]'

Method 2: Interactive Login (OAuth/SSO)

# Open browser at login page, wait for redirect to dashboard after OAuth
node "$SKILL_DIR/navigate.js" --url https://app.example.com/login \
  --wait-for-login "/dashboard"

Error Recovery

If script fails:

# 1. Capture current state
node "$SKILL_DIR/screenshot.js" --output ./.claude/skills/chrome-devtools/screenshots/debug.png

# 2. Get console errors
node "$SKILL_DIR/console.js" --url about:blank --types error --duration 1000

# 3. Discover correct selector
node "$SKILL_DIR/snapshot.js" | jq '.elements[] | select(.text | contains("Submit"))'

Troubleshooting

Error	Solution
Cannot find package 'puppeteer'	Run npm 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

• ./references/cdp-domains.md - Chrome DevTools Protocol domains
• ./references/puppeteer-reference.md - Puppeteer API patterns
• ./references/performance-guide.md - Core Web Vitals optimization

Gotchas

• Performance recordings reset on tab refresh — capture-then-export, don’t trust live recordings to survive nav.
• Coverage reports include every file traversed, NOT every file used at runtime — interpret carefully.
• Source maps must be uploaded BEFORE first error report — Sentry-style integrations otherwise fingerprint minified stacks.