Laby/README.md

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.

📜 Version & Historie: Laufende Version + Changelog in 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

# 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:

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):

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.

// 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.

---

CI / Automatisierung

Empfohlene Stufen (Details in 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	Komplette __AEGIS_DEBUG__-API + In-Game-Debug-Console
02_Audits.md	Was self/extension/redesign prüfen, Assertions, Exit-Codes
03_Automatisierung_CI.md	Playwright-Aufruf, Self-Play-Konzept, Perf, CI-Workflows
04_Resultate_Report.md	JSON-Schemata + report.html-Aufbau
05_Tasks_Backlog.md	Abgeschlossene Tasks (Changelog) + offenes Backlog
06_Refactoring_Game.md	Performance-/Refactoring-Empfehlungen für Aegis-Labyrinth.html
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.

⚠️ 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).