Easy testing with Python doctest and GitLab

Oct 27, 2019 by Thibault Debatty - 135 views

https://cylab.be/blog/44/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