# 0009 – Tests sind Teil der Definition of Done, und sie werden für Menschen dokumentiert

Status: vorgeschlagen · Datum: 2026-09-04 · Beteiligte: AG QGIS · Ergänzt 0003

## Kontext
Entscheidung 0003 machte den Baseline-Lauf vor jedem Pull Request zur Pflicht. Sie verhindert *Rückschritte*,
verlangt aber keine *neuen* Tests. Bei überwiegend KI-erzeugtem Code ist das zu wenig: Ein Agent kann
überzeugend erklären, dass etwas funktioniert, ohne dass es funktioniert.

Der am 04.09.2026 erstmals erzeugte Testkatalog zeigt dazu einen zweiten Befund: Von 332 Testfällen haben nur
100 (30 %) eine Beschreibung — `sn_basis` null von 87, `sn_plan41` einen von 44. Ohne Beschreibung ist von außen
nicht erkennbar, was ein Test prüft. Damit kann niemand beurteilen, ob die Abdeckung **fachlich** sinnvoll ist,
und genau das ist bei einer Fachanwendung die entscheidende Frage. Ein grüner Testlauf, dessen Inhalt niemand
kennt, ist ein Gefühl, kein Nachweis.

## Entscheidung
1. **Neue Funktionalität ohne Test wird nicht gemergt.** Mindestens ein Test je neuem beobachtbarem Verhalten.
   Bei einer Fehlerbehebung zuerst der Test, der den Fehler zeigt.
2. **Jeder Test hat einen deutschen Docstring**, dessen erste Zeile mit `Prüft, dass …` beginnt. Diese Zeile ist
   für die meisten Leser der einzige Kontakt mit dem Test.
3. **Der Testkatalog wird erzeugt, nicht gepflegt.** `scripts/testkatalog.py` liest die Testdateien per `ast`
   (ohne Import, ohne QGIS, ohne Abhängigkeiten) und schreibt `docs/tests/testkatalog.md`. Er wird mitcommittet;
   `--pruefen` meldet, wenn er veraltet ist.
4. **Fachlich wichtige Abläufe bekommen eine Testkonzept-Seite** in `docs/tests/` nach
   `docs/vorlagen/testkonzept.md`: ein Mermaid-Diagramm des fachlichen Ablaufs, eine Tabelle
   Schritt → deckender Test → bewusst nicht getestet mit Begründung, und die bekannten Lücken.
   Damit kann eine Fachperson ohne Programmierkenntnisse prüfen, ob die Tests das Richtige prüfen.

Die Docstring-Pflicht gilt für **neue und geänderte** Tests. Die 232 bestehenden Tests ohne Beschreibung werden
nicht auf einen Schlag nachgezogen; der Abschnitt „Lücken" des Katalogs ist die Arbeitsliste, die nebenbei
abgearbeitet wird.

## Folgen
Pull Requests werden etwas größer und etwas langsamer. Dafür wird zum ersten Mal überprüfbar, ob die Testsuite
fachlich das Richtige abdeckt — bisher war nur bekannt, wie viele Tests grün sind. Der Katalog macht Lücken
sichtbar, statt sie in Testdateien zu verstecken. Die Testkonzept-Seiten sind zusätzlicher Pflegeaufwand und
lohnen nur für Abläufe, die fachlich wirklich wichtig sind — nicht für jede Funktion.

## Verworfene Alternativen
Nur den generierten Katalog (zeigt was getestet wird, aber nicht ob es genügt — genau die Prüfung, um die es
geht, fiele weg); nur handgeschriebene Testkonzepte (laufen dem Code hinterher, dieselbe Drift, die die
Wissensbasis sonst vermeidet); Testabdeckung in Prozent als Ziel (misst durchlaufene Zeilen, nicht fachliche
Vollständigkeit, und verleitet zu Tests ohne Aussage).

## Ergänzung (18.09.2026)
Der Testkatalog weist seither zusätzlich einen Abschnitt „Ungetestete Funktionen (strukturelle Lücke)" aus:
Funktionen/Methoden im Quellcode, deren Name in keiner Testdatei des Pakets vorkommt (Namensabgleich per `ast`,
ohne Import und ohne Laufzeitmessung). Das ist **keine** Wiederaufnahme der oben verworfenen
Zeilen-Coverage-in-Prozent: Es gibt keine Prozentzahl als Ziel, sondern eine Lückenliste nach demselben Muster
wie der bestehende Abschnitt „Lücken" für fehlende Docstrings — ein Hinweis, wo ein Mensch hinschauen sollte,
kein Ausführungsnachweis und keine Aussage über fachliche Richtigkeit.