Skip to main content

A pytest plugin for testing QGIS python plugins

Project description


PyPI version Downloads CI Code on Github Code style: black Imports: isort pre-commit

A pytest plugin for testing QGIS python plugins.


This plugin makes it easier to write QGIS plugin tests with the help of some fixtures and hooks:


  • qgis_app returns and eventually exits fully configured QgsApplication. This fixture is called automatically on the start of pytest session.
  • qgis_bot returns a QgisBot, which holds common utility methods for interacting with QGIS. Also fixture module_qgis_bot in module scope is provided.
  • qgis_canvas returns QgsMapCanvas.
  • qgis_parent returns the QWidget used as parent of the qgis_canvas
  • qgis_iface returns stubbed QgsInterface
  • qgis_new_project makes sure that all the map layers and configurations are removed. This should be used with tests that add stuff to QgsProject.
  • qgis_processing initializes the processing framework. This can be used when testing code that calls
  • qgis_version returns QGIS version number as integer.
  • qgis_world_map_geopackage returns Path to the world_map.gpkg that ships with QGIS
  • qgis_countries_layer returns Natural Earth countries layer from as QgsVectorLayer


  • qgis_show_map lets developer inspect the QGIS map visually at the teardown of the test. Full signature of the marker is:
    @pytest.mark.qgis_show_map(timeout: int = 30, add_basemap: bool = False, zoom_to_common_extent: bool = True, extent: QgsRectangle = None)
    • timeout is the time in seconds until the map is closed.
    • add_basemap when set to True, adds Natural Earth countries layer as the basemap for the map.
    • zoom_to_common_extent when set to True, centers the map around all layers in the project.
    • extent is alternative to zoom_to_common_extent and lets user specify the extent as QgsRectangle

Check the marker api documentation and examples for the ways markers can be used.

Utility tools

  • clean_qgis_layer decorator found in pytest_qgis.utils is a decorator which can be used with QgsMapLayer fixtures to ensure that they are cleaned properly if they are used but not added to the QgsProject. This is only needed with layers with other than memory provider.
    # of start of a test file
    import pytest
    from pytest_qgis.utils import clean_qgis_layer
    from qgis.core import QgsVectorLayer
    def some_layer() -> QgsVectorLayer:
      return QgsVectorLayer("layer_file.geojson", "some layer")


  • pytest_configure hook is used to initialize and configure QgsApplication. With QGIS >= 3.18 it is also used to patch qgis.utils.iface with qgis_iface automatically.

Command line options

  • --qgis_disable_gui can be used to disable graphical user interface in tests. This speeds up the tests that use Qt widgets of the plugin.
  • --qgis_disable_init can be used to prevent QGIS (QgsApllication) from initializing. Mainly used in internal testing.


  • qgis_qui_enabled whether the QUI will be visible or not. Defaults to True. Command line option --qgis_disable_gui will override this.
  • qgis_canvas_width width of the QGIS canvas in pixels. Defaults to 600.
  • qgis_canvas_height height of the QGIS canvas in pixels. Defaults to 600.


Class to hold common utility methods for interacting with QGIS. Here are some of the methods:

  • create_feature_with_attribute_dialog method to create a feature with default values using QgsAttributeDialog. This ensures that all the default values are honored and for example boolean fields are either true or false, not null.
  • get_qgs_attribute_dialog_widgets_by_name function can be used to get dictionary of the QgsAttributeDialog widgets. Check the test for a usage example.


This pytest plugin requires QGIS >= 3.10 to work.


Install with pip:

pip install pytest-qgis

Development environment

  1. Create a virtual environment and activate it.
  2. pip install pip-tools
  3. pip-sync requirements.txt requirements-dev.txt
  4. pre-commit install

Updating dependencies

  1. pip-compile --upgrade
  2. pip-compile --upgrade


Contributions are very welcome.


Distributed under the terms of the GNU GPL v2.0 license, "pytest-qgis" is free and open source software.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest-qgis-1.3.2.tar.gz (40.7 kB view hashes)

Uploaded source

Built Distribution

pytest_qgis-1.3.2-py3-none-any.whl (25.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page