Projektwissen/.agents/skills/sn-tests/SKILL.md

name, description

name	description
sn-tests	Tests der LNO-Plugins ausführen, deuten, neu schreiben und dokumentieren - Mock-Modus ohne QGIS über scripts/run_tests.py mit Baseline-Vergleich, Testkatalog erzeugen, Testkonzept-Seiten pflegen, Hinweise für Tests in echter QGIS-Umgebung. Verwenden bei "Tests ausführen", "sind die Tests grün", "Test schlägt fehl", "Baseline", "schreib einen Test", "Testabdeckung".

Tests ausführen, schreiben und dokumentieren

Ausführliche Fassung für Menschen: docs/leitfaden/06_tests.md.

Ausführen (Mock-Modus, ohne QGIS)

python scripts/run_tests.py                                  # alle Pakete mit Tests
python scripts/run_tests.py sn_verfahrensgebiet --baseline   # ein Paket, Vergleich mit Baseline
python scripts/run_tests.py sn_plan41 --verbose              # volle unittest-Ausgabe (nur zum Verstehen eines Fehlers)

• Das Skript verlinkt die Repos unter ihren Paketnamen (sn_basis, …) in ein temporäres Verzeichnis und startet python -m unittest discover. Voraussetzung: Python ≥ 3.11, openpyxl installiert, Repos vorhanden (scripts/setup_workspace.py).
• Ausgabe je Paket: GRÜN/ROT, Zähler, mit --baseline zusätzlich NEU ROT (verboten) und neu grün.
• Exit-Code 0 = in Ordnung. gesamt = 0 bedeutet Import-Fehler → --verbose.

Einen neuen Test schreiben

Pflicht bei jeder neuen Funktionalität – ein Test je neuem beobachtbarem Verhalten, nicht je Funktion. Bei einem Bugfix zuerst der Test, der den Fehler zeigt.

def test_fbschl_mit_punkt_wird_erkannt(self):
    """Prüft, dass der Shape-Import auch das Feld 'FBSchl.' mit Punkt akzeptiert.

    Manche DAVID-Exporte liefern den Feldnamen mit Punkt, andere ohne.
    """
    layer = self._layer_mit_feldern({"FBSchl.": "901/10110F"})
    self.assertEqual(_ermittle_gebietstyp_aus_fbschl(layer), "Verfahrensgebiet")

Drei Anforderungen, alle verbindlich:

1. Deutscher, fachlich sprechender Name – nicht test_case_3.
2. Docstring, erste Zeile Prüft, dass …. Sie landet im Testkatalog und ist für die meisten Leser der einzige Kontakt mit dem Test.
3. Ein Verhalten je Test. Steht im Namen ein „und", sind es zwei Tests.

Weiter: unittest, Datei tests/test_<modul>.py, kein Netzwerk, keine echten Verfahrensdaten, keine Abhängigkeit von der Testreihenfolge. Muster: vorhandene Tests des Pakets. Dialoge: Pruefmanager(ui_modus="test") liefert Standardantworten; dialog_wrapper-Funktionen mit unittest.mock.patch ersetzen.

Testkatalog

python scripts/testkatalog.py            # erzeugt docs/tests/testkatalog.md UND testkatalog.html
python scripts/testkatalog.py --pruefen  # Exit 1, wenn eine der beiden Dateien veraltet ist
python scripts/testkatalog.py --ohne-html  # nur die Markdown-Datei

Wird aus den Testdateien per ast erzeugt (kein Import, läuft ohne QGIS). Nicht von Hand bearbeiten. Nach jeder Änderung an Tests neu erzeugen und mitcommitten. Der Abschnitt „Lücken" in testkatalog.md listet Tests ohne Docstring – Stand 15.09.2026 haben nur 114 von 346 Tests einen, sn_basis fast keine (7 von 94). testkatalog.html ist dasselbe als interaktives Dashboard „Prüfstand" (Baumdiagramm je Testdatei per Mermaid, Filter, Suche) – lokal im Browser öffnen, kein Server nötig; Mermaid lädt von cdnjs.cloudflare.com, ohne Internetverbindung bleiben nur die Diagramme leer.

Testkonzept-Seiten

Für fachlich wichtige Abläufe liegt in docs/tests/<ablauf>.md eine Seite nach docs/vorlagen/testkonzept.md: Mermaid-Diagramm des fachlichen Ablaufs, Tabelle Schritt → deckender Test → bewusst nicht getestet mit Begründung, bekannte Lücken. Sie ermöglicht Fachleuten die Beurteilung, ob die Tests das Richtige prüfen. Wird ein dokumentierter Ablauf geändert, wird die Seite mit nachgezogen.

Fehler deuten

• ModuleNotFoundError: sn_basis → nicht über das Skript gestartet oder Repo fehlt.
• Mock-Klassen ohne Methode (AttributeError: _MockQgs… has no attribute) → Mock im Wrapper ergänzen, nicht den Test umgehen.
• Test erwartet alte Signatur (Einzeldatei statt Liste, ein Layer statt zwei) → veralteter Test nach Umbau auf Mehrfachauswahl; prüfen, ob das neue Verhalten gewollt ist (Issue/Changelog), dann Test anpassen und im PR begründen.
• Test hängt oder braucht Netz → der Test ist falsch gebaut, Dienstantwort nachstellen.

Niemals einen roten Test durch Löschen, @unittest.skip oder Anpassen der Erwartung grün machen – außer das Verhalten wurde bewusst geändert und der PR begründet es.

Baseline

• Datei docs/status/testbaseline.json; wird nur von Maintainern mit python scripts/run_tests.py --update-baseline verändert. Ein Agent fasst sie nicht an.
• Regel: keine neuen roten Tests; bekannte rote Tests werden über eigene Issues grün gemacht.

In echter QGIS-Umgebung (Windows, OSGeo4W)

• Plugins ohne Release in ein QGIS-Profil bringen: python scripts/link_qgis_profile.py --profil dev (verknüpft die Klone unter ihren Paketnamen; danach in QGIS experimentelle Plugins anzeigen, sn_basis zuerst aktivieren).
• Heute nur manuell bzw. über die repo-eigenen tests\test_qgis.bat (enthalten fest verdrahtete Pfade). Der Ausbau zu automatisierten QGIS-Tests ist geplant: docs/konzept/07_qgis_tests_plan.md.
• Pflicht bei: Layer-Operationen, WFS/REST, Drucklayouts, Signalen/Docks. Ergebnis im PR unter „Wie geprüft".
• Agenten ohne QGIS: Test als offenen Punkt im PR benennen, nicht als erledigt ausgeben.