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).
This commit is contained in:
parent
382097ab54
commit
1de0e16c4a
314
AI-BROWSER-DEBUG-SETUP.md
Normal file
314
AI-BROWSER-DEBUG-SETUP.md
Normal file
|
|
@ -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)
|
||||
Loading…
Reference in New Issue
Block a user