Testprozess

Testprozess

Diese Seite beschreibt den vollständigen hocX-Testprozess: lokale Ausführung, Testisolation, Browser-Tests, CI-Gates, Release-Verifikation und Fehlersuche.

Überblick

Änderung entwickeln
    ↓
betroffenen Testbereich lokal ausführen
    ↓
gesamte lokale Suite vor dem Pull Request
    ↓
Pull Request: CI, Builds, Migrationen und Security-Checks
    ↓
Candidate auf der Testumgebung verifizieren
    ↓
getesteten Candidate nach Produktion promoten

Testbereiche

Bereich	Werkzeug	Isolation	Befehl
Haupt-Backend	Pytest	eigener Compose-Stack mit flüchtigem PostgreSQL	./scripts/test.sh backend
Abgabebox-Backend	Pytest	eigener Compose-Stack und eingeschränkte DB-Rolle	./scripts/test.sh abgabebox-backend
Haupt-Frontend	Vitest	laufender Entwicklungscontainer	./scripts/test.sh frontend
Abgabebox-Frontend	Vitest	laufender Entwicklungscontainer	./scripts/test.sh abgabebox-frontend
Gesamtsystem	Playwright	eigener E2E-Stack, eigene Ports und Volumes	./scripts/test.sh e2e

Die gesamte Suite wird mit folgendem Befehl ausgeführt:

./scripts/test.sh all

Die Bereiche laufen dabei nacheinander. Beim ersten Fehler bricht der Runner ab.

Voraussetzungen

• Docker Engine
• Docker Compose v2
• eine aus .env.example erzeugte .env
• genügend freier Speicher für Test-Images und das Playwright-Image
• für den optionalen Host-Lauf: Node.js, npm und ein installierter Playwright-Browser

cp .env.example .env

Für die beiden Frontend-Testbefehle muss der Entwicklungs-Stack laufen:

./scripts/dev.sh

Backend-Tests

Haupt-Backend

./scripts/test.sh backend

Der Runner verwendet docker-compose.tests.yml unter dem Projektnamen hocx-tests:

1. test-db startet PostgreSQL 16 auf einem tmpfs.
2. test-migrations führt alembic upgrade head aus.
3. backend-test baut das Test-Image und startet Pytest.
4. Nach dem Lauf werden Container, Netz und Volumes entfernt.

Die Backend-Fixture kapselt jeden Test zusätzlich in eine äussere Transaktion. Vom Code ausgeführte Commits verlassen nur einen Savepoint; beim Teardown wird die äussere Transaktion zurückgerollt. Tests hinterlassen dadurch keine Datensätze.

Einzelne Tests lassen sich direkt im Test-Container auswählen:

docker compose -p hocx-tests -f docker-compose.tests.yml --profile tests \
  run --rm --build backend-test python3 -m pytest \
  tests/test_auth_access.py -v

Ein einzelner Testfall kann mit seinem Node-Identifier ausgeführt werden:

docker compose -p hocx-tests -f docker-compose.tests.yml --profile tests \
  run --rm --build backend-test python3 -m pytest \
  tests/test_auth_access.py::test_name -v

Danach den isolierten Stack entfernen:

docker compose -p hocx-tests -f docker-compose.tests.yml \
  --profile tests down --volumes --remove-orphans

Abgabebox-Backend

./scripts/test.sh abgabebox-backend

Dieser Bereich nutzt dieselbe flüchtige Datenbank, greift aber mit der eingeschränkten Rolle hocx_abgabebox darauf zu. Dadurch werden neben Upload-, Quota-, Scan- und CAPTCHA-Logik auch die tatsächlichen Datenbankberechtigungen getestet. Die Umgebung ist explizit test; reale CAPTCHA-Schlüssel sind nicht erforderlich.

Frontend-Tests

Die Frontend-Tests verwenden Vitest:

./scripts/test.sh frontend
./scripts/test.sh abgabebox-frontend

Der Wrapper führt npm test in den bereits laufenden Containern frontend bzw. abgabebox-frontend des Projekts hocx-dev aus. Alternativ kann bei lokal installierten Abhängigkeiten direkt im jeweiligen Verzeichnis getestet werden:

cd frontend
npm test

cd ../abgabebox-frontend
npm test

Einen einzelnen Vitest-Test ausführen:

docker compose -p hocx-dev exec frontend \
  npm test -- lib/offline-store.test.ts

End-to-End-Tests

./scripts/test.sh e2e

Der Befehl delegiert an ./scripts/e2e.sh all. Der E2E-Runner:

1. startet den isolierten Compose-Stack hocx-e2e;
2. verwendet .env.e2e.example, nicht die Entwicklungs-.env;
3. wartet auf die Health-Endpunkte aller vier Anwendungen;
4. führt die Playwright-Tests in Chromium aus;
5. sammelt bei Fehlern die Dienstlogs;
6. entfernt anschliessend Container, Volumes und storage-e2e.

E2E-Adressen

Dienst	Adresse
hocX-Frontend	http://127.0.0.1:13000
hocX-Backend	http://127.0.0.1:18000
Abgabebox-Frontend	http://127.0.0.1:13001
Abgabebox-Backend	http://127.0.0.1:18001
PostgreSQL	127.0.0.1:55432

Diese Ports sind bewusst von der Entwicklungsumgebung getrennt.

Getrennter E2E-Ablauf zur Fehlersuche

./scripts/e2e.sh up
./scripts/e2e.sh test
./scripts/e2e.sh down

Mit up bleibt der Stack zwischen Testläufen aktiv. down entfernt auch Datenbank- Volumes und E2E-Dateispeicher.

Standardmässig läuft Playwright in einem passenden Browser-Container. Wenn Chromium bereits auf dem Host installiert ist, kann der speichersparende Host-Lauf verwendet werden:

E2E_USE_HOST_PLAYWRIGHT=1 ./scripts/e2e.sh all

Abgedeckte Browser-Szenarien

• reproduzierbare Sitzungen für Admin, Writer, Reader und einen zweiten Mandanten
• Weiterleitung nicht angemeldeter Benutzer
• zentrale Workspace- und Admin-Navigation
• Erstellen, Lesen, Ändern und Löschen zentraler Entitäten
• persistente Terminänderungen nach einem Reload
• Todo-Erstellung sowie Markdown- und PDF-Export
• Writer- und Reader-Berechtigungen
• Mandantentrennung bei Lesen und Schreiben

Die Tests laufen absichtlich nicht vollständig parallel, damit gemeinsam verwendete Testdaten und Lifecycle-Abläufe reproduzierbar bleiben. In CI wird ein fehlgeschlagener Test einmal wiederholt; lokal gibt es standardmässig keinen Retry.

Diagnose bei Fehlern

Playwright bewahrt bei Fehlern folgende Dateien auf:

• Screenshots
• Videos
• Traces
• HTML-Report
• Dienstlogs unter frontend/test-results/e2e-services.log

Lokale Verzeichnisse:

frontend/test-results/playwright/
frontend/playwright-report/
frontend/test-results/e2e-services.log

Nützliche Befehle:

docker compose -p hocx-e2e \
  -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.e2e.yml \
  --env-file .env.e2e.example ps

docker compose -p hocx-e2e \
  -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.e2e.yml \
  --env-file .env.e2e.example logs --tail=150 backend frontend

In GitHub Actions wird die Playwright-Diagnose bei einem Fehlschlag als Artefakt playwright-report für 14 Tage gespeichert.

CI-Prozess

Die CI läuft bei Pull Requests gegen main und bei Pushes auf main.

CI-Job	Prüfung	Gate
deploy-script-tests	Shell-Syntax, sicherer Env-Loader und Release-Konfiguration	blockierend
migration-check	komplette Alembic-Historie gegen eine frische PostgreSQL-DB	blockierend
backend-tests	Haupt-Backend mit Pytest	blockierend
abgabebox-backend-tests	Abgabebox mit eingeschränkter DB-Rolle	blockierend
frontend-build	Vitest und Produktionsbuild beider Frontends	blockierend
e2e-tests	isolierter Stack und Playwright-Browsertests	blockierend
secret-scan	neue Secrets im Commit-Bereich mit Gitleaks	blockierend
dependency-audit	pip-audit und npm audit	warnend

Der Dependency-Audit ist aktuell bewusst nicht blockierend, weil bekannte Findings separat nachgeführt werden. Ergebnisse stehen in der Job-Zusammenfassung. Ein neu eingechecktes Secret blockiert dagegen den Merge.

backend-tests und abgabebox-backend-tests laufen mit pytest-cov (--cov-report=term-missing), frontend-build mit vitest run --coverage für beide Frontends. Bewusst ohne Schwellenwert-Gate, siehe Bekannte offene Punkte; die Coverage-Tabelle steht im jeweiligen Job-Log. backend-tests führt zusätzlich backend/scripts/check_audit_coverage.py aus, das schreibende Endpunkte ohne direkt sichtbaren AuditService.log(...)-Aufruf auflistet — ebenfalls informativ, nicht blockierend.

Test der Release-Konfiguration

scripts/tests/test_release_config.sh prüft unter anderem:

• ob Test-, E2E- und Release-Compose-Dateien gültig zusammengeführt werden;
• ob Release-Services nicht die komplette .env erhalten;
• Read-only-Dateisysteme, Capability-Drops und no-new-privileges;
• Ressourcenlimits für Traefik und ClamAV;
• nicht privilegierte Containerbenutzer;
• getrennte Migration und Anwendungsstart;
• Host-Bindung an test bzw. prod;
• Fast-Forward-only für Updates des Deployment-Codes.

scripts/tests/test_env.sh prüft den sicheren Env-Loader, Dateirechte, Symlink-Abwehr, das Ablehnen unbekannter Variablen und die feste Host-Umgebung.

Direkte Ausführung:

bash scripts/tests/test_env.sh
bash scripts/tests/test_release_config.sh

Testumgebung und Release-Gate

Eine grüne PR-CI allein gibt noch keinen Produktionsrelease frei. Nach dem Erstellen der Candidate-Images wird exakt derselbe Candidate auf dem Test-Host deployt:

./scripts/deploy.sh test
./scripts/verify_release.sh test

Zusätzlich zur automatischen Verifikation wird mit einem Wegwerf-Testkonto geprüft:

• Login-Seite und Branding laden korrekt;
• Anmeldung funktioniert;
• mindestens eine Tabellenansicht lädt Daten;
• die öffentliche Abgabebox ist erreichbar, sofern sie konfiguriert ist;
• Backend-Logs enthalten keine Start- oder Alembic-Fehler.

Ein erfolgreicher Lauf von verify_release.sh test schreibt den GitHub-Deployment- Nachweis für genau den Candidate-Tag. Nur dieser nachgewiesene Candidate darf im Promotion-Workflow zum finalen Release-Tag werden. Der vollständige Ablauf steht im Deployment-Runbook.

Checkliste vor einem Pull Request

• Für die Änderung existiert ein passender automatisierter Test.
• Der direkt betroffene Testbereich läuft lokal grün.
• Datenbankänderungen bestehen alembic upgrade head gegen eine frische DB.
• Beide Frontends bauen, wenn gemeinsam verwendete Typen oder APIs geändert wurden.
• Berechtigungsänderungen prüfen mindestens Admin, Writer, Reader und Tenant-Grenzen.
• Upload-Änderungen prüfen Dateityp, Grösse, Quota, Scan und eingeschränkte DB-Rolle.
• Für einen Release-Kandidaten wurde die gesamte Suite ausgeführt.
• Fehlerartefakte und Logs wurden geprüft, nicht nur der Exit-Code.

Neue Tests hinzufügen

• Backend-Tests gehören nach backend/tests/test_*.py.
• Abgabebox-Backend-Tests gehören nach abgabebox-backend/tests/test_*.py.
• Vitest-Dateien verwenden das Muster *.test.ts bzw. *.test.tsx.
• Playwright-Szenarien gehören nach frontend/e2e/*.spec.ts.
• Wiederverwendbare E2E-Anmeldungen werden in frontend/e2e/auth.setup.ts erzeugt.
• Tests müssen ohne bestehende Entwicklerdaten reproduzierbar sein.
• E2E-Tests müssen angelegte Daten entfernen oder sich auf den vollständig entsorgten E2E-Stack verlassen.