Testing through documentation — Python: Automated testing

Python has built-in testing through documentation in addition to the classic tests. It is an unusual way to write tests, but developers sometimes use it for library functions. In this lesson, we'll study this topic in more detail to learn what such documentation looks like.

Testing through documentation

The idea is pretty simple. We call a function inside the terminal. The call itself and the resulting output are the tests. Then, we add them to the documentation of the function:

# Example.py has a function called `reverse()` that reverses a string
# The `-i` flag turns on the interactive mode after module execution
python -i example.py
reverse('')
# ''
reverse('Hexlet')
# 'telxeH'

After making the necessary calls, we add them to the function description:

def reverse(string):
    """Reverse string

    >>> reverse('')
    ''

    >>> reverse('Hexlet')
    'telxeH'
    """

    return string[::-1]

# We need to run tests
if __name__ == "__main__":
    import doctest
    doctest.testmod()

If we pass this file to the interpreter, we'll see a report on the tests performed:

# For the detailed output, you need to add a flag `-v` (verbose)
python example.py -v
Trying:
    reverse('')
Expecting:
    ''
ok
Trying:
    reverse('Hexlet')
Expecting:
    'telxeH'
ok
1 items had no tests:
    __main__
1 items passed all tests:
   2 tests in __main__.reverse
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

It is how documentation can simultaneously act as tests, which is convenient and practical. We can do the same not only in a specific function but also at the module level:

"""
It is the example module.

The example module supplies the `reverse()` function, for example:

>>> reverse('awesome!')
'!emosewa'
"""

Recommended materials

1. Doctest documentation