E2E-Testing (End-to-End-Tests)

Überblick

Das E2E-Testing-System von Hermeneus ermöglicht automatisierte Browser-Tests basierend auf User Flow Markdown-Dateien. Die Tests werden durch Claude Code Agents/Skills gesteuert und nutzen den Playwright MCP-Server für die Browser-Automatisierung.

Wichtig: E2E-Tests sind NICHT Teil der regulären Test-Suite (npm run test) und werden manuell oder durch spezielle Skills ausgeführt.

---

Architektur

User Flow Markdown ──> e2e-test-runner Agent ──> Playwright MCP ──> Browser
        │                      │                         │
        │                      v                         v
        │                 Testbericht               Screenshots
        │
        v
e2e-test-constructor Agent (erstellt User Flows)

Komponenten

Komponente	Beschreibung
User Flows	Markdown-Dateien, die Testschritte beschreiben
e2e-test-runner	Agent/Skill zur Ausführung von User Flows
e2e-test-constructor	Agent/Skill zur Erstellung von User Flows
Playwright MCP	Browser-Automatisierungs-Server
Reports	Markdown-Testberichte mit Ergebnissen
Callables	Backend-Unit-Tests zur Zustandsverifikation

---

Ordnerstruktur

tests/E2E/
├── Auth/
│   ├── userflows/
│   │   ├── 01-login-flow.md
│   │   └── 02-logout-flow.md
│   ├── callables/
│   │   └── VerifyUserLoggedInTest.php
│   ├── reports/
│   │   └── 2025-12-30_14-30-00.md
│   └── screenshots/
│       └── login-flow/
│           ├── 01-login-page.png
│           └── 02-after-login.png
├── Texte/
│   └── TextAufbereitung/
│       ├── userflows/
│       │   ├── 01-create-text-flow.md
│       │   └── 02-aufbereitung-text-flow.md
│       ├── callables/
│       ├── reports/
│       └── screenshots/
├── Uebungen/
│   └── [analog]
└── Glossarium/
    └── [analog]

Kategorien

Kategorie	Typische Flows
Auth	Login, Logout, Registrierung, Passwort-Reset
Texte	Text erstellen, bearbeiten, aufbereiten, annotieren
Uebungen	Übung erstellen, bearbeiten, absolvieren, auswerten
Glossarium	Vokabeln verwalten, Lemmabank, Import/Export

---

User Flow Format

Jeder User Flow ist eine Markdown-Datei mit standardisierter Struktur:

# [Flow-Name]

## Beschreibung

[1-2 Sätze, was der Flow testet]

## Voraussetzungen

- [Was muss gegeben sein, z.B. "Benutzer ist eingeloggt"]
- [Benötigte Daten, z.B. "Mindestens ein Text vorhanden"]

## Screenshots

Während der Ausführung werden Screenshots in folgendem Verzeichnis gespeichert:

tests/E2E/[Kategorie]/screenshots/[flow-name]/

## Schritte

1. **[Schritt-Titel]**
   - Navigiere zu `[URL]`
   - Erwartung: [Was sollte sichtbar sein]
   - **SCREENSHOT:** `01-[beschreibung].png`

2. **[Schritt-Titel]**
   - Klicke auf `[Selektor]` ([Beschreibung])
   - Fülle `[Selektor]` mit "[Wert]"
   - Erwartung: [Was sollte passieren]
   - **SCREENSHOT:** `02-[beschreibung].png`

## Erwartetes Ergebnis

- [Assertion 1: URL, Element, Text, etc.]
- [Assertion 2: ...]

## Callables

- `[TestName].php` - [Beschreibung was geprüft wird]

## Bei Fehlern

- Screenshot erstellen
- Konsolen-Logs dokumentieren
- [Spezifische Fehlerbehandlung]

Dateinamenskonvention

• Nummerierung: 01-, 02-, etc.
• Name: kebab-case, beschreibend
• Suffix: -flow.md

Beispiele:

• 01-login-flow.md
• 02-create-uebung-flow.md
• 03-edit-text-annotation-flow.md

---

E2E-Tests ausführen

Mit dem e2e-test-runner Skill

/e2e-test                    # Alle Flows in allen Kategorien
/e2e-test Auth               # Nur Auth-Kategorie
/e2e-test login              # Spezifischer Flow (Suche nach "login")
/e2e-test TextEditor Auth    # Mehrere Kategorien

Workflow des Runners

1. User Flows identifizieren - Findet alle passenden .md-Dateien
2. Parallele Ausführung - Startet bis zu 5 parallele e2e-test-runner Subagents
3. Schritte ausführen - Jeder Agent führt seinen Flow im Browser aus
4. Ergebnisse sammeln - Status, Screenshots, Fehlerdetails
5. Testbericht erstellen - Zusammenfassender Report in reports/

Parallele Ausführung

Flow 1 ──> Subagent 1 ──> Browser 1
Flow 2 ──> Subagent 2 ──> Browser 2
Flow 3 ──> Subagent 3 ──> Browser 3
Flow 4 ──> Subagent 4 ──> Browser 4
Flow 5 ──> Subagent 5 ──> Browser 5

Bei mehr als 5 Flows wird auf Abschluss der ersten 5 gewartet, dann werden die nächsten gestartet.

---

User Flows erstellen

Mit dem e2e-test-constructor Skill

/e2e-construct [beschreibung]

Beispiele:

/e2e-construct Login und Logout testen
/e2e-construct Benutzer erstellt eine neue Übung vom Typ Activitas
/e2e-construct Text im Editor öffnen und ein Wort annotieren
/e2e-construct Vokabel zur Lemmabank hinzufügen

Workflow des Constructors

1. Analyse - Extrahiert Kategorie, Startpunkt, Ziel aus der Beschreibung
2. Browser-Exploration - Führt den Flow explorativ im Browser aus
3. Dokumentation - Dokumentiert jeden Schritt mit Selektoren und Screenshots
4. Test-Bedarf identifizieren - Erkennt Bedarf für Unit-/Feature-Tests
5. User Flow erstellen - Generiert die Markdown-Datei
6. TODO-Listen aktualisieren - Trägt identifizierten Test-Bedarf ein

Automatisch erkannter Test-Bedarf

Der Constructor identifiziert während der Exploration:

Bedarf	Ziel-Datei	Beispiel
Unit-Tests	tests/Unit/TODO_Unit-tests.md	Isolierte Logik-Prüfungen
Feature-Tests	tests/Feature/TODO_Feature-tests.md	API-Endpoint-Tests
Callables	tests/E2E/[Kategorie]/callables/	Backend-Zustandsverifikation

---

Callables

Callables sind Unit-Tests im callables/-Ordner jeder Kategorie. Sie verifizieren Backend-Zustände nach E2E-Aktionen.

Wann Callables nutzen?

• Datenbank-Einträge prüfen ("Wurde der Eintrag korrekt gespeichert?")
• Session-Zustände verifizieren
• Cache-Einträge prüfen
• API-Responses validieren

Aufruf

php artisan test tests/E2E/Auth/callables/VerifyUserLoggedInTest.php

Vorteile gegenüber UI-Prüfungen

• Schneller - Direkter Backend-Zugriff
• Zuverlässiger - Keine UI-Timing-Probleme
• Präziser - Exakte Datenbank-Assertions

---

Testberichte (Reports)

Nach jedem Testlauf wird ein Bericht erstellt:

Speicherort: tests/E2E/[Kategorie]/reports/[YYYY-MM-DD_HH-MM-SS].md

Report-Format

# E2E Test Report

**Datum:** [YYYY-MM-DD HH:MM:SS]
**Dauer:** [X] Sekunden
**Kategorie:** [Auth|TextEditor|alle]

## Zusammenfassung

| Status | Anzahl |
|--------|--------|
| Bestanden | X |
| Fehlgeschlagen | Y |
| Gesamt | Z |

---

## Ergebnisse

### 01 - Login Flow
- **Status:** BESTANDEN
- **Dauer:** X.Xs
- **Schritte:** X/X erfolgreich

### 02 - Logout Flow
- **Status:** FEHLGESCHLAGEN
- **Dauer:** X.Xs
- **Schritte:** X/X erfolgreich
- **Fehler:** [Kurze Beschreibung]
- **Screenshot:** [Link]

---

## Fehlgeschlagene Tests - Details

[Details aus den Subagent-Berichten]

---

Screenshots

Konvention

• Nummerierung: 01-, 02-, etc.
• Beschreibender Name: 01-wizard-step1-leer.png, 02-wizard-step1-ausgefuellt.png
• Speicherort: tests/E2E/[Kategorie]/screenshots/[flow-name]/

Wann Screenshots erstellen?

• Bei wichtigen Zwischenschritten
• Bei Wizard-Schritten
• Bei Formularen vor/nach Ausfüllen
• Bei Modals/Dialogen
• Bei jedem Fehler (automatisch)

Nutzen

• Debugging fehlgeschlagener Tests
• Dokumentation des erwarteten UI-Zustands
• Visuelle Regression-Erkennung

---

Test-Benutzer

Die E2E-Tests nutzen die Base-Data User aus der Test-Datenbank:

Benutzer	Rolle	Passwort
bruce.wayne	admin	hermeneus#17
harvey.dent	editor	hermeneus#17
james.gordon	tester	hermeneus#17
selina.kyle	teacher	hermeneus#17
joker	user	hermeneus#17

---

Voraussetzungen

1. Playwright MCP Server muss konfiguriert sein (in .mcp.json)
2. Hermeneus muss unter https://hermeneus.test erreichbar sein
3. Base-Data muss in der Datenbank sein (Test-Benutzer)
4. Vite Dev-Server sollte laufen (für Frontend-Änderungen)

---

Fehlerbehandlung

Fehlertyp	Behandlung
Element nicht gefunden	Warte bis zu 5 Sekunden, dann Fehler dokumentieren
Navigation fehlgeschlagen	Screenshot + Fehler dokumentieren
Unerwarteter Alert	Versuche zu schließen, dokumentiere Inhalt
Timeout	Nach 30 Sekunden pro Schritt abbrechen
MCP-Server-Fehler	Fehlermeldung ausgeben, Test abbrechen

Bei Fehlern werden automatisch:

• Screenshot erstellt
• Konsolen-Logs gespeichert
• Fehlgeschlagener Schritt dokumentiert

---

Best Practices

User Flows schreiben

1. Kurz und fokussiert - Ein Flow testet EINEN Anwendungsfall
2. Sprechende Selektoren - button[type="submit"] statt .btn-1
3. Fallback-Selektoren - Mehrere Optionen mit Komma trennen
4. Screenshots einplanen - Besonders bei Wizard-Schritten

Selektoren auswählen (Priorität)

1. data-testid Attribute (falls vorhanden)
2. Semantische Selektoren: button[type="submit"], input[name="username"]
3. Aria-Labels: [aria-label="Einloggen"]
4. Text-basiert: button:has-text("Speichern")
5. CSS-Klassen (nur wenn eindeutig): .submit-button

Callables nutzen

• Für Backend-Verifikation immer Callables bevorzugen
• Schneller und zuverlässiger als UI-basierte Prüfungen
• Callable-Bedarf im User Flow dokumentieren

---

Weiterführende Dokumentation

• Testing Leitlinien - Allgemeine Test-Philosophie
• NPM-Test-Commands - Unit/Feature/Integration-Tests
• TestRunCommand - Artisan-Test-Commands