188 lines
7.9 KiB
Markdown
188 lines
7.9 KiB
Markdown
# 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`](./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).
|