browser-automation

Browser Automation Skill

Explore pages interactively, build reusable flows, and test multi-user scenarios.

Quick Start

# Start server
node .claude/skills/browser-automation/server.mjs &

# Check available profiles
curl http://localhost:9222/profiles

# Create a session
curl -X POST http://localhost:9222/sessions \
  -d '{"name": "test", "url": "http://localhost:3000", "profile": "member"}'

# Inspect the page
curl http://localhost:9222/inspect

# Execute code
curl -X POST http://localhost:9222/chunk \
  -d '{"label": "Click button", "code": "await page.click(\"button.submit\");"}'

# Shutdown
curl -X POST http://localhost:9222/exit

Endpoints

Endpoint	Method	Description
/profiles	GET	List auth profiles with descriptions
/sessions	GET	List active sessions
/sessions	POST	Create session { name, url, profile?, headless? }
/sessions/:name	DELETE	Close session
/flows	GET	List saved flows
/flows/:name/run	POST	Run flow { profile?, startUrl?, headless? }
/status	GET	Session status
/inspect	GET	Page state + screenshot. Add ?fullPage=true for full-page screenshot
/chunk	POST	Execute code { label, code }
/navigate	POST	Navigate { url, fullPage? }. Set fullPage: true for full-page screenshot
/save-auth	POST	Save auth { profile, description }
/review	GET	Review recorded chunks
/exit	POST	Shutdown server

Use ?session=name when multiple sessions are active.

Multi-User Testing

# Create two sessions with different profiles
curl -X POST http://localhost:9222/sessions \
  -d '{"name": "creator", "url": "http://localhost:3000", "profile": "creator"}'
curl -X POST http://localhost:9222/sessions \
  -d '{"name": "viewer", "url": "http://localhost:3000", "profile": "member"}'

# Creator does something
curl -X POST "http://localhost:9222/chunk?session=creator" \
  -d '{"label": "Publish", "code": "await page.click(\"button.publish\");"}'

# Viewer sees it
curl -X POST "http://localhost:9222/navigate?session=viewer" \
  -d '{"url": "http://localhost:3000/models"}'

Profiles

# List profiles
curl http://localhost:9222/profiles

# Create new profile (description required)
curl -X POST http://localhost:9222/save-auth \
  -d '{"profile": "moderator", "description": "User with mod permissions"}'

# Refresh existing profile
curl -X POST http://localhost:9222/save-auth \
  -d '{"profile": "moderator"}'

Profile	Description
moderator	Mod permissions for content review
creator	Established user with published content
member	Standard logged-in user
new-user	Fresh account for onboarding flows

Flows

Saved flows are reusable Playwright scripts.

# List flows
curl http://localhost:9222/flows

# Run a flow
curl -X POST http://localhost:9222/flows/my-flow/run \
  -d '{"profile": "member"}'

# Run with custom start URL
curl -X POST http://localhost:9222/flows/my-flow/run \
  -d '{"profile": "member", "startUrl": "http://localhost:3000"}'

Flows are stored in .browser/flows/*.js.

Playwright Code

Chunks execute with page available:

await page.click('button.submit');
await page.fill('input[name="email"]', '[email protected]');
await page.waitForSelector('h1');
await page.goto('https://example.com');
const title = await page.textContent('h1');

Mockup Comparison

Open local HTML mockups with file:// URLs, then compare to live pages:

# 1. Open mockup and take full-page screenshot
curl -X POST http://localhost:9222/sessions \
  -d '{"name": "compare", "url": "file:///C:/path/to/mockup.html"}'
curl "http://localhost:9222/inspect?session=compare&fullPage=true"

# 2. Navigate to live page and screenshot
curl -X POST "http://localhost:9222/navigate?session=compare" \
  -d '{"url": "http://localhost:3000/page", "fullPage": true}'

# 3. Compare screenshots in session folder

File Locations

• Flows: .browser/flows/*.js
• Profile metadata: .browser/profiles/profiles.meta.json
• Auth state: .browser/profiles/*.json (gitignored)
• Screenshots: .browser/sessions/{id}/screenshots/