From 1de0e16c4a2e1542f44aa26ba5d72826a24eea3e Mon Sep 17 00:00:00 2001 From: "matthias.lotz" Date: Wed, 1 Apr 2026 17:33:58 +0200 Subject: [PATCH] docs: add AI browser debugging setup guide for GitHub Copilot Add AI-BROWSER-DEBUG-SETUP.md with step-by-step instructions for enabling Playwright MCP server so GitHub Copilot can access browser DevTools (console errors, network requests, screenshots) in VS Code. Setup covers WSL 2 + nvm environment: - Node.js >= 18 required (documented upgrade path via NodeSource) - VS Code MCP server needs absolute node path (nvm not loaded by VS Code) - --no-sandbox flag required for Chromium in WSL 2 - workbench.browser.enableChatTools must be enabled in VS Code settings Note: .vscode/mcp.json is gitignored (user-local IDE config). --- AI-BROWSER-DEBUG-SETUP.md | 314 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 AI-BROWSER-DEBUG-SETUP.md diff --git a/AI-BROWSER-DEBUG-SETUP.md b/AI-BROWSER-DEBUG-SETUP.md new file mode 100644 index 0000000..48102fc --- /dev/null +++ b/AI-BROWSER-DEBUG-SETUP.md @@ -0,0 +1,314 @@ +# AI Browser Debugging – Setup für GitHub Copilot in VS Code + +Dieses Dokument beschreibt, wie GitHub Copilot (KI) Zugriff auf einen echten Browser bekommt, +um Console-Fehler, Netzwerkanfragen und Screenshots der laufenden React-App zu analysieren. + +**Umgebung:** Windows 11 · Docker Desktop · WSL 2 (Ubuntu) · VS Code (Remote – WSL) + +--- + +## Was wird dadurch möglich? + +Wenn dieses Setup aktiv ist, kann Copilot folgende Browser-Aktionen selbstständig durchführen: + +| Fähigkeit | Beschreibung | +|---|---| +| **Screenshots** | Seite oder einzelne Elemente aufnehmen | +| **Console-Logs** | Alle `console.error`, `console.warn`, etc. lesen | +| **Netzwerkanfragen** | API-Requests und Responses analysieren | +| **JS ausführen** | Beliebiges JavaScript in der laufenden Seite auswerten | +| **Navigation** | URLs aufrufen, zurücknavigieren | +| **UI-Interaktionen** | Klicken, Felder ausfüllen, Hover | + +Der Mechanismus dahinter ist der **Playwright MCP Server** – ein lokaler Prozess in WSL 2, +der einen headless Chromium-Browser startet und diesen über das MCP-Protokoll +für Copilot-Tools bereitstellt. + +--- + +## Voraussetzungen + +- VS Code mit **GitHub Copilot Chat** Extension (empfohlen: ≥ 1.99) +- Node.js in WSL 2 (bereits vorhanden, da das Projekt Node.js nutzt) +- Docker Desktop läuft und die Dev-Umgebung ist gestartet (`./dev.sh`) + → Frontend erreichbar auf `http://localhost:3000` + +--- + +## Setup-Schritte + +### Schritt 1 – Node.js-Version prüfen (WSL 2) + +Playwright benötigt **Node.js ≥ 18**. Die System-Node-Version in Ubuntu ist oft veraltet. Prüfen: + +```bash +node --version +``` + +Falls die Ausgabe **v12 oder v16** zeigt, Node.js 20 nachinstallieren: + +```bash +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs + +# Prüfen: +node --version # sollte v20.x.x zeigen +npm --version # sollte 10.x zeigen +``` + +> Bei Nutzung von **nvm**: aktive Version mit `node --version` prüfen, ggf. `nvm use 20` ausführen. + +### Schritt 2 – Playwright MCP Server installieren + +```bash +npm install -g @playwright/mcp +``` + +### Schritt 3 – Chromium-Browser und System-Abhängigkeiten installieren + +```bash +# Chromium herunterladen (Playwright-eigene Version) +npx playwright install chromium + +# System-Bibliotheken installieren +# WICHTIG: sudo env "PATH=$PATH" verwenden, damit sudo die korrekte +# Node.js-Version (≥ 18) findet und nicht die System-Version (v12) +sudo env "PATH=$PATH" npx playwright install-deps chromium +``` + +> **Warum `sudo env "PATH=$PATH"`?** +> `sudo` setzt standardmäßig einen leeren PATH und findet dann nur den System-Node.js (oft v12), +> der zu alt für Playwright ist. Mit `env "PATH=$PATH"` wird der aktuelle PATH weitergegeben, +> sodass sudo die richtige Node-Version verwendet. + +> **Hinweis:** `install-deps` installiert fehlende Linux-Bibliotheken (libglib, libnss, etc.), +> die Chromium in WSL 2 benötigt. Ohne diesen Schritt startet der Browser nicht. + +### Schritt 4 – VS Code MCP-Konfiguration anlegen + +Datei `.vscode/mcp.json` im Projekt-Root anlegen. + +**Wichtig bei nvm:** VS Code startet MCP-Server-Prozesse ohne das nvm-Environment, +deshalb muss der **absolute Pfad** zu `node` und dem CLI-Script angegeben werden. + +Zuerst die benötigten Pfade ermitteln: + +```bash +which node # z. B. /home/USER/.nvm/versions/node/v21.7.1/bin/node +npm list -g @playwright/mcp # zeigt Installationspfad +``` + +Dann `.vscode/mcp.json` entsprechend anlegen (Pfade anpassen!): + +```json +{ + "servers": { + "playwright": { + "type": "stdio", + "command": "/home/USER/.nvm/versions/node/vX.Y.Z/bin/node", + "args": [ + "/home/USER/.nvm/versions/node/vX.Y.Z/lib/node_modules/@playwright/mcp/cli.js", + "--browser", "chromium", + "--no-sandbox" + ] + } + } +} +``` + +> **Ohne nvm** (system-weites Node.js ≥ 18): `"command": "npx"` mit +> `"args": ["@playwright/mcp@latest", "--browser", "chromium", "--no-sandbox"]` funktioniert direkt. + +> Nach dem Anlegen der Datei: `Ctrl+Shift+P` → *Developer: Reload Window*, +> dann **MCP: List Servers** → `playwright` → **Start Server**. +> Im Output-Log sollte `Discovered X tools` erscheinen. + +### Schritt 5 – Browser-Seiteninhalt für Copilot freischalten + +Damit Copilot auf Console-Logs, Netzwerkanfragen und Screenshots zugreifen kann, +muss eine zusätzliche VS Code-Einstellung aktiviert werden: + +1. `Ctrl+Shift+P` → **Open User Settings (JSON)** +2. Eintragen: + +```json +"workbench.browser.enableChatTools": true +``` + +3. `Ctrl+Shift+P` → **Developer: Reload Window** + +> **Ohne diese Einstellung** öffnet Copilot zwar den Browser, kann aber weder +> Seiteninhalte lesen noch Console-Fehler oder Netzwerkanfragen analysieren. + +### Schritt 6 – Source Maps ✅ (kein Handlungsbedarf) + +Der Frontend-Container startet via `start.sh` den CRA Dev-Server (`react-scripts start`). +Im **Development-Modus** von Create React App sind Source Maps **standardmäßig immer aktiv** – +das Setzen von `GENERATE_SOURCEMAP` ist nur für Production-Builds (`react-scripts build`) relevant. + +**Kein Eingriff in `docker-compose.yml` oder `package.json` nötig.** Fehler werden +automatisch auf die korrekten Quelldateien in `frontend/src/` zurückgeführt. + +### Schritt 7 (optional) – VS Code launch.json für manuelles Developer-Debugging + +Diese Konfiguration gilt für das **eigene Debugging** (nicht für die KI), ermöglicht aber +in VS Code Breakpoints direkt im React-Code zu setzen. + +Datei `.vscode/launch.json` anlegen: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "chrome", + "request": "launch", + "name": "Frontend debuggen (Chrome, Port 3000)", + "url": "http://localhost:3000", + "webRoot": "${workspaceFolder}/frontend/src", + "sourceMapPathOverrides": { + "/app/src/*": "${workspaceFolder}/frontend/src/*" + } + }, + { + "type": "msedge", + "request": "launch", + "name": "Frontend debuggen (Edge, Port 3000)", + "url": "http://localhost:3000", + "webRoot": "${workspaceFolder}/frontend/src", + "sourceMapPathOverrides": { + "/app/src/*": "${workspaceFolder}/frontend/src/*" + } + } + ] +} +``` + +> `sourceMapPathOverrides` ist notwendig, weil der Code im Docker-Container +> unter `/app/src/` liegt, die lokalen Dateien aber unter `frontend/src/`. + +--- + +## Funktionsweise (Überblick) + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Windows 11 Host │ +│ │ +│ VS Code ──── Remote WSL ────► WSL 2 Ubuntu │ +│ │ │ +│ Copilot-Tools │ +│ │ │ +│ Playwright MCP Server │ +│ (npx @playwright/mcp) │ +│ │ │ +│ Chromium (headless) │ +│ │ │ +│ http://localhost:3000 │ +│ │ │ +│ ┌───────────────┘ │ +│ ▼ │ +│ Docker Desktop │ +│ └── image-uploader-frontend-dev │ +│ (nginx, Port 3000 → 80 im Container) │ +└─────────────────────────────────────────────────────────────┘ +``` + +1. Copilot ruft ein Browser-Tool auf (z. B. `take_screenshot` oder `list_console_messages`). +2. VS Code leitet den Aufruf an den Playwright MCP Server weiter. +3. Playwright steuert headless Chromium in WSL 2. +4. Chromium lädt `http://localhost:3000` – Docker Desktop leitet den Port durch. +5. Das Ergebnis (Screenshot, Logs, etc.) kommt zurück zu Copilot. + +--- + +## Verwendung – Copilot ansprechen + +Wenn das Setup aktiv ist, können Anfragen wie folgt gestellt werden: + +``` +Öffne die App auf localhost:3000, navigiere zur Upload-Seite +und zeige mir alle Console-Fehler. +``` + +``` +Mach einen Screenshot der aktuellen Ansicht und erkläre, +was auf der Seite zu sehen ist. +``` + +``` +Schau, welche API-Requests beim Laden der Galerie-Seite +gesendet werden und ob es Fehler gibt. +``` + +--- + +## Troubleshooting + +### Problem: `install-deps` schlägt fehl + +```bash +# Chromium über das System-Paket installieren als Fallback +sudo apt-get update && sudo apt-get install -y chromium-browser + +# Dann Playwright auf den System-Chromium zeigen +PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npx playwright install chromium +``` + +### Problem: Playwright startet nicht (no usable sandbox) + +Chromium in WSL 2 benötigt das `--no-sandbox` Flag. Das Flag wird direkt als +Top-Level-Argument übergeben (nicht als `--browser-arg`): + +```json +{ + "servers": { + "playwright": { + "type": "stdio", + "command": "/home/USER/.nvm/versions/node/vX.Y.Z/bin/node", + "args": [ + "/home/USER/.nvm/versions/node/vX.Y.Z/lib/node_modules/@playwright/mcp/cli.js", + "--browser", "chromium", + "--no-sandbox" + ] + } + } +} +``` + +### Problem: `localhost:3000` nicht erreichbar + +```bash +# Prüfen, ob die Dev-Container laufen +docker compose -f docker/dev/docker-compose.yml ps + +# Falls nicht: Dev-Umgebung starten +./dev.sh +``` + +### Problem: MCP-Server startet, aber Tools sind nicht verfügbar + +- VS Code-Fenster neu laden: `Ctrl+Shift+P` → *Developer: Reload Window* +- Sicherstellen, dass `"workbench.browser.enableChatTools": true` in den User Settings gesetzt ist +- Copilot Chat Extension ≥ 1.99 prüfen +- `.vscode/mcp.json` auf JSON-Syntaxfehler prüfen +- Im MCP-Output-Log prüfen: `Ctrl+Shift+P` → *Output: Show Output Channels* → **MCP** + +### Problem: Source Maps zeigen falschen Pfad + +Der `sourceMapPathOverrides`-Eintrag in `launch.json` muss den Container-Pfad +(`/app/src/*`) auf den lokalen Pfad (`frontend/src/*`) abbilden. +Prüfen, ob der Pfad im Container korrekt ist: + +```bash +docker exec image-uploader-frontend-dev ls /app/src +``` + +--- + +## Weiterführende Links + +- [Playwright MCP auf npm](https://www.npmjs.com/package/@playwright/mcp) +- [VS Code MCP-Dokumentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) +- [VS Code Chrome Debugger](https://code.visualstudio.com/docs/nodejs/browser-debugging) +- [Playwright in WSL 2](https://playwright.dev/docs/browsers#install-system-dependencies)