breakpilot-lehrer/docs-src/development/regression-testing.md

OCR Pipeline Regression Testing

Stand: 2026-03-23

---

Uebersicht

Das Regression Framework stellt sicher, dass Aenderungen an der OCR-Pipeline keine bestehenden Ergebnisse verschlechtern. Ground-Truth Sessions dienen als Referenz — nach jeder Code-Aenderung wird die Pipeline neu ausgefuehrt und das Ergebnis mit der Referenz verglichen.

---

Ground Truth markieren

Via Admin-UI (empfohlen)

1. Oeffne die OCR Pipeline: /ai/ocr-pipeline
2. Lade eine Session und fuehre alle Pipeline-Schritte aus
3. Pruefe das Ergebnis im Grid Editor (Schritt 10)
4. Korrigiere Fehler falls noetig (Inline-Edit)
5. Klicke "Als Ground Truth markieren"

Via API

# Bestehende Session als Ground Truth markieren
curl -X POST "http://macmini:8086/api/v1/ocr-pipeline/sessions/{session_id}/mark-ground-truth"

# Ground Truth entfernen
curl -X DELETE "http://macmini:8086/api/v1/ocr-pipeline/sessions/{session_id}/mark-ground-truth"

# Alle Ground-Truth Sessions auflisten
curl "http://macmini:8086/api/v1/ocr-pipeline/ground-truth-sessions"

Via Ground-Truth Review UI

Fuer die Massenpruefung von 50-100 Sessions:

1. Oeffne /ai/ocr-ground-truth
2. Filter auf "Offen" (ungeprueft)
3. Split-View: Bild links, Grid rechts pruefen
4. Korrekte Zeilen mit Haekchen bestaetigen
5. Fehler inline korrigieren
6. "Markieren & Weiter" fuer naechste Session

---

Regression ausfuehren

Via Shell-Script (CI/CD)

# Standard: macmini:8086
./scripts/run-regression.sh

# Custom URL
./scripts/run-regression.sh http://localhost:8086

# Exit-Codes:
# 0 = alle bestanden
# 1 = Fehler gefunden
# 2 = Verbindungsfehler

Via Admin-UI

1. Oeffne /ai/ocr-regression
2. Klicke "Alle Tests starten"
3. Ergebnis: Pass/Fail pro Session mit Diff-Details

Via API

# Alle Ground-Truth Sessions testen
curl -X POST "http://macmini:8086/api/v1/ocr-pipeline/regression/run?triggered_by=script"

# Einzelne Session testen
curl -X POST "http://macmini:8086/api/v1/ocr-pipeline/sessions/{session_id}/regression/run"

# Verlauf abrufen
curl "http://macmini:8086/api/v1/ocr-pipeline/regression/history?limit=20"

---

Ergebnisse lesen

Diff-Typen

Typ	Beschreibung
structural_changes	Anzahl Zonen, Spalten oder Zeilen hat sich geaendert
text_change	Text einer Zelle hat sich geaendert
cell_missing	Zelle war in der Referenz, fehlt jetzt
cell_added	Neue Zelle die in der Referenz nicht existierte
col_type_change	Spaltentyp einer Zelle hat sich geaendert

Status-Bewertung

• pass: Keine Diffs → Code-Aenderung hat keine Auswirkung
• fail: Diffs gefunden → pruefen ob gewollt (Feature) oder ungewollt (Regression)
• error: Pipeline-Fehler → Build oder Config-Problem

Verlauf

Alle Laeufe werden in der Tabelle regression_runs persistiert:

SELECT id, run_at, status, total, passed, failed, errors, duration_ms, triggered_by
FROM regression_runs
ORDER BY run_at DESC
LIMIT 10;

---

Best Practices

Ground-Truth Sessions waehlen

Decke verschiedene Seitentypen ab:

• Woerterbuchseiten (2-3 Spalten, IPA-Klammern)
• Uebungsseiten (Tabellen, Checkboxen)
• Seiten mit Illustrationen
• Seiten ohne IPA (reines Deutsch-Vokabular)
• Verschiedene Verlage und Layouts

Workflow vor jedem Commit

# 1. Regression laufen lassen
./scripts/run-regression.sh

# 2. Bei Failure: Diff pruefen
#    - Gewollte Aenderung? → Ground Truth aktualisieren
#    - Ungewollte Regression? → Code fixen

# 3. Bei Pass: Commit
git add . && git commit -m "fix: ..."

---

Datenbank-Schema

CREATE TABLE regression_runs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    run_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    status VARCHAR(20) NOT NULL,          -- pass, fail, error
    total INT NOT NULL DEFAULT 0,
    passed INT NOT NULL DEFAULT 0,
    failed INT NOT NULL DEFAULT 0,
    errors INT NOT NULL DEFAULT 0,
    duration_ms INT,
    results JSONB NOT NULL DEFAULT '[]',  -- Detail-Ergebnisse pro Session
    triggered_by VARCHAR(50) DEFAULT 'manual'
);

Ground-Truth Referenzen werden im ground_truth JSONB-Feld der ocr_pipeline_sessions Tabelle gespeichert.