Introduction

Gamera does not contain its own unit testing framework, but instead uses the great pytest framework.

This document does not attempt to replicate the pytest documentation, and will only discuss Gamera-specific additions.

Running the provided unit tests

1. Install and test pytest using the instructions here.

2. From the gamera/tests directory, run all the unit tests with the command:

   pytest --tb=no
   

   Alternatively, you can run an individual test, say test_graph.py with:

   pytest --tb=no test_graph.py
   

   In case of failures you can obtain more information by omitting the option "--tb=no".

3. If you only want to run a single test function from a unit test script, use the "keyword" option "-k", e.g.:

   pytest -k test_glyphs_from_xml_gz test_xml.py
   

Adding new unit tests

A new unit test, say test_mystuff.py, is added by the following steps:

1. Create a new test script test_mystuff.py which imports gamera and pytest:

import pytest
from gamera.core import *
init_gamera()

2. Define for each test a function with the prefix test_. pytest will run all these functions. To verify certain results, use the assert statement, e.g.:

def test_something():
    img = load_image("data/OneBit_generic.png")
    assert img.myplugin(3) == 42

3. To verify that certain circumstances (e.g., wrong input data) lead to an exception, use pytest.raises:

def test_wronginput():
    def _fail(img):
        img.myplugin("should only be numeric")
    img = load_image("data/OneBit_generic.png")
    pytest.raises(Exception, _fail, img)

For more details, see the pytest documentation.

Testing Gamera plugins

The unit test in gamera/tests/test_plugins.py will load and run the doc_example functions of all plugins available in Gamera. Therefore, writing a unit test for a Gamera plugin is often as simple as writing a doc_example plugin with the function. This is explained in Writing Plugins: Documenting and unit-testing Plugin functions.