APAW/README.Docker.md

Docker Testing Environment

Quick guide for running browser automation tests in Docker.

Quick Start

# Build the image
docker-compose build playwright-mcp

# Start MCP server
docker-compose up -d playwright-mcp

# Check logs
docker-compose logs -f playwright-mcp

Available Modes

1. Headless MCP Server (Default)

Best for CI/CD and automated testing:

# Start server
docker-compose up playwright-mcp

# Connect from Kilo Code
# Configure: "url": "http://localhost:8931/mcp"

2. Headed Mode (Visual Debugging)

Best for development and debugging:

# Start with display
docker-compose --profile debug up playwright-headed

# Requires X11 forwarding or VNC

3. Test Runner Mode

Best for running E2E tests:

# Run all tests
docker-compose --profile test up test-runner

# Run specific test
docker-compose run --rm playwright-test npx playwright test e2e/homepage.spec.ts

Environment Variables

Variable	Default	Description
PLAYWRIGHT_MCP_BROWSER	chromium	Browser to use (chromium, firefox, webkit)
PLAYWRIGHT_MCP_HEADLESS	true	Run without visible window
PLAYWRIGHT_MCP_PORT	8931	Port for MCP server
PLAYWRIGHT_MCP_HOST	0.0.0.0	Host to bind
PLAYWRIGHT_MCP_NO_SANDBOX	true	Disable sandbox for Docker

Useful Commands

# Pull official image
docker pull mcr.microsoft.com/playwright:v1.58.2-noble

# Run interactive shell
docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.58.2-noble /bin/bash

# Run MCP server directly
docker run -d -i --rm --init --ipc=host \
  -p 8931:8931 \
  --name playwright-mcp \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

# Check MCP server health
curl http://localhost:8931/health

# View browser versions
docker run --rm mcr.microsoft.com/playwright:v1.58.2-noble npx playwright --version

CI/CD Integration

# .github/workflows/e2e-tests.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.58.2-noble
      options: --ipc=host
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run E2E tests
        run: npx playwright test
      - name: Upload screenshots
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: screenshots
          path: .test/screenshots/

Troubleshooting

Chromium Failed to Launch

# Add --no-sandbox and --disable-dev-shm-usage
docker run --rm --cap-add=SYS_ADMIN mcr.microsoft.com/playwright:v1.58.2-noble

Out of Memory

# Increase shared memory
docker run --shm-size=2g ...

Slow Performance

# Use headless mode
# --headless flag is default in Dockerfile

Performance Metrics

Setup	Startup Time	Memory	Recommended For
Local headless	1-2s	150-250MB	Development
Local headed	2-4s	250-400MB	Debugging
Docker headless	2-5s	300-500MB	CI/CD
Docker headed	3-6s	400-600MB	Visual debugging

Related Files

• Dockerfile.playwright - Custom image with MCP
• docker-compose.yml - Service definitions
• .kilo/skills/playwright/SKILL.md - Playwright usage guide
• .kilo/agents/browser-automation.md - Browser agent