Easy testing with Python doctest and GitLab

When developing some new Python code, you will usually open another terminal to test your function or class using a Python shell… and repeat until you obtain the expected result.

And this is where a novice programmer would stop. If you want to do serious development, the next steps are:

1. writing documentation and
2. writing reproducible tests

And here comes doctest to the rescue!

doctest

Doctest is a standard python module (so nothing to install) that is able to:

1. extract python shell examples from docstrings
2. run these examples
3. check the results match the examples

This means you can simply create tests by copy-pasting your python shell examples into docstrings, like below:

def add(a, b) :
  """ Add two numbers
  
  >>> add(1, 2)
  3
  """
  return a + b

We can now re-run our tests automatically :

python -m doctest -v my_module.py

GitLab

Checking docstring examples should be part of your continuous integration chain. Here is the job you should add to your .gitlab-ci.yml to do this automatically:

test:doctest:
    image: python:3.6
    script:
        - python -m doctest -v my_file.py

However, doctest is not able to recurse into directories or packages. When your project starts to get bigger, you might use a helper script like DoctestAll:

test:doctest:
    image: python:3.6
    script:
        - pip install doctestall
        - doctestall my_module

This blog post is licensed under CC BY-SA 4.0