Initial project version

README.md

@@ -0,0 +1,187 @@
+# Aegis Labyrinth – Test- & Audit-Suite
+
+> Automatisierte **Test-, Audit- und Performance-Suite** für das Single-File-Browser-Game `Aegis-Labyrinth.html`.
+> Dieses Repo enthält **nicht** das Spiel selbst – es enthält die Werkzeuge, um die Game-Source-Datei im vollen Umfang zu testen, zu auditieren und als Audit-Bericht auszuwerten.
+
+**Ziel:** Jede Änderung an `Aegis-Labyrinth.html` automatisch validieren – Funktionalität (3 Audits), Regressionsschutz (Self-Play), Performance (FPS/Heap) und einen maschinenlesbaren + HTML-Bericht erzeugen.
+
+![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)
+
+> 📜 **Version & Historie:** Laufende Version + Changelog in [`CHANGELOG.md`](./CHANGELOG.md)
+> (aktuell: **Game `1.0.2`**, **Suite `1.0.0`**).
+
+## ⚠️ Voraussetzung: Game-Datei manuell legen
+
+Die zu testende Datei **`Aegis-Labyrinth.html`** gehört **nicht** zu diesem Repo (wird nicht versioniert).
+Lege/kopiere sie **vor** dem ersten Testlauf in die Projekt-Root:
+
+```
+Laby/
+├── Aegis-Labyrinth.html      ← ⚠️ MANUELL HINZUFÜGEN (Source of truth, extern)
+└── ...
+```
+
+Alle Test-Skripte erwarten die Datei an genau diesem Ort (Projekt-Root).
+Fehlt sie, bricht `audit.mjs` mit `❌ Aegis-Labyrinth.html nicht gefunden!` ab.
+
+> Tipp: Damit die Datei nicht versehentlich committet wird, `Aegis-Labyrinth.html` in die `.gitignore` aufnehmen.
+
+---
+
+## Was wird getestet?
+
+| Suite | Skript | Was es prüft | Ausgabe |
+|---|---|---|---|
+| **Audit** | `tests/audit.mjs` | Die 3 eingebauten Audits: `runSelfAudit`, `runExtensionAudit`, `runRedesignAudit` + JS-Page-Errors + Assertions | `audit-result.json` |
+| **Self-Play** | `tests/selfplay.mjs` | Deterministischer Bot spielt Level 0 durch → Regressionsschutz & Balance | `selfplay-results.json` |
+| **Performance** | `tests/perf-test.mjs` | FPS unter Last (schweres Level + viele Türme) + Heap | `perf-result.json` |
+| **Report** | `tests/report.mjs` | Fügt alle `*-result.json` zu einem HTML-Report zusammen | `report.html` |
+
+---
+
+## Setup
+
+```bash
+# 1. Dependencies (Playwright + Chromium)
+npm install
+npx playwright install chromium
+
+# 2. Game-Datei in die Projekt-Root legen
+#    → Aegis-Labyrinth.html manuell kopieren (siehe oben)
+```
+
+> `node >= 18` wird empfohlen (Top-Level-`await` in den `.mjs`-Skripten).
+
+---
+
+## Quick-Start / Ausführung
+
+Jedes Skript ist auch als npm-Script verfügbar:
+
+```bash
+npm run audit      # node tests/audit.mjs            → audit-result.json
+npm run selfplay   # node tests/selfplay.mjs [n]     → selfplay-results.json   (Default 10 Episoden)
+npm run perf       # node tests/perf-test.mjs [ms] [towers] → perf-result.json (Default 15000ms / 50 Türme)
+npm run report     # node tests/report.mjs           → report.html
+
+# Kompletter Lauf (Audit + Self-Play + Perf)
+npm test
+```
+
+Direkt aufrufen (nützlich für CI / Parameter):
+
+```bash
+node tests/selfplay.mjs 50        # 50 Episoden
+node tests/perf-test.mjs 30000 80 # 30 s messen, 80 Türme
+```
+
+### Exit-Code-Vertrag
+
+| Skript | `exit 0` | `exit ≠ 0` |
+|---|---|---|
+| `audit.mjs` | alle Assertions grün, keine Page-Errors | ≥ 1 Fehler (Assertion / Page-Error) → `1`, Crash → `2` |
+| `perf-test.mjs` | FPS ≥ Zielwert (55) | FPS < Zielwert → `1` |
+| `selfplay.mjs` | (liefert immer 0) | – |
+| `report.mjs` | (liefert immer 0) | – |
+
+---
+
+## Die getestete Debug-API
+
+Die Suite hängt vollständig an der **öffentlichen Debug-API** des Games (`window.__AEGIS_DEBUG__`) plus frei im Global Scope liegenden Funktionen. Details: [`docs/01_Debug_API.md`](./docs/01_Debug_API.md).
+
+```js
+// State lesen
+window.__AEGIS_DEBUG__.getState()
+
+// Level / Credits / Wave
+window.__AEGIS_DEBUG__.selectLevel(0)
+window.__AEGIS_DEBUG__.setCredits(999999)
+window.__AEGIS_DEBUG__.startWave()
+
+// Die 3 Audits
+window.__AEGIS_DEBUG__.runSelfAudit()
+window.__AEGIS_DEBUG__.runExtensionAudit()
+window.__AEGIS_DEBUG__.runRedesignAudit()
+```
+
+> **Wichtig (Playwright):** `const`/`let` im Global Scope (`TOWER_TYPES`, `Game`, `placeTower`, `buySkill`, `simulate`, …) liegen **nicht** auf `window`. In `page.evaluate()` müssen sie als **bare Identifier** referenziert werden.
+
+---
+
+## Projektstruktur
+
+```
+Laby/
+├── Aegis-Labyrinth.html              # ⚠️ Game-Source – MANUELL HINZUFÜGEN (nicht versioniert)
+├── package.json                      # npm-Scripts (audit, selfplay, perf, report, test, setup)
+├── package-lock.json
+├── .gitignore
+├── LICENSE                           # GNU GPL v3
+├── README.md                         # diese Datei
+├── CHANGELOG.md                      # Version-Historie (Game + Suite) & Änderungs-Log
+├── tests/
+│   ├── audit.mjs                     # Playwright-Audit-Suite (3 Audits + Assertions)
+│   ├── selfplay.mjs                  # Self-Play-Bot (deterministisch, Level 0)
+│   ├── perf-test.mjs                 # FPS/Heap-Messung unter Last
+│   └── report.mjs                    # HTML-Report-Generator (report.html)
+└── docs/
+    ├── 01_Debug_API.md               # __AEGIS_DEBUG__-API & In-Game-Console (Test-Orakel)
+    ├── 02_Audits.md                  # Die 3 Audits im Detail + Assertions + Exit-Codes
+    ├── 03_Automatisierung_CI.md      # Playwright-Automatisierung, Self-Play, Perf, CI
+    ├── 04_Resultate_Report.md        # Ausgabe-Dateien & report.html (Schema-Referenz)
+    ├── 05_Tasks_Backlog.md           # Implementierte Tasks (Changelog) & Backlog
+    └── 06_Refactoring_Game.md        # (Advisory) Refactoring-/Performance-Empfehlungen für die Game-Datei
+```
+
+---
+
+## Erzeugte Artefakte (werden NICHT committet)
+
+| Datei | Von | Beschreibung |
+|---|---|---|
+| `audit-result.json` | `audit.mjs` | Raw-Audit-Reports + Assertions + Page-Errors + Summary |
+| `selfplay-results.json` | `selfplay.mjs` | Episoden-Log + Win-Rate + Aggregates |
+| `perf-result.json` | `perf-test.mjs` | FPS, Heap, Setup-Metadaten |
+| `report.html` | `report.mjs` | Zusammengefasster, menschlich lesbarer CI-Report |
+| `audit-final.png` | `audit.mjs` | Finaler Screenshot des Headless-Browsers |
+
+Schema-Details: [`docs/04_Resultate_Report.md`](./docs/04_Resultate_Report.md).
+
+---
+
+## CI / Automatisierung
+
+Empfohlene Stufen (Details in [`docs/03_Automatisierung_CI.md`](./docs/03_Automatisierung_CI.md)):
+
+| Stufe | Inhalt | Wann |
+|---|---|---|
+| **Pre-Commit / Push** | `npm run audit` (schnell) | bei jedem Commit / PR |
+| **Nightly** | Audit + `selfplay.mjs 50` + `perf-test.mjs` | zeitplangetrieben |
+| **Release** | Audit + `selfplay.mjs 500` + Perf + Report-Artifact | Tagging |
+
+> ⚠️ In CI muss die `Aegis-Labyrinth.html` als **Secret/Artifact** bereitgestellt werden, da sie nicht im Repo liegt.
+
+---
+
+## Dokumentation
+
+| Datei | Inhalt |
+|---|---|
+| [`01_Debug_API.md`](./docs/01_Debug_API.md) | Komplette `__AEGIS_DEBUG__`-API + In-Game-Debug-Console |
+| [`02_Audits.md`](./docs/02_Audits.md) | Was `self`/`extension`/`redesign` prüfen, Assertions, Exit-Codes |
+| [`03_Automatisierung_CI.md`](./docs/03_Automatisierung_CI.md) | Playwright-Aufruf, Self-Play-Konzept, Perf, CI-Workflows |
+| [`04_Resultate_Report.md`](./docs/04_Resultate_Report.md) | JSON-Schemata + `report.html`-Aufbau |
+| [`05_Tasks_Backlog.md`](./docs/05_Tasks_Backlog.md) | Abgeschlossene Tasks (Changelog) + offenes Backlog |
+| [`06_Refactoring_Game.md`](./docs/06_Refactoring_Game.md) | Performance-/Refactoring-Empfehlungen für `Aegis-Labyrinth.html` |
+| [`CHANGELOG.md`](./CHANGELOG.md) | Laufende Version + Version-Historie & Änderungs-Log (Game + Suite) |
+
+---
+
+## Lizenz
+
+Dieses Projekt (die Test- & Audit-Suite) ist unter **GNU General Public License v3.0** (GPL-3.0) lizenziert.
+Die vollständige Lizenz finden Sie in der Datei [`LICENSE`](./LICENSE).
+
+> ⚠️ Die getestete Game-Datei `Aegis-Labyrinth.html` ist **nicht** Teil dieses Repos und unterliegt deren eigener Lizenzierung.
+> Der GPL-3.0-Schutz erstreckt sich auf alle Dateien in diesem Repository (Tests, Docs, Konfiguration).