Easy testing with Python doctest and GitLab

Oct 27, 2019 by Thibault Debatty | 4631 views

Python 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 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)
  return a + b

We can now re-run our tests automatically :

python -m doctest -v my_module.py


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:

    image: python:3.6
        - 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:

    image: python:3.6
        - pip install doctestall
        - doctestall my_module

This blog post is licensed under CC BY-SA 4.0

This website uses cookies. More information about the use of cookies is available in the cookies policy.