Projektwissen/docs/entscheidungen/0009-tests-definition-of-done.md

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.