3. Writing code in the PyQGIS Cookbook
If you are planning to add or update some chapters of the PyQGIS Developer Cookbook, then you should follow some rules to enable automatic testing of the code snippets.
Testing is really important because it allows automatic checking of the code. Code snippets with errors or code that uses outdated methods will fail and the notification will help you fix the problems.
For testing, we use the Sphinx doctest extension. Refer to the extension documentation for more detailed information.
3.1. How to write testable code snippets
Writing testable code snippets is not so different from the old method. Basically, you need to use a different Sphinx directive.
3.1.1. Doctest sphinx directives
Instead of embedding the code in a
.. code-block:: python
directive (which would highlight the code syntax automatically), you now need to
embed it in a
.. testcode::. That is, instead of this:
.. code-block:: python crs = QgsCoordinateReferenceSystem("EPSG:4326") assert crs.isValid()
You now use this:
.. testcode:: crs = QgsCoordinateReferenceSystem("EPSG:4326") assert crs.isValid()
After you wrote the example code, you should add some assertion that will evaluate the code and that will be run automatically.
In the above example, you are creating a crs and with
you test if it is valid. If the code has a wrong python syntax or the
False, this code snippet will fail during testing.
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
needs to be placed before the
.. 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
assert object.isValid()), you can test the code using the
print() method, then add the expected results within a
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
If the code snippet contains any print statements, you MUST add a
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()
doctest will pick each group snippets and run them independently.
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
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:
Create a custom
Makefileextension on top of the
venv.mkfile, for example a
user.mkfile with the following content:
# Root installation folder QGIS_PREFIX_PATH = /home/user/apps/qgis-master include venv.mk
# build output folder QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output include venv.mk
Then, use it to run target
make -f user.mk doctest
doctestinside 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.