09 — Tests & Qualitätssicherung

Grundlagen

Warum Tests wichtig sind

Tests sind das Sicherheitsnetz deines KI-Agent-Systems. Sie stellen sicher, dass nach jeder Änderung alles weiterhin funktioniert.

Anfänger 5 Min

Die drei Säulen der Qualitätssicherung

Das Claw Code Projekt verfügt über ein umfassendes Test-System, das drei Ebenen abdeckt:

Säule	Beschreibung	Anzahl
Unit Tests	Testen einzelne Funktionen und Klassen isoliert	~35
Integration Tests	Testen das Zusammenspiel mehrerer Module	~10
Parity Audit	Vergleicht Python-Port mit TypeScript-Original	4 Metriken

Was passiert ohne Tests?

Ohne Tests können folgende Probleme unentdeckt bleiben:

Regressionsfehler — Eine Änderung bricht existierende Funktionalität
Snapshot-Divergenz — Die JSON-Referenzdaten sind nicht mehr synchron
Routing-Fehler — Prompts werden nicht mehr korrekt zugeordnet
Session-Datenverlust — Persistenz funktioniert nicht wie erwartet

💡

Pro-Tipp

Führe Tests immer aus, bevor du Änderungen committest. So vermeidest du, dass fehlerhafter Code in das Repository gelangt.

Praxis

Alle Tests ausführen

Führe die komplette Testsuite aus und verstehe die verschiedenen Ausführungsmodi.

Kern 5 Min

Der Standard-Befehl

Der empfohlene Weg, alle Tests auszuführen:

bash

# Alle Tests mit detailliertem Output
$ python3 -m unittest discover -s tests -v

Alternative Ausführungsmodi

Kompakte Ausgabe (ohne -v)

Zeigt nur Punkte für erfolgreiche Tests und Buchstaben für Fehler:
python3 -m unittest discover -s tests

Einzelne Testdatei ausführen

Teste nur einen bestimmten Bereich:
python3 -m unittest tests.test_porting_workspace -v

Einzelnen Testfall ausführen

Sehr spezifisch für Debugging:
python3 -m unittest tests.test_porting_workspace.TestWorkspaceBasics.test_commands_load -v

Test-Abbruch bei erstem Fehler

Für schnelles Debugging verwende --failfast oder -f:

bash

$ python3 -m unittest discover -s tests -v --failfast

✅

Erfolgskriterium

Am Ende solltest du sehen: "Ran 49 tests" gefolgt von "OK". Das bedeutet, alle Tests wurden erfolgreich ausgeführt.

Analyse

Test-Output interpretieren

Verstehe, was die Testausgabe dir mitteilt und wie du Probleme identifizierst.

Kern 5 Min

Ein typischer erfolgreicher Durchlauf

bash

test_commands_load (test_porting_workspace.TestWorkspaceBasics) ... ok
test_tools_load (test_porting_workspace.TestWorkspaceBasics) ... ok
test_runtime_bootstrap (test_porting_workspace.TestRuntimeBasics) ... ok
test_session_management (test_porting_workspace.TestRuntimeBasics) ... ok
... (45 weitere Tests)

----------------------------------------------------------------------
Ran 49 tests in 1.847s

OK

Die Test-Struktur verstehen

Jede Testzeile folgt diesem Muster:

test_<name> (<datei>.<klasse>) ... <status>

Status	Bedeutung	Farbe
`ok`	Test erfolgreich bestanden	Grün
`FAIL`	Test fehlgeschlagen (Assertion Error)	Rot
`ERROR`	Test konnte nicht ausgeführt werden (Exception)	Rot
`SKIP`	Test wurde übersprungen (optional)	Gelb

Die Testklassen im Überblick

Testklasse	Zweck	Anzahl
`TestWorkspaceBasics`	Grundlegende Ladefunktionen	~8
`TestRuntimeBasics`	Runtime-Initialisierung	~6
`TestCommandLoading`	Befehlskatalog-Validierung	~10
`TestToolLoading`	Toolkatalog-Validierung	~8
`TestPromptRouting`	Prompt-Routing-Algorithmus	~7
`TestSessionManagement`	Session-Lebenszyklus	~5
`TestTurnLoops`	Multi-Turn-Schleifen	~5

💡

Tipp für große Ausgaben

Bei vielen Tests kann die Ausgabe sehr lang werden. Leite sie in eine Datei um: python3 -m unittest discover -s tests -v > test_results.txt 2>&1

Fortgeschritten

Parity Audit durchführen

Vergleiche den Python-Port mit dem ursprünglichen TypeScript-System und stelle sicher, dass alle Features übernommen wurden.

Fortgeschritten 5 Min

Was ist der Parity Audit?

Der Parity Audit überprüft, wie vollständig der Python-Port das ursprüngliche TypeScript-System abbildet. Er vergleicht:

Datei-Abdeckung — Welche Dateien wurden portiert?
Verzeichnis-Struktur — Sind alle Module vorhanden?
Befehls-Einträge — Alle ~150 Befehle verfügbar?
Tool-Einträge — Alle ~100 Tools verfügbar?

Audit ausführen

bash

$ python3 -m src.main parity-audit

╔══════════════════════════════════════════════════════════════╗
║ PARITY AUDIT REPORT ║
╠══════════════════════════════════════════════════════════════╣
║ Root-Datei-Abdeckung: 85% (17/20 Dateien) ║
║ Verzeichnis-Abdeckung: 90% (9/10 Verzeichnisse) ║
║ Befehls-Einträge: 100% (152/152 Befehle) ║
║ Tool-Einträge: 100% (98/98 Tools) ║
╚══════════════════════════════════════════════════════════════╝

# Mit detaillierten Informationen
$ python3 -m src.main parity-audit --verbose

Die vier Metriken erklärt

1. Root-Datei-Abdeckung

Zeigt, wie viele der Top-Level-Dateien aus dem TypeScript-Original im Python-Port vorhanden sind. Eine Abdeckung von 85% bedeutet, dass einige Dateien (z.B. Konfigurationsdateien oder UI-Komponenten) noch nicht portiert wurden.

2. Verzeichnis-Abdeckung

Zeigt, wie viele Verzeichnisse/Module portiert wurden. Eine hohe Abdeckung ist wichtig für die strukturelle Parität.

3. Befehls-Einträge

Sollte immer 100% sein, da alle Befehle aus dem Snapshot geladen werden. Wenn hier weniger als 100% steht, ist möglicherweise die commands_snapshot.json beschädigt.

4. Tool-Einträge

Ebenfalls sollte immer 100% sein. Zeigt die Anzahl der verfügbaren Tools aus dem Snapshot.

⚠️

Wichtig

Eine 100%ige Parity ist nicht immer das Ziel. Einige TypeScript-spezifische Features (z.B. bestimmte UI-Komponenten) werden in einem Python-Port möglicherweise absichtlich nicht übernommen.

Details

Was wird getestet?

Ein detaillierter Blick auf die Testabdeckung und welche Komponenten geprüft werden.

Kern 10 Min

Testabdeckung nach Modulen

Komponente	Was wird geprüft	Kritikalität
`commands.py`	Alle ~150 Befehle laden korrekt, Validierung der Struktur	🔴 Hoch
`tools.py`	Alle ~100 Tools laden korrekt, Permission-Levels	🔴 Hoch
`runtime.py`	Prompt-Routing, Token-Scoring, Matching-Algorithmus	🔴 Hoch
`query_engine.py`	Session-Erstellung, Nachrichtenverarbeitung	🟡 Mittel
`session_store.py`	Persistenz, Laden/Speichern von Sessions	🟡 Mittel
`context.py`	Workspace-Erkennung, Dateistruktur	🟢 Normal
`setup.py`	Bootstrap-Phasen, Trust-Gating	🟡 Mittel
`main.py`	Alle 24 CLI-Befehle sind aufrufbar	🔴 Hoch

Die 24 CLI-Befehle im Test

Jeder der folgenden Befehle wird auf Ausführbarkeit geprüft:

bash

# Informationsbefehle
summary, manifest, subsystems, version, doctor

# Katalog-Befehle
commands, tools, show-command, show-tool

# Runtime-Befehle
route, bootstrap, turn-loop, flush-transcript, load-session

# Audit & Qualität
parity-audit, bootstrap-graph, health

# Hilfe
help, intro

JSON-Snapshot-Validierung

Die Tests überprüfen, dass die Referenzdaten gültig sind:

commands_snapshot.json — Schema-Validierung, Pflichtfelder, Eindeutigkeit der Namen
tools_snapshot.json — Schema-Validierung, Permission-Level-Validität
Kreuzreferenzen — Keine verwaisten Referenzen zwischen Dateien

Session-Management Tests

Diese Tests prüfen den kompletten Lebenszyklus:

Session erstellen mit QueryEnginePort.from_workspace()
Nachricht senden mit submit_message()
Transkript aktualisieren
Session persistieren mit persist_session()
Session laden mit load_session()
Datenintegrität verifizieren

✅

Ziel der Tests

Jede wichtige Funktion hat mindestens einen Test. Bei Änderungen am Code kannst du sofort sehen, ob etwas kaputt gegangen ist.

Troubleshooting

Häufige Test-Fehler

Typische Fehlerursachen und ihre Lösungen beim Ausführen der Tests.

Fortgeschritten 10 Min

Fehler 1: ModuleNotFoundError

bash

ModuleNotFoundError: No module named 'src'

Ursache: Du befindest dich nicht im Projekt-Root-Verzeichnis.

Lösung:

# Prüfe dein aktuelles Verzeichnis
$ pwd

# Navigiere zum Projekt-Root (wo sich src/ befindet)
$ cd /pfad/zu/claw-code

Fehler 2: JSON Decode Error

bash

json.decoder.JSONDecodeError: Expecting ',' delimiter

Ursache: Eine der JSON-Dateien im reference_data/ Verzeichnis ist beschädigt.

Lösung:

# Validiere die JSON-Dateien
$ python3 -c "import json; json.load(open('src/reference_data/commands_snapshot.json'))"
$ python3 -c "import json; json.load(open('src/reference_data/tools_snapshot.json'))"

# Falls fehlerhaft: Aus dem Git-Repository wiederherstellen
$ git checkout -- src/reference_data/

Fehler 3: Permission Denied bei Session-Speicherung

bash

PermissionError: [Errno 13] Permission denied: '.port_sessions/'

Ursache: Keine Schreibrechte im Projektverzeichnis.

Lösung:

# Unter Linux/macOS
$ chmod 755 .port_sessions/

# Oder: Verzeichnis neu erstellen
$ rm -rf .port_sessions/
$ mkdir .port_sessions/

Fehler 4: Test-Timeout

Ursache: Ein Test hängt möglicherweise in einer Endlosschleife.

Lösung:

# Mit Timeout-Limit ausführen
$ timeout 60 python3 -m unittest discover -s tests -v

# Einzelne Testklassen isoliert testen
$ python3 -m unittest tests.test_porting_workspace -v

Fehler 5: Assertion Errors im Routing-Test

Ursache: Der Token-Scoring-Algorithmus wurde geändert, ohne die Tests anzupassen.

Lösung:

Prüfe, ob die erwarteten Testwerte noch aktuell sind
Passe die Testassertions an die neue Logik an
Stelle sicher, dass die JSON-Snapshots nicht verändert wurden

💡

Debugging-Tipp

Führe fehlschlagende Tests mit maximaler Ausführlichkeit aus: python3 -m unittest <test> -v --tb=long für detaillierte Tracebacks.

Übersicht: Alle Fehler und Lösungen

Fehler	Wahrscheinliche Ursache	Schnelle Lösung
ModuleNotFoundError	Falsches Verzeichnis	Ins Projekt-Root wechseln
JSONDecodeError	Beschädigte Snapshot-Datei	Git-Restore ausführen
PermissionError	Keine Schreibrechte	Rechte korrigieren
Timeout	Endlosschleife	Einzelne Tests isolieren
AssertionError	Code-Änderung	Tests anpassen oder Rollback
ImportError	Fehlende Abhängigkeit	Python 3.8+ prüfen

✓

Abschluss

Zusammenfassung

Die wichtigsten Befehle und Konzepte auf einen Blick.

Die wichtigsten Befehle

bash

# Alle 49 Tests ausführen
$ python3 -m unittest discover -s tests -v

# Parity Audit durchführen
$ python3 -m src.main parity-audit

# Einzelne Testdatei ausführen
$ python3 -m unittest tests.test_porting_workspace -v

# System-Health prüfen
$ python3 -m src.main doctor

🎉

Sektion 09 abgeschlossen!

Du beherrschst nun die Qualitätssicherung des Claw Code Projekts. Du kannst alle 49 Tests ausführen, den Parity Audit interpretieren und häufige Fehler beheben. Dein KI-Agent-Harness ist bereit für den produktiven Einsatz!

Weiter zu Sektion 10 →