Patchright - Browser Automation Skill

Patchright-based browser automation with bot detection bypass. Use for localhost, dev servers, web app testing, screenshots, and UI interactions.

Triggers

URL/Network:

• localhost (http://localhost:, http://127.0.0.1:)
• Local IPs (192.168.x.x, 10.x.x.x, 172.16-31.x.x)
• Dev server ports (3000, 5173, 8080, 4200, 5000, etc.)

Web App Testing:

• "test the app", "check the site"
• "open localhost", "view in browser"
• "take screenshot", "capture screen"
• "check UI", "view page"
• QA, E2E testing, dev build verification

Browser Interaction:

• "click", "press button"
• "type", "fill form"
• "login", "sign up"
• "open menu", "click tab"
• "scroll", "navigate"

Visual Verification:

• "how does it look?", "is it working?"
• "check design", "verify layout"
• "responsive test", "screen size"
• "check rendering", "verify component"

Development Workflow:

• Verify changes after code edits
• Frontend debugging
• Real-time dev feedback
• Pre-deployment checks

Core: Server Mode (Session Persistence!)

Problem: scripts/executor.py terminates process on each call -> browser session lost Solution: scripts/server.py runs background server -> session persists

Start Server (Required!)

bash
1cd ~/.claude/skills/patchright-skill
2python scripts/server.py start &

Server Commands

bash
1# Check status
2python scripts/server.py status
3
4# Stop server
5python scripts/server.py stop
6
7# Call tool
8python scripts/server.py call '{"tool": "...", "args": {...}}'

Usage

1. Navigate + Screenshot (Most Common Pattern)

bash
1cd ~/.claude/skills/patchright-skill
2
3# Start server (if not running)
4python scripts/server.py start &
5sleep 2
6
7# Navigate to page
8python scripts/server.py call '{"tool": "navigate", "args": {"url": "http://localhost:3000"}}'
9
10# Take screenshot
11python scripts/server.py call '{"tool": "screenshot", "args": {"path": "screenshot.png", "full_page": true}}'

2. Click + Interaction

bash
1# Click element
2python scripts/server.py call '{"tool": "click", "args": {"selector": "button.submit"}}'
3python scripts/server.py call '{"tool": "click", "args": {"selector": "#menu-btn"}}'
4python scripts/server.py call '{"tool": "click", "args": {"selector": "body"}}'  # Click anywhere
5
6# Type text
7python scripts/server.py call '{"tool": "type", "args": {"selector": "#email", "text": "test@test.com"}}'
8python scripts/server.py call '{"tool": "type", "args": {"selector": "input[name=password]", "text": "password123"}}'

3. Get Information

bash
1# Current URL
2python scripts/server.py call '{"tool": "get_url"}'
3
4# Page title
5python scripts/server.py call '{"tool": "get_title"}'
6
7# Element text
8python scripts/server.py call '{"tool": "get_text", "args": {"selector": ".error-message"}}'

4. Wait

bash
1# Wait for element to appear
2python scripts/server.py call '{"tool": "wait_for", "args": {"selector": ".loading-complete", "timeout": 10000}}'

Tool Reference

Examples

Login Test

bash
1cd ~/.claude/skills/patchright-skill
2python scripts/server.py start &
3sleep 2
4
5# Navigate to login page
6python scripts/server.py call '{"tool": "navigate", "args": {"url": "http://localhost:3000/login"}}'
7python scripts/server.py call '{"tool": "screenshot", "args": {"path": "login_page.png"}}'
8
9# Fill form
10python scripts/server.py call '{"tool": "type", "args": {"selector": "#email", "text": "admin@test.com"}}'
11python scripts/server.py call '{"tool": "type", "args": {"selector": "#password", "text": "admin123"}}'
12python scripts/server.py call '{"tool": "screenshot", "args": {"path": "login_filled.png"}}'
13
14# Submit
15python scripts/server.py call '{"tool": "click", "args": {"selector": "button[type=submit]"}}'
16sleep 2
17python scripts/server.py call '{"tool": "screenshot", "args": {"path": "login_result.png"}}'

App Navigation

bash
1# Enter app
2python scripts/server.py call '{"tool": "navigate", "args": {"url": "http://localhost:3000"}}'
3python scripts/server.py call '{"tool": "click", "args": {"selector": "body"}}'  # Click to enter
4sleep 2
5python scripts/server.py call '{"tool": "screenshot", "args": {"path": "app_main.png", "full_page": true}}'
6
7# Explore features
8python scripts/server.py call '{"tool": "click", "args": {"selector": ".create-btn"}}'
9python scripts/server.py call '{"tool": "screenshot", "args": {"path": "after_action.png"}}'

Selector Tips

css
1/* ID */
2#submit-btn
3
4/* Class */
5.nav-menu
6button.primary
7
8/* Attribute */
9input[type=email]
10button[data-testid="login"]
11a[href="/about"]
12
13/* Text content */
14text=Login
15text=Submit
16
17/* Combined */
18form#login button[type=submit]
19.sidebar .menu-item:first-child

Technical Specs

• Engine: patchright (undetected playwright fork)
• Browser: Google Chrome (channel: 'chrome')
• Bot Detection Bypass: YES (Cloudflare, reCAPTCHA, etc.)
• Localhost Support: YES
• Private IP Support: YES
• Server Port: 9222

Troubleshooting

"Server not running" error:

bash
1python scripts/server.py start &
2sleep 2

Browser not visible:

• headless=False is default, browser window should appear
• In server mode, browser persists in background

Session disconnected:

• Use scripts/server.py instead of scripts/executor.py
• Server keeps session alive once started

Element not found:

• Use wait_for to wait first
• Verify selector in DevTools