# Docker Testing Environment

Quick guide for running browser automation tests in Docker.

## Quick Start

```bash
# 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:

```bash
# 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:

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

# Requires X11 forwarding or VNC
```

### 3. Test Runner Mode

Best for running E2E tests:

```bash
# 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

```bash
# 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

```yaml
# .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

```bash
# 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

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

### Slow Performance

```bash
# 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