如果您计划添加或查看Pyqgis食谱的某些章节,那么您必须遵循一些规则来启用代码段的自动测试。
测试非常重要,因为它允许自动检查代码的质量。在测试期间,如果代码有错误,测试将失败,这意味着代码段有错误,需要修复。
框架遵循 Sphinx rules :有关详细信息,请参阅本文档。
编写可测试代码段与 old 方法。基本上,你需要使用不同的狮身人面像 directive.
在每个代码段嵌入到 .. code-block:: python
指令:sphinx自动突出显示语法。
为了在代码段上运行测试,必须声明所有类和其他有用的导入。你用这个 .. testsetup::
指令后接代码段中使用的所有导入,例如:
.. testsetup:: *
from qgis.core import QgsCoordinateReferenceSystem
注解
所有代码 .. testsetup:: *
在最终文件中不可见。这个 \*
将导入的类应用于文件中的所有代码段。
您也可以使用 .. testsetup:: example1
以一组名为“example1”的代码段为目标
在这之后,你必须使用 .. testcode::
指令后面跟一个你想要的名字,比如 .. testcode:: example
. 在这个指令中,您应该添加您想要的所有代码(基本上是您添加到 old .. code-block:: python
指令)。
在编写代码之后,您可以添加一些 assertion 这将评估代码,并将自动运行。
一个小片段可以是:
crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.PostgisCrsId)
assert crs.isValid()
基本上你正在创建一个CRS assert crs.isValid()
你 test 如果它是有效的。
当然,您也可以在Python控制台或独立脚本中运行此代码,但是自动测试引擎将负责测试代码片段并检查它是否有效。
然后您可以编写文本并添加另一个 .. testcode:: example2
包含其他断言的代码段。
如果代码段没有创建对象(因此不能使用 assert object.isValid()
)您仍然可以将输出与另一个指令进行比较: .. testoutput:: mysnippet
.
基本上,您必须首先使用已知的名称创建代码,例如 .. testcode:: mysnippet
里面有一些 print
声明:
.. testcode:: mysnippet
print("QGIS CRS ID:", crs.srsid())
print("PostGIS SRID:", crs.srid())
然后添加预期结果:
.. testoutput:: mysnippet
QGIS CRS ID: 3452
PostGIS SRID: 4326
注解
针对Linux系统测试了指令。
你必须安装 Docker 首先,因为我们将在其中使用带有qgis的Docker图像。
要测试python代码段,需要 QGIS 安装。为此,使用了一个包含qgis的Docker图像。有很多选择:
你可以使用你的系统 QGIS 安装 Sphinx 从python虚拟环境:
make -f venv.mk doctest
您可以使用 QGIS, 为此,需要创建一个自定义 Makefile
在 venv.mk
文件,例如a user.mk
包含以下内容的文件:
# Root installation forder
QGIS_PREFIX_PATH = /home/user/apps/qgis-master
# Or build output folder
QGIS_PREFIX_PATH = /home/user/dev/QGIS-build-master/output
include venv.mk
然后用它来运行目标 doctest
::
make -f user.mk doctest
或者你可以跑向目标 doctest
官员内部 QGIS 码头工人形象:
make -f docker.mk doctest