test-ui

Chrome DevTools Agent Skill

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

Summary

Goal: Automate browser interactions, take screenshots, and analyze performance using Puppeteer CLI scripts.

Key Principles:

• Never use file:// for local HTML -- serve via npx serve instead
• Session persists between scripts; delete .browser-session.json to reset
• Source-available sites: read source first for selectors; unknown layouts: use aria-snapshot.js

⚠️ MUST READ References

IMPORTANT: You MUST read these reference files for complete protocol. Do NOT skip.

• ⚠️ MUST READ references/devtools-patterns.md — ARIA, screenshots, console, custom scripts
• ⚠️ MUST READ references/cdp-domains.md — CDP domain reference
• ⚠️ MUST READ references/puppeteer-reference.md — Puppeteer API reference
• ⚠️ MUST READ references/performance-guide.md — Performance analysis guide
• ⚠️ MUST READ scripts/README.md — Script options reference

Choosing Your Approach

Quick Start

cd .claude/skills/test-ui/scripts
npm install
node navigate.js --url https://example.com
# Headless on Linux/WSL/CI; headed on macOS/Windows
# Linux/WSL: Run ./install-deps.sh first for Chrome system libraries

Session Persistence

Browser state persists via .browser-session.json. Scripts disconnect but keep browser running.

node navigate.js --url https://example.com/login
node fill.js --selector "#email" --value "user@example.com"
node click.js --selector "button[type=submit]"
node navigate.js --url about:blank --close true   # Close when done

Available Scripts

All in .claude/skills/test-ui/scripts/:

Script Options (All scripts)

• --headless false - Show browser window
• --close true - Close browser completely
• --timeout 30000 - Set timeout (ms)
• --wait-until networkidle2 - Wait strategy

Common Patterns

# Web scraping
node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent, link: el.querySelector('a')?.href
  }))" | jq '.result'

# Form automation
node fill.js --selector "#search" --value "query"
node click.js --selector "button[type=submit]"

# Performance
node performance.js --url https://example.com | jq '.vitals'

Local HTML Files

Never use file://. Serve via local server: npx serve ./dist -p 3000 &

Troubleshooting

IMPORTANT Task Planning Notes

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed