Integration-Test Skill

Dieser Skill führt End-to-End Integration-Tests für das CommonKnowledgeScout Projekt aus.

Wann verwenden

• Wenn der Benutzer "Integrationstest", "teste dieses Verzeichnis" oder ähnliches sagt
• Wenn der Benutzer ein Verzeichnis mit Dateien (PDF, Audio, Markdown, etc.) testen möchte
• Wenn der Benutzer den Test-Loop starten möchte (Test → Analyse → Fix → Repeat)

Voraussetzungen

1. Dev-Server muss laufen (pnpm dev)
2. Secretary Service muss erreichbar sein (localhost:5001)
3. MongoDB muss verfügbar sein

Parameter sammeln

Bevor du Tests startest, sammle folgende Informationen vom Benutzer:

Verfügbare Testcases

Audio

• audio_transcription.happy_path - Einfache Audio-Transkription
• audio_transcription.gate_skip_extract - Überspringt Extract wenn Shadow-Twin existiert
• audio_transcription.force_recompute - Erzwingt Neuberechnung
• audio_transcription.template_and_ingest - Template + Ingestion nach Transkription

PDF

• pdf_mistral_report.happy_path - PDF-Extraktion + Template
• pdf_mistral_report.gate_skip_extract - Überspringt Extract
• pdf_mistral_report.force_recompute - Erzwingt Neuberechnung
• pdfanalyse.hitl_publish - Human-in-the-Loop Publishing

Markdown/TXT/Website

• markdown_ingest.happy_path - Markdown → Template → Ingest
• txt_normalize.happy_path - TXT → Normalize → Template → Ingest
• website_normalize.happy_path - Website → Normalize → Template → Ingest

Test-Befehl

Führe Tests mit folgendem Befehl aus:

bash
1pnpm -s test:integration:api -- \
2  --libraryId <LIBRARY_ID> \
3  --folderId <FOLDER_ID> \
4  --userEmail <USER_EMAIL> \
5  --fileKind <FILE_KIND> \
6  --testCaseIds <COMMA_SEPARATED_IDS>

Beispiel

bash
1pnpm -s test:integration:api -- \
2  --libraryId 7911fdb9-8608-4b24-908b-022a4015cbca \
3  --folderId YXVkaW8= \
4  --userEmail peter.aichner@crystal-design.com \
5  --fileKind audio \
6  --testCaseIds audio_transcription.happy_path,audio_transcription.template_and_ingest

Agent-Loop (Definition of Done)

Führe folgende Schleife aus bis failed = 0:

1. Tests starten

Führe den Test-Befehl aus und warte auf das Ergebnis (JSON).

2. Ergebnis analysieren

Prüfe im JSON:

• summary.failed - Anzahl fehlgeschlagener Tests
• results[].messages - Validierungsnachrichten (type: error/warn/info)

3. Bei Fehlern

a) Fehler clustern: Gruppiere ähnliche Fehler nach Message-Text

b) Root-Cause analysieren:

• Lies den Job via MongoDB oder API
• Prüfe Trace-Events und Step-Status
• Identifiziere die fehlerhafte Code-Stelle

c) Minimalen Fix implementieren:

• 1 Fehler-Cluster → 1 Fix
• Ändere so wenig Code wie möglich
• Füge hilfreiche Kommentare hinzu

d) Unit-Tests prüfen:

bash
1pnpm test

4. Wiederholen

Starte die Tests erneut und wiederhole bis alle grün sind.

Globale Contracts (immer prüfen)

Diese Regeln müssen IMMER erfüllt sein:

1. Leeres Markdown ist ein Fehler - Keine leeren Transcripts/Transformationen
2. completed ⇒ keine pending Steps - Alle aktivierten Phasen müssen abgeschlossen sein
3. completed ⇒ keine running Steps - Keine hängenden Steps
4. phases.X = true ⇒ Step X muss completed sein - Aktivierte Phasen dürfen nicht pending bleiben

Referenz-Dokumentation

Detaillierte Dokumentation findest du in:

• docs/guides/integration-tests.md - Hauptdokumentation
• docs/analysis/integration-tests-agent-mode.md - Agent-Modus Details
• src/lib/integration-tests/test-cases.ts - Testcase-Definitionen
• src/lib/integration-tests/validators.ts - Validierungslogik

Beispiel-Interaktion

Benutzer: "Teste mir die Audio-Dateien im Testfolder"

Agent:

1. Fragt nach Library-ID und Folder-ID (falls nicht bekannt)
2. Führt aus: pnpm -s test:integration:api -- --libraryId ... --folderId ... --fileKind audio
3. Analysiert das JSON-Ergebnis
4. Bei Fehlern: Identifiziert Root-Cause, implementiert Fix, wiederholt
5. Meldet: "Alle X Tests bestanden" oder "Y Fehler gefunden, analysiere..."