Unit testing with Gamera

Last modified: January 08, 2018



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


py.test is still considered beta-level software, and is somewhat cumbersome to install (perhaps the same could be said about Gamera). It is not required for proper operation of Gamera, and is only needed for those developers who wish to port Gamera to new platforms or write unit tests for new code.

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

Running the provided unit tests

  1. Install and test py.test using the instructions here.
  1. From the gamera/tests directory, run all the unit tests with the command:

    py.test --tb=no

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

    py.test --tb=no test_graph.py

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

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

    py.test -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 py.test:
import py.test
from gamera.core import *
  1. Define for each test a function with the prefix test_. py.test 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
  1. To verify that certain circumstances (e.g., wrong input data) lead to an exception, use py.test.raises:
def test_wronginput():
    def _fail(img):
        img.myplugin("should only be numeric")
    img = load_image("data/OneBit_generic.png")
    py.test.raises(Exception, _fail, img)

For more details, see the py.test 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.