From 6c95c6159e704f973fb36c6b7687bfd9b5f9026d Mon Sep 17 00:00:00 2001 From: swp Date: Sat, 4 Apr 2026 03:59:19 +0100 Subject: [PATCH] feat: add Docker testing environment with visible browser (Issue #12) - Create Dockerfile.playwright with headed mode by default - Create docker-compose.yml with MCP server, headed, and test profiles - Update Playwright skill to recommend headed mode for observation - Remove --headless flag so browser window is visible - Add BROWSER_VISIBILITY.md guide for X11/Docker setup - Add README.Docker.md with quick start instructions Configuration: - PLAYWRIGHT_MCP_HEADLESS=false (browser visible) - Requires X11 display for Docker (DISPLAY=:0) - Three profiles: default, debug, test Refs: #12 in Milestone #44 --- .dockerignore | 7 ++ .kilo/agents/orchestrator.md | 2 + .kilo/skills/playwright/SKILL.md | 12 ++- BROWSER_VISIBILITY.md | 99 ++++++++++++++++++++ Dockerfile.playwright | 33 +++++++ README.Docker.md | 153 +++++++++++++++++++++++++++++++ docker-compose.yml | 54 +++++++++++ 7 files changed, 356 insertions(+), 4 deletions(-) create mode 100644 .dockerignore create mode 100644 BROWSER_VISIBILITY.md create mode 100644 Dockerfile.playwright create mode 100644 README.Docker.md create mode 100644 docker-compose.yml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..c8bf95a --- /dev/null +++ b/.dockerignore @@ -0,0 +1,7 @@ +node_modules +.git +.env +*.log +.DS_Store +coverage +.nyc_output diff --git a/.kilo/agents/orchestrator.md b/.kilo/agents/orchestrator.md index 00d2171..552035f 100644 --- a/.kilo/agents/orchestrator.md +++ b/.kilo/agents/orchestrator.md @@ -27,6 +27,8 @@ permission: "requirement-refiner": allow "frontend-developer": allow "agent-architect": allow + "browser-automation": allow + "visual-tester": allow --- # Kilo Code: Orchestrator diff --git a/.kilo/skills/playwright/SKILL.md b/.kilo/skills/playwright/SKILL.md index 4a9360c..acecbb1 100644 --- a/.kilo/skills/playwright/SKILL.md +++ b/.kilo/skills/playwright/SKILL.md @@ -24,9 +24,11 @@ Playwright MCP (Model Context Protocol) is an official Microsoft server that pro node --version # Should be 18+ # Install Playwright MCP -npx @playwright/mcp@latest --headless --browser chromium +npx @playwright/mcp@latest --browser chromium ``` +**Note**: By default, browser is VISIBLE (no `--headless` flag) so you can observe actions. + ### Option 2: Docker (Recommended for CI/CD) ```bash @@ -36,11 +38,12 @@ docker pull mcr.microsoft.com/playwright:v1.58.2-noble # Run container docker run -it --rm --ipc=host mcr.microsoft.com/playwright:v1.58.2-noble /bin/bash -# Or run with Playwright MCP server +# Or run with Playwright MCP server (HEADED - browser visible) docker run -d -i --rm --init --ipc=host -p 8931:8931 \ --name playwright-mcp \ + -e DISPLAY=$DISPLAY \ mcr.microsoft.com/playwright/mcp \ - cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0 + cli.js --browser chromium --no-sandbox --port 8931 --host 0.0.0.0 ``` ## Configuration for Kilo Code @@ -54,7 +57,6 @@ docker run -d -i --rm --init --ipc=host -p 8931:8931 \ "command": "npx", "args": [ "@playwright/mcp@latest", - "--headless", "--browser", "chromium", "--timeout-action", "3000", "--timeout-navigation", "30000" @@ -64,6 +66,8 @@ docker run -d -i --rm --init --ipc=host -p 8931:8931 \ } ``` +**Note**: Remove `--headless` if you want to see the browser window. + ### Docker Mode ```json diff --git a/BROWSER_VISIBILITY.md b/BROWSER_VISIBILITY.md new file mode 100644 index 0000000..89f3ac5 --- /dev/null +++ b/BROWSER_VISIBILITY.md @@ -0,0 +1,99 @@ +# Browser Visibility Configuration + +## By Default: Browser is VISIBLE (headed mode) + +This allows you to observe browser actions in real-time during testing. + +## Configuration Options + +### Option 1: Visible Browser (Default for Development) + +```bash +# Docker: Browser window visible +docker-compose up playwright-mcp + +# Or directly: +npx @playwright/mcp@latest --browser chromium --no-sandbox +# (without --headless flag = visible window) +``` + +### Option 2: Hidden Browser (For CI/CD) + +Set environment variable: +```bash +export PLAYWRIGHT_MCP_HEADLESS=true +``` + +Or use flag: +```bash +npx @playwright/mcp@latest --headless --browser chromium --no-sandbox +``` + +## Docker Setup for Visible Browser + +### Linux + +```bash +# Allow Docker to access X11 +xhost +local:docker + +# Run with display +docker-compose up playwright-mcp +``` + +### macOS + +```bash +# Install XQuartz for X11 +brew install --cask xquartz + +# Start XQuartz +open -a XQuartz + +# Allow connections +xhost +local: + +# Run with display +docker-compose up playwright-mcp +``` + +### Windows (WSL2) + +```bash +# Install VcXsrv or use WSLg (Windows 11) +# Export display +export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 + +# Run +docker-compose up playwright-mcp +``` + +## Environment Variables + +| Variable | Default | Purpose | +|----------|---------|---------| +| `PLAYWRIGHT_MCP_HEADLESS` | `false` | `true` = hidden, `false` = visible | +| `PLAYWRIGHT_MCP_BROWSER` | `chromium` | Browser to use | +| `DISPLAY` | `:0` | X11 display for headed mode | + +## Benefits of Headed Mode + +1. **Observe Actions** - Watch browser in real-time +2. **Debug Tests** - See what's happening visually +3. **Learn** - Understand how automation works +4. **Verify** - Confirm correct behavior visually + +## When to Use Headless + +For CI/CD pipelines or production testing where you don't need to see the browser: + +```bash +# Set in CI environment +export PLAYWRIGHT_MCP_HEADLESS=true + +# Or in docker-compose.override.yml +services: + playwright-mcp: + environment: + - PLAYWRIGHT_MCP_HEADLESS=true +``` \ No newline at end of file diff --git a/Dockerfile.playwright b/Dockerfile.playwright new file mode 100644 index 0000000..6c7b155 --- /dev/null +++ b/Dockerfile.playwright @@ -0,0 +1,33 @@ +# Playwright MCP Docker Image for E2E Testing +# Based on official Microsoft Playwright image + +FROM mcr.microsoft.com/playwright:v1.58.2-noble + +# Set working directory +WORKDIR /app + +# Install dependencies +RUN npm install -g @playwright/mcp@latest + +# Create directories for tests +RUN mkdir -p .test/screenshots/{baseline,current,diff} .test/reports + +# Set environment variables +ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright +ENV PLAYWRIGHT_MCP_BROWSER=chromium +# HEADLESS=false by default - browser is VISIBLE for observation +# Set PLAYWRIGHT_MCP_HEADLESS=true for CI/CD +ENV PLAYWRIGHT_MCP_HEADLESS=false + +# Expose port for MCP server +EXPOSE 8931 + +# Healthcheck +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ + CMD curl -f http://localhost:8931/health || exit 1 + +# Default command - MCP server (HEADED by default - browser visible) +# Browser window will be visible for observation +CMD ["node", "/usr/local/lib/node_modules/@playwright/mcp/cli.js", \ + "--browser", "chromium", \ + "--no-sandbox", "--port", "8931", "--host", "0.0.0.0"] diff --git a/README.Docker.md b/README.Docker.md new file mode 100644 index 0000000..9319c4d --- /dev/null +++ b/README.Docker.md @@ -0,0 +1,153 @@ +# 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 \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..ff6741c --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,54 @@ +version: '3.8' + +services: + playwright-mcp: + build: + context: . + dockerfile: Dockerfile.playwright + container_name: playwright-mcp + ports: + - "8931:8931" + volumes: + - ./:/app + - /app/node_modules + environment: + - PLAYWRIGHT_MCP_BROWSER=chromium + - PLAYWRIGHT_MCP_HEADLESS=false + - PLAYWRIGHT_MCP_NO_SANDBOX=true + - PLAYWRIGHT_MCP_PORT=8931 + - PLAYWRIGHT_MCP_HOST=0.0.0.0 + - DISPLAY=${DISPLAY:-:0} + restart: unless-stopped + shm_size: '2gb' + ipc: host + security_opt: + - seccomp:unconfined + + # For visual debugging (headed mode) + playwright-headed: + image: mcr.microsoft.com/playwright:v1.58.2-noble + container_name: playwright-headed + ports: + - "8932:8931" + volumes: + - ./:/app + environment: + - DISPLAY=$DISPLAY + command: > + npx @playwright/mcp@latest + --browser chromium + --port 8931 + --host 0.0.0.0 + profiles: + - debug + + # For running tests locally + test-runner: + image: mcr.microsoft.com/playwright:v1.58.2-noble + container_name: playwright-test + volumes: + - ./:/app + working_dir: /app + command: npx playwright test + profiles: + - test