# GeoGraSim · Playwright-Test-Suite

**Zweck**: automatisierte Browser-Tests, die das halbe Hundertfach manuelles Durchklicken
ersetzen. Sucht tote Links, geänderte UI-Verhalten, Glossar-Tooltip-Bugs etc.

**Wichtig — Plattformregel**: dies ist eine **Lokal-Test-Suite**. Sie läuft gegen
`http://localhost/geograsim/App/...` (XAMPP). Sie deployt nichts und modifiziert keine
Prod-Daten. Falls jemals Prod-Tests gebraucht werden, muss das explizit konfiguriert sein.

---

## Drei Test-Stufen

| Stufe | Was wird getestet | Tool | Wer macht's | Wann läuft's |
|---|---|---|---|---|
| **1** | Statische Link-Checks · Glossar-Slugs · Sim-Wrapper · Nav-Routes | Playwright headless (Chromium) | Atlas baut + lässt laufen | täglich oder vor jedem Commit |
| **2** | End-to-End-Flows: Login · Sim durchspielen · Submit · Lehrer-Cockpit | Playwright headless + headed bei Debug | Atlas baut + lässt laufen | vor jedem geplanten Deploy |
| **3** | Semantische Review: passt didaktisch · UX · Sinnhaftigkeit | Codex (OpenAI) liest Stufe-1-/2-Reports | Atlas baut Briefing-Bundle · Codex schreibt Review · Thomas moderiert | nach größeren Änderungen oder ad hoc |

---

## Verzeichnisstruktur

```
.dontDeploy/playwright/
├── README.md                       ← dieses File
├── package.json                    ← npm-Dependencies
├── playwright.config.js            ← globale Konfig (baseURL, retries, reporter)
├── .gitignore                      ← node_modules + Reports werden ignoriert
│
├── tests/
│   ├── stufe1-smoke/
│   │   ├── links-static.spec.js    ← Nav-Links, Top-Menü, Footer
│   │   ├── glossar-all.spec.js     ← jeder Glossar-Slug ist erreichbar
│   │   ├── sim-wrappers.spec.js    ← jeder Sim-Wrapper antwortet 200 + rendert
│   │   └── api-routes.spec.js      ← /api/*-Endpunkte antworten (auth-aware)
│   │
│   └── stufe2-flows/
│       ├── login-klassen-code.spec.js
│       ├── sim-klima-start-bis-submit.spec.js
│       ├── teacher-cockpit-tabs.spec.js
│       └── glossar-tooltip-popup.spec.js
│
├── fixtures/
│   ├── known-glossar-slugs.json    ← aktuelle Liste aller Glossar-Slugs
│   ├── known-paths.json            ← alle erwarteten Top-Level-Routes
│   └── test-accounts.json          ← Lokal-Test-Schüler:innen + Lehrer
│
├── reports/                        ← gitignored: HTML-Reports + Screenshots
│   └── (autogeneriert)
│
└── briefing/
    ├── CODEX-BRIEF.md              ← Liebe-Kollege-Brief an Codex
    ├── codex-stufe-3-auftraege.md  ← konkrete Review-Aufträge
    └── _context-bundle/            ← Anlagen für Codex
        ├── geograsim-readme.md     ← Auszug aus CLAUDE.md
        ├── projektkonventionen.md  ← Sprach-Regeln, Bildstil, Lehrplan
        ├── glossar-pattern.md      ← Tooltip-Pattern, Bug-Historie
        └── sim-architektur.md      ← Wrapper, GGS_LIVE_STATE, Live-Cockpit
```

---

## Einrichtung lokal

```bash
cd .dontDeploy/playwright
npm install
npx playwright install chromium    # nur Chromium reicht für die meisten Tests
```

Hinweis: `npm install` zieht `node_modules/` ins Verzeichnis (~250 MB). Das ist
via `.gitignore` ausgeschlossen.

---

## Tests laufen lassen

```bash
# Stufe 1 (Smoke): ~30 Sekunden, headless
npm run test:smoke

# Stufe 2 (Flows): ~3 Minuten, headless
npm run test:flows

# Beides hintereinander
npm test

# Mit UI-Debugger (headed, langsam, sehr nützlich beim Debuggen)
npm run test:debug

# Nur ein Test-File
npx playwright test glossar-all.spec.js

# HTML-Report öffnen
npm run report
```

---

## Was Stufe 1 macht (Smoke)

- **Alle Glossar-Slugs anfahren** (aus DB-Dump in `fixtures/known-glossar-slugs.json`):
  jeden `/glossar?term=<slug>` aufrufen, prüfen ob 200 + Begriff-Titel im DOM
- **Alle Top-Level-Routes** (`fixtures/known-paths.json`):
  `/teacher`, `/schueler`, `/lehrplan`, `/glossar`, `/heli-game`, `/klima-2d`, ...
- **Alle Sim-Wrapper** öffnen, prüfen ob `window.__GGS__` gesetzt ist + game-DOM rendert
- **Glossar-Tooltip-Links auf zentralen Seiten** (Klima-Onboarding, Weltküche): clicken,
  prüfen ob Popup öffnet + Link zum vollen Eintrag funktioniert (Regression für den
  Bug vom 2026-06-10!)

## Was Stufe 2 macht (Flows)

- **Schüler-Login** mit Klassen-Code + Pseudonym + Passwort
- **Klima starten · 10 Klicks machen · submit**: prüft assessment-Submit + Heartbeat
- **Heli M1 · alle Wegpunkte klicken · Startfreigabe**: prüft die Startfreigabe-Logik
  vom 2026-06-10 (Audio-Ende alleine reicht NICHT)
- **Weltküche Pizza · zwei richtige Länder · solved**: prüft Round-End-Anzeige
- **Lehrer-Cockpit · alle 5 Tabs durchklicken**: prüft alle Render-Funktionen
- **Glossar-Tooltip in Weltküche**: Begriff klicken → Popup → „Voller Eintrag" → 200

## Was Stufe 3 macht (Codex-Review)

Codex bekommt:
- HTML-Reports aus Stufe 1 + 2
- Screenshots der wichtigsten Stellen
- Briefing aus `briefing/CODEX-BRIEF.md`
- Kontext-Bundle aus `briefing/_context-bundle/`

Codex schreibt zurück:
- Markdown-Review mit Fundstellen, Schweregrad, Empfehlungen
- KEINE Code-Änderungen — nur Bewertung

---

## Wartung

- **Bei jedem Glossar-Update**: `fixtures/known-glossar-slugs.json` neu dumpen
  (siehe `scripts/dump-glossar-slugs.sql`)
- **Bei jeder neuen Sim**: `fixtures/known-paths.json` ergänzen + neuen Flow-Test bauen
- **Bei jedem Bug-Fix**: ein Regressionstest dazu, damit der Bug nicht wiederkommt

---

Stand: 2026-06-11 · gepflegt von Atlas (Claude Opus 4.7) · Reviews durch Codex (GPT-5/4o)