slop-game-opus5.5/docs/TESTING.md

Tests

Das Projekt hat drei Testebenen:

Ebene	Werkzeug	Ort	Umfang
Backend, Assets, Deployment	pytest	tests/*.py	Routen, API inkl. Validierung, Rate-Limit, Tokens, Datenbank, Konfiguration, Moderation, Passenger-Import, Upload-Paket, Asset-Lizenzen, Inhaltsprüfung
Spiellogik (JavaScript)	Vitest	tests/js/*.test.js	Wellen, Punkte, Combo-Eingabe, Abklingzeiten, Gegner-KI, Waffen, Formatierung, Einstellungen, API-Client, Audio, Tastaturhelfer, Konfiguration
End-to-End	Playwright (pytest)	tests/e2e/test_smoke.py	Seite lädt, Disclaimer, Spielstart, Schießen, Pause, Orbital-Befehle per Tastatur, Game Over mit Highscore, Spiel ohne Asset-Dateien, keine JavaScript-Fehler

Vorbereitung

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1   –   Linux/macOS: source .venv/bin/activate
python -m pip install -r requirements-dev.txt
npm install            # nur für Vitest und ESLint (Node.js 22 ab 22.13 oder 24)

Python-Tests (inkl. End-to-End)

pytest                      # alles
pytest -m "not e2e"         # ohne Browser
pytest -m e2e               # nur End-to-End
pytest tests/test_api_highscores.py -k rate_limit   # gezielt

Die End-to-End-Tests starten den Flask-Server selbst (zufälliger Port, temporäre Datenbank). Als Browser nehmen sie das installierte Microsoft Edge oder Google Chrome, ein zusätzlicher Download ist nicht nötig. Ist keiner vorhanden:

python -m playwright install chromium
GLORY_E2E_BROWSER=chromium pytest -m e2e        # PowerShell: $env:GLORY_E2E_BROWSER="chromium"; pytest -m e2e

GLORY_E2E_BROWSER erzwingt einen Kanal (msedge, chrome oder chromium). Findet Playwright gar keinen Browser, werden die E2E-Tests übersprungen (mit Begründung in der Ausgabe) statt fehlzuschlagen.

Hinweis: Die E2E-Tests warten per page.evaluate statt page.wait_for_function. Letzteres nutzt intern eval, und das blockiert die strenge Content-Security-Policy der App zu Recht. So wird mit der echten CSP getestet.

JavaScript-Tests

npm test               # einmalig
npm run test:watch     # bei Änderungen neu

Die getestete Logik in app/static/js/logic/ importiert kein Phaser und läuft direkt in Node. Systeme mit Browser-Abhängigkeit (Audio, Einstellungen, API-Client) werden mit kleinen Attrappen getestet (Fake-AudioContext, Fake-fetch, Speicher statt localStorage).

Linting

ruff check .
ruff format --check .      # „ruff format .“ formatiert
npm run lint               # ESLint für app/static/js, tests/js, scripts

Hinweis für Windows PowerShell 5.1: Befehle nicht mit && verketten (das kennt erst PowerShell 7), sondern nacheinander ausführen. Ist die venv nicht aktiviert, jeden Befehl über .\.venv\Scripts\python.exe -m … aufrufen, z. B. .\.venv\Scripts\python.exe -m pytest oder .\.venv\Scripts\python.exe -m ruff check ..

ruff prüft mit target-version = "py310", dass kein Code neuere Python-Features braucht, als cPanel-Hosts typischerweise anbieten.

Was wo getestet wird

Anforderung	Tests
Alle Routen	tests/test_routes.py
Highscore-API, Validierung, ungültige Eingaben	tests/test_api_highscores.py, tests/test_validation.py
Rate-Limiting	tests/test_api_highscores.py (test_rate_limit_*), tests/test_models.py
Datenbank-Initialisierung	tests/test_models.py
passenger_wsgi.py importiert die App (auch aus fremdem Arbeitsverzeichnis)	tests/test_passenger_wsgi.py
Wellengenerierung	tests/js/waves.test.js, tests/js/waveDirector.test.js
Punkteberechnung	tests/js/scoring.test.js
Tastenkombinationen der Orbital-Befehle	tests/js/comboInput.test.js, E2E test_orbital_commands_via_keyboard
Gegner-KI	tests/js/steering.test.js, tests/js/enemyAi.test.js
Seite lädt, Disclaimer, Spielstart, keine JS-Fehler	E2E test_page_loads_disclaimer_then_game_starts
Spielbar mit Platzhaltern	E2E test_game_runs_with_placeholders_when_assets_are_missing
Assets dokumentiert, keine fremden Namen	tests/test_assets.py
Eigene Befehlscodes (nicht aus anderen Spielen)	tests/js/config.test.js
Moderation (CLI, Sperrliste)	tests/test_moderation.py
Upload-Paket für cPanel (vollständig, ohne Geheimnisse, startet entpackt)	tests/test_deploy_zip.py
Proxy-Header, Schlüssel erst bei Bedarf	tests/test_routes.py, tests/test_config.py

Neue Tests schreiben

• Neue Spiellogik möglichst in app/static/js/logic/ ohne Phaser-Import anlegen und in tests/js/ testen.
• Backend-Fixtures (app, client, issue_token, valid_payload) stehen in tests/conftest.py. issue_token(started_ago=…) simuliert eine bereits laufende Runde, ohne zu warten.
• Für E2E-Tests den Hilfsbefehl _accept_disclaimer_and_start(page) nutzen. Der Spielzustand ist über window.gloryDefense (Phaser-Game-Instanz) erreichbar.