Skip to content

Latest commit

 

History

History

.docker

README.md

QGIS Docker images

The QGIS project provides a few official docker images that can be used for testing purposes.

These dockers are currently used to run continuous integration tests for the QGIS project itself and to run continuous integration tests for several third party Python plugins.

The images are automatically built every day and pushed on docker hub to the QGIS account: https://hub.docker.com/r/qgis/

Available images

Dependencies image

qgis/qgis3-build-deps

This is a simple base image that contains all the dependencies required to build QGIS, it is used by the other images.

Multiple versions of this image may be available: the suffix in the image name indicates the Ubuntu version they are based on.

Main QGIS image

qgis/qgis

This is the main image containing a build of QGIS.

The docker tags for this image are assigned for each point release (prefixed with final-), for the active development branches (prefixed with release-) while the latest tag refers to a build of the current master branch.

Features

The docker file builds QGIS from the current directory and sets up a testing environment suitable for running tests inside QGIS.

You can use this docker image to test QGIS and/or to run unit tests inside QGIS, xvfb (A fake X server) is available and running as a service inside the container to allow for fully automated headless testing in CI pipelines such as Travis or Circle-CI.

Building

You can build the image from the main directory of the QGIS source tree with:

$ docker build -t qgis/qgis:latest \
    --build-arg DOCKER_TAG=latest \
    -f .docker/qgis.dockerfile \
    .

The DOCKER_TAG argument, can be used to specify the tag of the dependencies image.

Running QGIS

You can also use this image to run QGIS on your desktop.

To run a QGIS container, assuming that you want to use your current display to use QGIS and the image is tagged qgis/qgis:latest you can use a script like the one here below:

# Allow connections from any host
$ xhost +
$ docker run --rm -it --name qgis \
    -v /tmp/.X11-unix:/tmp/.X11-unix  \
    -e DISPLAY=unix$DISPLAY \
    qgis/qgis:latest qgis

This code snippet will launch QGIS inside a container and display the application on your screen.

Running unit tests inside QGIS

Suppose that you have local directory containing the tests you want to execute into QGIS:

/my_tests/travis_tests/
├── __init__.py
└── test_TravisTest.py

To run the tests inside the container, you must mount the directory that contains the tests (e.g. your local directory /my_tests) into a volume that is accessible by the container, see -v /my_tests/:/tests_directory in the example below:

$ docker run -d --name qgis -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v /my_tests/:/tests_directory \
    -e DISPLAY=:99 \
    qgis/qgis:latest

Here is an extract of test_TravisTest.py:

# -*- coding: utf-8 -*-
import sys
from qgis.testing import unittest

class TestTest(unittest.TestCase):

    def test_passes(self):
        self.assertTrue(True)

def run_all():
    """Default function that is called by the runner if nothing else is specified"""
    suite = unittest.TestSuite()
    suite.addTests(unittest.makeSuite(TestTest, 'test'))
    unittest.TextTestRunner(verbosity=3, stream=sys.stdout).run(suite)

When done, you can invoke the test runnner by specifying the test that you want to run, for instance:

$ docker exec -it qgis sh -c "cd /tests_directory && qgis_testrunner.sh travis_tests.test_TravisTest.run_fail"

The test can be specified by using a dotted notation, similar to Python import notation, by default the function named run_all will be executed but you can pass another function name as the last item in the dotted syntax:

# Call the default function "run_all" inside test_TravisTest module
qgis_testrunner.sh travis_tests.test_TravisTest
# Call the function "run_fail" inside test_TravisTest module
qgis_testrunner.sh travis_tests.test_TravisTest.run_fail

Please note that in order to make the test script accessible to Python the calling command must ensure that the tests are in Python path. Common patterns are:

  • change directory to the one containing the tests (like in the examples above)
  • add to PYTHONPATH the directory containing the tests

Running tests for a Python plugin

All the above considerations applies to this case too, however in order to simulate the installation of the plugin inside QGIS, you'll need to make an additional step: call qgis_setup.sh <YourPluginName> in the docker container before actually running the tests (see the paragraph about Running on Travis for a complete example).

The qgis_setup.sh script prepares QGIS to run in headless mode and simulate the plugin installation process:

  • creates the QGIS profile folders
  • "installs" the plugin by making a symbolic link from the profiles folder to the plugin folder
  • installs startup.py monkey patches to prevent blocking dialogs
  • enables the plugin

Please note that depending on your plugin repository internal directory structure you may need to adjust (remove and create) the symbolic link created by qgis_setup.sh, this is required in particular if the real plugin code in your repository is contained in the main directory and not in a subdirectory with the same name of the plugin internal name (the name in metadata.txt).

Options for the test runner

The env var QGIS_EXTRA_OPTIONS defaults to an empty string and can contains extra parameters that are passed to QGIS by the test runner.

Running on Travis

Here is a simple example for running unit tests of a small QGIS plugin (named QuickWKT), assuming that the tests are in tests/test_Plugin.py under the main directory of the QuickWKT plugin:

services:
    - docker
install:
    - docker run -d --name qgis-testing-environment -v ${TRAVIS_BUILD_DIR}:/tests_directory -e DISPLAY=:99 qgis/qgis:latest
    - sleep 10 # This is required to allow xvfb to start
    # Setup qgis and enables the plugin
    - docker exec -it qgis-testing-environment sh -c "qgis_setup.sh QuickWKT"
    # Additional steps (for example make or paver setup) here
    # Fix the symlink created by qgis_setup.sh
    - docker exec  -it qgis-testing-environment sh -c "rm -f  /root/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QuickWKT"
    - docker exec -it qgis-testing-environment sh -c "ln -s /tests_directory/ /root/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QuickWKT"

script:
    - docker exec -it qgis-testing-environment sh -c "cd /tests_directory && qgis_testrunner.sh tests.test_Plugin"

Please note that cd /tests_directory && before the call to qgis_testrunner.sh could be avoided here, because QGIS automatically adds the plugin main directory to Python path.

Running on Circle-CI

Here is an example for running unit tests of a small QGIS plugin (named QuickWKT), assuming that the tests are in tests/test_Plugin.py under the main directory of the QuickWKT plugin:

version: 2
jobs:
  build:
    docker:
      - image: qgis/qgis:latest
        environment:
          DISPLAY: ":99"
    working_directory: /tests_directory
    steps:
      - checkout
      - run:
          name: Setup plugin
          command: |
            qgis_setup.sh QuickWKT
      - run:
          name: Fix installation path created by qgis_setup.s
          command: |
            rm -f  /root/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QuickWKT
            ln -s /tests_directory/ /root/.local/share/QGIS/QGIS3/profiles/default/python/plugins/qgisce
      - run:
          name: run tests
          command: |
            sh -c "/usr/bin/Xvfb :99 -screen 0 1024x768x24 -ac +extension GLX +render -noreset -nolisten tcp &"
            qgis_testrunner.sh tests.test_Plugin

Implementation notes

The main goal of the test runner in this image is to execute unit tests inside a real instance of QGIS (not a mocked one).

The QGIS tests should be runnable from a Travis/Circle-CI CI job.

The implementation is:

  • run the docker, mounting as volumes the unit tests folder in /tests_directory (or the QGIS plugin folder if the unit tests belong to a plugin and the plugin is needed to run the tests)
  • execute qgis_setup.sh MyPluginName script in docker that sets up QGIS to avoid blocking modal dialogs and installs the plugin into QGIS if needed
    • create config and python plugin folders for QGIS
    • enable the plugin in the QGIS configuration file
    • install the startup.py script to disable python exception modal dialogs
  • execute the tests by running qgis_testrunner.sh MyPluginName.tests.tests_MyTestModule.run_my_tests_function
  • the output of the tests is captured by the test_runner.sh script and searched for FAILED (that is in the standard unit tests output) and other string that indicate a failure or success condition, if a failure condition is identified, the script exits with 1 otherwise it exits with 0.

qgis_testrunner.sh accepts a dotted notation path to the test module that can end with the function that has to be called inside the module to run the tests. The last part (.run_my_tests_function) can be omitted and defaults to run_all.