Playwright Browser Automation Skill

Purpose

Provides browser automation capabilities through a local Playwright Docker container, eliminating the need for remote MCP server connections. Enables web scraping, E2E testing, screenshot capture, and browser interaction automation.

Capabilities

• Navigation: Load URLs with configurable wait conditions
• Screenshots: Capture full-page or viewport screenshots
• Interaction: Click, fill forms, press keys
• Evaluation: Execute JavaScript in page context
• Testing: End-to-end test automation

Requirements

Docker

• Docker Desktop installed and running
• agent-network Docker network created
• Playwright container running

Ruby

• Ruby ≥2.7
• Gems: websocket-client-simple, json

Setup

# Start Playwright container
cd ~/.claude/skills/playwright-browser/docker
docker-compose up -d

# Verify container is running
docker ps | grep playwright-server

# Check health
curl http://localhost:3000/health

Usage

Navigation

# Navigate to URL
~/.claude/skills/playwright-browser/scripts/navigate.rb "https://example.com"

Screenshots

# Capture screenshot
~/.claude/skills/playwright-browser/scripts/screenshot.rb "https://example.com" /tmp/screenshot.png

# Full-page screenshot
~/.claude/skills/playwright-browser/scripts/screenshot.rb "https://example.com" /tmp/screenshot.png --full-page

JavaScript Evaluation

# Execute JavaScript
~/.claude/skills/playwright-browser/scripts/evaluate.rb "document.title"

# Get page data
~/.claude/skills/playwright-browser/scripts/evaluate.rb "JSON.stringify({title: document.title, url: location.href})"

Docker Management

Start Container

~/.claude/skills/playwright-browser/scripts/start.sh

Stop Container

~/.claude/skills/playwright-browser/scripts/stop.sh

Restart Container

~/.claude/skills/playwright-browser/scripts/restart.sh

Check Status

~/.claude/skills/playwright-browser/scripts/status.sh

Troubleshooting

Container won't start

Symptom: docker-compose up -d fails

Solutions:

1. Check Docker Desktop is running
2. Verify network exists: docker network ls | grep agent-network
3. Check logs: docker-compose logs
4. Try recreating: docker-compose down && docker-compose up -d

Connection refused

Symptom: WebSocket connection fails

Solutions:

1. Verify container is running: docker ps | grep playwright
2. Check health: curl http://localhost:3000/health
3. Check logs: docker logs playwright-server
4. Restart container: docker-compose restart

Slow performance

Symptom: Operations take >5 seconds

Solutions:

1. Check resource allocation in Docker Desktop settings
2. Increase memory limit in docker-compose.yml
3. Verify no other heavy containers running
4. Check system resources: docker stats

Ruby gem errors

Symptom: LoadError for websocket gem

Solutions:

gem install websocket-client-simple
gem install json

Performance Notes

• Container startup: ~20-30 seconds
• API response time: <500ms typical
• Memory usage: ~500MB-1GB
• Suitable for development and light automation

Advanced Configuration

Custom Playwright version

Edit docker-compose.yml:

image: mcr.microsoft.com/playwright:v1.41.0-jammy

Resource limits

Edit docker-compose.yml deploy section:

deploy:
  resources:
    limits:
      memory: 4G
      cpus: '4.0'

See Also

• Chrome DevTools skill for debugging capabilities
• Original research: ~/.claude/claudedocs/research_mcp_to_agent_skill_conversion_20251116.md