playwright-testing

Critical Rules

1. NEVER use curl for testing Drupal pages — it cannot execute JS or simulate user navigation
2. ALWAYS use HTTP (not HTTPS) for all Playwright navigation in DDEV — self-signed SSL certificates cause failures
3. Convert ALL URLs from https:// to http:// before passing to browser_navigate, including drush uli output
4. NEVER create JavaScript files, Node.js scripts, or Playwright test scripts to interact with the browser. Always use the Playwright MCP tools directly. If MCP fails, troubleshoot the connection — do NOT generate script files as a workaround

MCP Connection

Playwright MCP tools (browser_navigate, browser_take_screenshot, etc.) are registered as native tools via the MCP server configuration. They should be available directly — no manual HTTP/SSE protocol is needed.

• MCP URL: http://playwright-mcp:8931/mcp (or $PLAYWRIGHT_MCP_URL)
• Site URL: use $DDEV_HTTP_URL (already HTTP). $DDEV_PRIMARY_URL is HTTPS — if you use it, convert to HTTP first
• Web Container: accessible via ssh web (for commands like drush uli)

If MCP tools are not available

This is a RECOVERY procedure only. If the browser_ tools are visible, skip this entire section.*

If the browser tools are not showing up as available tools:

# 1. Check if Playwright MCP is responding (works without Docker socket)
curl -s --max-time 3 http://playwright-mcp:8931/sse \
  -H "Accept: text/event-stream" | head -1
# Success: "event: endpoint"
# Failure: connection refused → container not running

# 2. Verify environment variable
echo $PLAYWRIGHT_MCP_URL
# Should return: http://playwright-mcp:8931/mcp

# 3. Restart DDEV to recover the container
# (tell the user to run: ddev restart)

NEVER work around a failed MCP connection by writing .js or .mjs files.

Environment Architecture

┌─────────────────────────────────────────────────────────────┐
│  AI Container (OpenCode or Claude Code)                      │
│  - Runs agents, reads files, executes bash                   │
│  - Connects to Web via: ssh web           │
│  - Uses Playwright via: MCP tools (native)                   │
└──────────────┬──────────────────────┬───────────────────────┘
               │ SSH                  │ MCP protocol
               ▼                      ▼
┌──────────────────────────┐  ┌───────────────────────────────┐
│  Web Container           │  │  Playwright MCP Container     │
│  (ddev-{project}-web)    │  │  (ddev-{project}-playwright-  │
│  - PHP, Drupal, Drush    │  │   mcp)                        │
│  - npm, Composer         │  │  - Chromium browser            │
└──────────────────────────┘  │  - MCP tools on port 8931     │
                              │  - Navigates to Web Container  │
                              └───────────────────────────────┘