3.  Escrevendo código no Livro de Receitas do PyQGIS

Se você planeja adicionar ou atualizar alguns capítulos do Passo-a-passo para desenvolvedor PyQGIS, é necessário seguir algumas regras para ativar o teste automático dos trechos de código.

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.

Para testar, usamos a Sphinx doctest extension. Consulte a documentação da extensão para obter informações mais detalhadas.

3.1. Como escrever trechos de código testáveis

Escrever trechos de código testáveis ​​não é tão diferente do método old. Basicamente, você precisa usar uma diretiva diferente do Sphinx.

3.1.1. Diretivas Sphinx Doctest

Ao invés de incorporar o código em uma diretiva ..code-block:: python (que realçaria a sintaxe do código automaticamente), agora você precisa incorporá-lo em um .. testcode::. Ou seja, em vez disso:

.. code-block:: python

   crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.PostgisCrsId)
   assert crs.isValid()

Agora você pode usar:

.. testcode::

   crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.PostgisCrsId)
   assert crs.isValid()

Depois de escrever o código de exemplo, você deve adicionar algumas afirmações que vão avaliar o código e serão executadas automaticamente.

In the above example, you are creating a crs and with assert crs.isValid() you test if it is valid. If the code has a wrong python syntax or the crs.isValid() returns False, this code snippet will fail during testing.

Para executar com sucesso os testes nos trechos, você deve importar todas as classes e declarar quaisquer variáveis ​​usadas nos trechos de código. Você pode incluir estas no próprio trecho de código (visível nas páginas HTML) ou adicioná-los a uma diretiva .. testsetup:: (oculta nas páginas HTML). O .. testsetup:: precisa ser colocado antes do .. testcode:::

.. testsetup::

   from qgis.core import QgsCoordinateReferenceSystem

.. testcode::

   crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.PostgisCrsId)
   assert crs.isValid()

Se o trecho de código não criar objetos (e, portanto, você não puder usar algo como assert object.isValid ()), poderá testar o código usando o método print() e adicionar os resultados esperados dentro de uma diretiva .. testoutput:: para comparar a saída esperada:

.. testcode::

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

.. testoutput::

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Por padrão, o conteúdo de .. testoutput:: é mostrado na saída HTML. Para ocultá-lo do HTML, use a opção :hide::

.. testoutput::
   :hide:

   QGIS CRS ID: 3452
   PostGIS SRID: 4326

Nota

Se o trecho de código contiver alguma declaração de impressão, você DEVE adicionar um testoutput com as saídas esperadas; caso contrário, o teste vai falhar.

3.1.2. Agrupando testes

Para cada documento rst, os trechos de código são testados sequencialmente, o que significa que você pode usar um .. testsetup: para todos os seguintes trechos de código e os trechos posteriores terão acesso a variáveis ​​declaradas nos anteriores, no documento.

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

Você inclui o trecho de código aos grupos adicionando um ou mais nomes de grupos (separados por vírgulas) na respectiva diretiva:

.. testcode:: crs_crsfromID [, morenames]

   crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.PostgisCrsId)
   assert crs.isValid()

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

Nota

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.

Se você não declarar nenhum grupo, o trecho de código será adicionado a um grupo chamado default. Se, ao invés disso, você usar * como um nome de grupo, o trecho será usado em todos os grupos de teste, algo normalmente útil para usar na configuração de teste:

.. testsetup:: *

   from qgis.core import QgsCoordinateReferenceSystem

3.2. Como testar trechos em sua máquina local

Nota

As instruções são válidas para o sistema Linux.

Para testar trechos de código Python, você precisa de uma instalação QGIS. Para isso, existem muitas opções. Você pode:

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

  make -f venv.mk doctest
  

• Use uma instalação criada manualmente do QGIS. Você precisa:

  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
     

     Ou

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

  2. Em seguida, use-o para executar o destino doctest:

     make -f user.mk doctest
     

• Execute o destino doctest dentro da imagem oficial do docker QGIS:

  make -f docker.mk doctest
  

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