# 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).