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

---
name: sn-tests
description: 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)
```bash
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.

```python
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
```bash
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.

## Test-Audit (Prüfvermerke)
`python scripts/test_audit.py status <paket> --nur ungeprueft` zeigt offene Testfälle. **`markieren` nur auf
ausdrückliche Aufforderung** – die Markierung bedeutet „ein Mensch hat fachlich bestätigt". Ohne Freigabe:
sichten, Lücken ergänzen, mit `markieren … --trocken` die vorgeschlagenen Treffer zeigen und nachfragen.
Details: `docs/leitfaden/06_tests.md` Abschnitt 7.

## 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.