========================
Unit testing with Gamera
========================

Introduction
============

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

.. __: https://pytest.org/

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

.. __: https://pytest.org/


Running the provided unit tests
===============================

1. Install and test `pytest` using the instructions here__.

.. __: https://pytest.org/

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:

.. code:: Python

   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.:

.. code:: Python

   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``:

.. code:: Python

   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`__.

.. __: https://pytest.org/


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`__.

.. __: writing_plugins.html#documenting-and-unit-testing-plugin-functions
