Projektwissen/docs/konzept/07_qgis_tests_plan.md

Plan: automatisierte Tests gegen echtes QGIS

Stand 04.09.2026. Vorschlag zur Abstimmung im Team. Ergänzt ../leitfaden/06_tests.md um die zweite Testebene. Recherchestand und Quellen am Ende.

1. Worum es geht

Heute laufen 332 Tests im Mock-Modus — ohne QGIS, in unter einer Sekunde. Das deckt Logik, Parsing und Prüfregeln ab. Es deckt nicht ab, was erst im Zusammenspiel mit QGIS passiert: ob ein Layer wirklich entsteht, ob ein WFS-Ergebnis verarbeitbar ist, ob ein Drucklayout eine Seite erzeugt, ob ein Dock sich sauber wieder abmeldet. Genau dort sitzen die Fehler, die heute nur durch manuelles Klicken auffallen — und die zwischen Qt5 und Qt6 unterschiedlich ausfallen.

Es gibt seit Jahren einen etablierten Weg, QGIS-Plugins ohne Bildschirm und ohne menschliche Interaktion gegen eine echte QGIS-Instanz zu testen. Dieser Plan beschreibt, wie wir dort in vier Stufen hinkommen.

Der Mock-Modus bleibt. Er wird nicht ersetzt. Er ist die schnelle Ebene, die bei jedem Commit läuft; QGIS-Tests sind die langsame Ebene, die bei jedem Pull Request läuft. Wer die Mocks abschafft, tauscht Sekunden gegen Minuten und verliert die Wrapper-Disziplin, die den Qt5/Qt6-Code zusammenhält.

2. Vorab: unsere Zielversionen stimmen nicht mehr

Recherchestand 04.09.2026, geprüft am QGIS-Release-Fahrplan und an den Docker-Tags:

	Version	Status
LTR	3.44	aktueller Langzeit-Release
Stable	4.2	wird am 25.09.2026 zum LTR
3.40	3.40.15 (Januar 2026)	End of Life, keine Updates mehr

workspace.toml sagt qgis_min = "3.40", alle .gitea/templates/metadata.template sagen qgisMinimumVersion=3.40. Das ist keine Testfrage, sondern eine Produktentscheidung: Welche QGIS-Versionen unterstützen wir? Sie muss vor Stufe 2 fallen, weil sie die Test-Matrix bestimmt. Vorschlag zur Diskussion: 3.44 als Minimum, 4.2 als zweites Matrix-Ziel, 3.40 nur solange Bestandsinstallationen es erzwingen.

3. Wie es technisch funktioniert

Der Kern ist qgis.testing.start_app() aus dem QGIS-Quellbaum. Es baut eine vollständige QgsApplication mit registrierten Datenprovidern auf, in einem temporären Profil, und ist idempotent — mehrfacher Aufruf schadet nicht. Plugins lädt es bewusst nicht; das eigene Plugin instanziiert der Test selbst.

import os
if not os.getenv("DISPLAY"):
    os.environ["QT_QPA_PLATFORM"] = "offscreen"   # muss VOR dem App-Start gesetzt sein

from qgis.testing import start_app, unittest
from qgis.testing.mocked import get_iface

QGIS_APP = start_app()
IFACE = get_iface()          # echtes QMainWindow, echter QgsMapCanvas, echter LayerTree

get_iface() liefert kein selbstgebautes Mock, sondern ein QgisInterface-Objekt mit echtem Hauptfenster, echtem Kartenfenster und echtem Layerbaum. Das ist deutlich realitätsnäher als alles, was wir selbst nachbauen könnten, und es kostet uns keine Pflege.

QT_QPA_PLATFORM=offscreen ist der Schalter, der das Ganze ohne Bildschirm laufen lässt — auf dem CI-Server genauso wie unter Windows.

4. Der Stufenplan

flowchart LR
    S1["<b>Stufe 1</b><br/>start_app() lokal<br/><i>klein</i>"]
    S2["<b>Stufe 2</b><br/>Gitea Actions<br/>Matrix 3.44 / 4.2<br/><i>mittel</i>"]
    S3["<b>Stufe 3</b><br/>pytest-qgis<br/><i>klein</i>"]
    S4["<b>Stufe 4</b><br/>Render-Vergleich<br/>Plan41<br/><i>groß</i>"]

    S1 --> S2 --> S3 --> S4

    style S1 fill:#e8f6ec,stroke:#2f9e44
    style S2 fill:#e6f2ff,stroke:#2b7dd9
    style S3 fill:#e6f2ff,stroke:#2b7dd9
    style S4 fill:#fff4e6,stroke:#d9822b

Stufe 1 — QGIS-Tests lokal, ohne CI

Ziel: Eine erste echte QGIS-Suite je Plugin, die ein Entwickler auf seinem Windows-Rechner starten kann.

• Neuer Ordner tests/qgis/ je Plugin-Repo, getrennt von den Mock-Tests in tests/. Beide Suiten bleiben unabhängig lauffähig.
• Start unter Windows über die OSGeo4W-Umgebung: C:\OSGeo4W\bin\python-qgis-ltr.bat -m pytest tests\qgis -v. Ein normales python -m pytest findet die QGIS-Bindings nicht.
• Die vorhandenen Skripte tests/test_qgis.bat und tests/start_osgeo4w_qgis.bat werden dabei ersetzt. Sie enthalten heute fest verdrahtete Pfade (D:\OSGeo, D:\QGISQT5) und funktionieren nur auf einem Rechner.
• Erste Kandidaten, weil dort der Mock-Modus am wenigsten aussagt: Layer anlegen und stylen (sn_basis), Verarbeitung einer WFS-Antwort (sn_verfahrensgebiet), Erzeugen eines Drucklayouts (sn_plan41).

Aufwand: klein. Kein neues Werkzeug, keine Infrastruktur. Nutzen: sofort, aber nur für die, die es lokal ausführen.

Stufe 2 — Gitea Actions mit Docker

Ziel: Jeder Pull Request wird automatisch gegen zwei QGIS-Generationen geprüft, ohne dass jemand eine zweite QGIS-Version installiert.

Das ist der größte Hebel des ganzen Plans. Der Qt5/Qt6-Unterschied ist in fallstricke.md ein Dauerthema, und er lässt sich mit Bordmitteln kaum abdecken — hier fällt er automatisch auf.

Die offiziellen Images qgis/qgis bringen QGIS samt Bindings mit. Verifizierte Tags (Stand 04.09.2026): 3.44, 3.44.14, 4.0, 4.2, 4.2.2, ltr, stable. QGIS 4 gibt es nur auf Qt6-Distributionen (Debian trixie, Ubuntu questing) — kein 4.x-noble.

name: QGIS-Tests
on:
  pull_request:
    branches: [unstable, testing, stable]

jobs:
  qgis:
    runs-on: ubuntu-latest        # Label muss auf einen Docker-fähigen act_runner zeigen
    strategy:
      fail-fast: false
      matrix:
        qgis: ["3.44", "4.2"]
    steps:
      - uses: actions/checkout@v4
      - name: Tests in QGIS ${{ matrix.qgis }}
        run: |
          docker run --rm -v "$PWD":/src -w /src \
            -e QT_QPA_PLATFORM=offscreen \
            qgis/qgis:${{ matrix.qgis }} \
            bash -c "python3 -m venv /venv --system-site-packages \
                     && /venv/bin/pip install -q pytest \
                     && /venv/bin/pytest tests/qgis -v"

Zu klären vor der Umsetzung:

• Der vorhandene Gitea-Runner trägt das Label alpine-latest (siehe docs/vorlagen/gitea_workflow_tests.yaml). Für Docker-in-Docker braucht es einen Runner mit Docker-Zugriff. Das ist eine Frage an den Maintainer der Runner-Infrastruktur, keine Codefrage.
• Die Fachplugins brauchen im Container auch sn_basis. Das Muster steckt schon in docs/vorlagen/gitea_workflow_tests.yaml: die Nachbar-Repos dazuklonen und unter ihren Paketnamen ablegen.

Aufwand: mittel, im Wesentlichen Infrastruktur. Nutzen: hoch und dauerhaft.

Stufe 3 — pytest-qgis

Ziel: Die bekannten Stolperfallen von QGIS-Tests nicht selbst lösen müssen.

pytest-qgis (Version 4.1.1, August 2026, Python ≥ 3.10, QGIS ≥ 3.34, Qt6-tauglich seit 3.0.0) bringt mit:

Was	Warum wichtig
Fixture qgis_app	startet die App einmal je Sitzung
Fixture qgis_iface	patcht qgis.utils.iface automatisch — sonst ist es None
Fixture qgis_new_project	leeres Projekt je Test; sonst wirken Layer aus Test A in Test B nach
automatisches Layer-Aufräumen	verhindert die bekannten Abstürze beim Beenden
Fixture qgis_processing	Processing-Registry initialisiert
--qgis_disable_exit	Notausgang, falls es beim Beenden doch kracht

Aufwand: klein — etwa eine halbe Stunde plus Umstellung der bis dahin geschriebenen Tests. Empfehlung: erst nach Stufe 2, damit die Umstellung einmal an einer laufenden CI verifiziert wird.

Stufe 4 — Render-Vergleich für Plan41

Ziel: Erkennen, wenn sich das Aussehen eines Plans ungewollt ändert.

Für ein Plugin, dessen Zweck das Zeichnen von Plänen nach § 41 FlurbG ist, ist das fachlich der wertvollste Testtyp — und der teuerste. Mit einem verifizierten Fallstrick:

QgisTestCase.render_layout_check() und render_map_settings_check() suchen Referenzbilder über setControlPathPrefix() in einem zur Compile-Zeit einkompilierten Pfad des QGIS-Quellbaums. In einer installierten QGIS-Version existiert dieser Pfad nicht. Die bequemen Helfer sind für Plugins nicht nutzbar.

Gangbar sind stattdessen:

• QgsLayoutExporter.renderPageToImage() und ein eigener, toleranter Bildvergleich, oder
• QgsRenderChecker direkt, das als einziges setControlImagePath() anbietet.

Bedingungen, ohne die es nur Ärger macht:

• Referenzbilder im CI-Container erzeugen, nie auf einem Entwickler-Windows. Schriftrendering und Antialiasing unterscheiden sich zwischen den Plattformen und erzeugen sonst dauerhaft rote Tests.
• Toleranz einplanen (Farbabweichung und Anteil abweichender Pixel), nicht auf Byte-Gleichheit prüfen.
• Mit zwei bis drei Referenzplänen anfangen, nicht mit fünfzig.

Aufwand: groß. Erst angehen, wenn Stufen 1–3 stabil laufen.

5. Was wir bewusst nicht machen

Ansatz	Warum nicht
YAML-Testframework für Processing-Algorithmen	An nose2, utilities.py und CTest im QGIS-Quellbaum gebunden. Für externe Plugins nur mit Portierungsaufwand nutzbar. Stattdessen processing.run(...) und assertLayersEqual.
qgis_setup.sh / qgis_testrunner.sh (Plugin im echten QGIS laden)	Kein pytest-Reporting; Erfolg wird über String-Suche in der Standardausgabe erkannt. Nur nötig, wenn der Plugin-Ladevorgang selbst geprüft werden soll.
pytest-xdist (Parallelisierung)	Bei unserer Teamgröße und Suite-Laufzeit unnötige Komplexität.
Eigenes Docker-Image bauen	qgis/qgis plus pip install im Job reicht.
pb_tool	Deployment-Helfer, kein Testwerkzeug. Lokal Geschmackssache.

6. Bekannte Fallstricke

Wandern bei der Umsetzung nach docs/wissen/fallstricke.md:

• QT_QPA_PLATFORM muss vor dem Erzeugen der QgsApplication gesetzt sein. Danach wirkt es nicht mehr.
• qgis.utils.iface ist nach start_app() None. Entweder pytest-qgis verwenden oder selbst qgis.utils.iface = get_iface() setzen — und darauf achten, keine Module zu früh zu importieren.
• QgsProject.instance() ist global. Ohne Aufräumen zwischen den Tests beeinflussen sie sich gegenseitig.
• Abstürze beim Beenden sind ein bekanntes QGIS-Thema, wenn Layer- oder Canvas-Objekte noch referenziert werden. Gegenmittel: pytest-qgis oder --qgis_disable_exit.
• offscreen hat keinen Fenstermanager. Fokus, activeWindow() und Drag-and-drop verhalten sich anders. Für Widget-Tests notfalls xvfb-run -a davorsetzen (nur Linux).
• Modale Dialoge blockieren den Test. Reihenfolge der Gegenmittel: den modalen Aufruf per monkeypatch ersetzen; open() statt exec() verwenden; erst als letztes QTimer.singleShot mit einem Klick-Handler.
• Locale. Die Container laufen mit LANG=C.UTF-8, Entwickler-Windows meist auf Deutsch. Tests, die formatierte Zahlen oder Datumsangaben vergleichen, brechen sonst nur an einem der beiden Orte.
• QGIS 4 / PyQt6. exec_() gibt es nicht mehr, Enum-Kurzformen (Qt.UserRole) auch nicht. Das trifft Testcode genauso wie Produktivcode. Für den Umstieg gibt es das Prüfwerkzeug pyqgis4-checker.

7. Vorschlag zur Reihenfolge

1. Entscheidung zu den Zielversionen (Abschnitt 2) — blockiert Stufe 2, eigenes Issue.
2. Stufe 1 an einem Plugin als Machbarkeitsnachweis, am besten sn_basis (keine Abhängigkeiten).
3. Runner-Frage klären — hat der Gitea-Runner Docker?
4. Stufe 2 für sn_basis, dann für die Fachplugins.
5. Stufe 3, sobald mehr als eine Handvoll QGIS-Tests existiert.
6. Stufe 4 als eigenes Vorhaben mit eigenem Konzept.

Die Stufen 1 bis 3 sind zusammen etwa der Aufwand, den heute ein größeres Fach-Issue kostet. Stufe 4 ist ein eigenes Vorhaben.

Quellen

Recherchestand 04.09.2026.

• qgis.testing (start_app, QgisTestCase): https://github.com/qgis/QGIS/blob/master/python/testing/__init__.py
• qgis.testing.mocked.get_iface(): https://github.com/qgis/QGIS/blob/master/python/testing/mocked.py
• Docker-Images und Test-Helfer: https://github.com/qgis/QGIS/blob/master/.docker/README.md
• Tag-Liste: https://hub.docker.com/r/qgis/qgis/tags
• Release-Fahrplan (LTR-Termine): https://qgis.org/resources/roadmap/
• Unit-Testing und Render-Checks: https://docs.qgis.org/testing/en/docs/developers_guide/unittesting.html
• QgsRenderChecker vs. QgsMultiRenderChecker: https://github.com/qgis/QGIS/blob/master/src/core/qgsrenderchecker.h
• pytest-qgis: https://github.com/GispoCoding/pytest-qgis · https://pypi.org/project/pytest-qgis/
• Modale Dialoge im Test: https://pytest-qt.readthedocs.io/en/latest/note_dialogs.html
• Migration zu Qt6/QGIS 4: https://plugins.qgis.org/docs/migrate-qgis4/ · https://github.com/qgis/pyqgis4-checker
• Gitea Actions, Runner-Labels: https://docs.gitea.com/usage/actions/act-runner/

Vorbilder mit echter QGIS-Testsuite, als Muster zum Abschauen:

• 3liz/lizmap-plugin — Matrix über drei QGIS-Versionen, eigener start_app()-Ersatz, dem hiesigen Setup am nächsten
• opengisch/qfieldsync — Dialog-Tests gegen echtes QGIS, Matrix inklusive QGIS 4
• opengisch/qgis_plugins_test_demo — kleines Referenz-Repo, unter anderem ein Drucklayout-Test