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: Game1.0.2, Suite1.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.htmlin die.gitignoreaufnehmen.
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 >= 18wird empfohlen (Top-Level-awaitin 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/letim Global Scope (TOWER_TYPES,Game,placeTower,buySkill,simulate, …) liegen nicht aufwindow. Inpage.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.htmlals 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.htmlist 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).