3. Code schreiben im PyQGIS-Kochbuch

Wenn Sie planen, einige Kapitel des PyQGIS-Entwicklerkochbuch hinzuzufügen oder zu aktualisieren, dann sollten Sie einige Regeln befolgen, um das automatische Testen der Code-Schnipsel zu ermöglichen.

Das Testen ist wirklich wichtig, da es die automatische Überprüfung des Codes ermöglicht. Code-Schnipsel mit Fehlern oder Code, der veraltete Methoden verwendet, werden fehlschlagen und die Benachrichtigung wird Ihnen helfen, die Probleme zu beheben.

Zum testen wird die ‚Sphinx doctest extension <https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html>‘ verwendet. Für weitere, detailierte Informationen schauen Sie bitte in die Dokumentation der Erweiterung.

3.1. Wie schreibe ich testbaren Code?

Das Schreiben von testbarem Code unterscheidet sich kaum von der ‚klassischen‘ Methode. Es wird lediglich eine andere Sphinx Direktive verwendet.

3.1.1. Doctest Sphinx Direktiven

Anstatt Code in .. code-block:: python Direktiven einzubetten (mit automatischem Code Highlighting), muss es jetzt mit .. testcode:: markiert werden. Also, statt diesem:

.. code-block:: python

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

Nutze dieses:

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

Nachdem du Beispielcode geschrieben hast, solltest du eine Behauptung/assertion hinzufügen, die den Code evaluiert und automatisch ausgeführt wird.

Im obigen Beispiel wird ein KBS erzeugt und mit assert crs.isValid() die Validität geprüft. Bei falscher Python-Syntax oder falls crs.isValid() False zurückliefert, wird dieser Codeteil beim Test scheitern.

To successfully run the tests on snippets, you must import all the classes and declare any variables used in the code snippets. You can include those in the code snippet itself (visible in the HTML pages) or you can add them to a .. testsetup:: directive (hidden in the HTML pages). The .. testsetup:: needs to be placed before the .. testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

If the code snippet doesn’t create objects (and therefore you cannot use something like assert object.isValid()), you can test the code using the print() method, then add the expected results within a .. testoutput:: directive to compare the expected output:

.. testcode::

   print("QGIS CRS ID:", crs.srsid())
   print("PostGIS SRID:", crs.postgisSrid())

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

By default, the content of .. testoutput:: is shown in the HTML output. To hide it from the HTML use the :hide: option:

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Bemerkung

If the code snippet contains any print statements, you MUST add a testoutput with the expected outputs; otherwise the test will fail.

3.1.2. Grouping tests

For each rst document, the code snippets are tested sequentially, which means you can use one .. testsetup:: for all the following code snippets and that later snippets will have access to variables declared in earlier ones in the document.

Alternatively, you can use groups to break down the examples on the same page in different tests.

You add the code snippet to groups by adding one or more group names (separated by commas) in the respective directive:

.. testcode:: crs_crsfromID [, morenames]

   crs = QgsCoordinateReferenceSystem("EPSG:4326")
   assert crs.isValid()

The doctest will pick each group snippets and run them independently.

Bemerkung

Use group names that make sense with the related content. Use something similar to <chapter>_<subchapter>, for example: crs_intro, crs_fromwkt. In case of failures, this will help identifying where the failures occur.

If you don’t declare any group, the code snippet will be added to a group named default. If instead, you use * as a group name, the snippet will be used in all testing groups, something normally usefull to use in the test setup:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. How to test snippets on your local machine

Bemerkung

Instructions are valid for Linux system.

To test Python code snippets, you need a QGIS installation. For this, there are many options. You can:

• Use your system QGIS installation with Sphinx from a Python virtual environment:

  make -f venv.mk doctest
  

• Use a manually built installation of QGIS. You’d need to:

  1. Create a custom Makefile extension on top of the venv.mk file, for example a user.mk file with the following content:

     # Root installation folder
     QGIS_PREFIX_PATH = /home/user/apps/qgis-master
     
     include venv.mk
     

     Or

     # build output folder
     QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output
     
     include venv.mk
     

  2. Then, use it to run target doctest:

     make -f user.mk doctest
     

• Run target doctest inside the official QGIS docker image:

  make -f docker.mk doctest
  

  You have to install Docker first because this uses a docker image with QGIS in it.