Writing Doctests

Writing a Doctest is just like writing a Docstring.

Example 1

def build_cells(width, height):
    """Create and return a 'width' x 'height' grid of two-tuples

    >>> cells = build_cells(2,2)
    >>> len(cells)
    4

    """
    cells = []
    for y in range(height):
        for x in range(width):
            cells.append((x, y))
    return cells

Example 2

def get_locations(cells):
    """Randomly pick starting locations for the monster, the door, 
    and the player.

    >>> cells = build_cells(2,2)
    >>> m, d, p = get_locations(cells)
    >>> m != d and d!= p
    True
    >>> d in cells
    True

    """
    monster = random.choice(cells)
    door = random.choice(cells)
    player = random.choice(cells)

    if monster == door or monster == player or door == player:
        monster, door, player = get_locations(cells)

    return monster, door, player

Writing a Doctest via Testing

In the Python console, import your app and test the unit you want to test (e.g. a method).

>>> from dd_game import get_moves
>>> GAME_DIMENSIONS = (2, 2)
>>> get_moves((0, 2))
['RIGHT', 'UP', 'DOWN']

Now, excluding the import statement, copy these code lines and paste them directly into unit you tested as a Doctest.

def get_moves(player):
    """ Based on the tuple of the player's position, return the list
    of acceptable moves
 
    >>> GAME_DIMENSIONS = (2, 2)
    >>> get_moves((0, 2))
    ['RIGHT', 'UP', 'DOWN']

    """
    x, y = player
    moves = ['LEFT', 'RIGHT', 'UP', 'DOWN']
    if x == 0:
        moves.remove('LEFT')
    if x == GAME_DIMENSIONS[0] - 1:
        moves.remove('RIGHT')
    if y == 0:
        moves.remove('UP')
    if y == GAME_DIMENSIONS[1] - 1:
        moves.remove('DOWN')
    return moves

Running the Test

From the command line

After you finish writing all of your Doctests, run the following code in the console.

python -m doctest dd_game.py

So what is this -m?
This tells Python to load the doctest module, and the doctest module has some special code written in it that says you’re going to give me a file and I’m going to look through that file for doctests.
And I’m going to find the doctests and I’m going to run them.
After running this command, if nothing comes back, it means all the tests have passed successfully.

From inside a script

import doctest
...
doctest.testmod()

Doctests Shortcomings!

Doctests do have some serious shortcomings though.
They’re pretty tightly bound to the code they’re written on, so you can’t just reuse them for new functions or classes, and all of their checking is done through string comparison, so sometimes floats can be tricky or even impossible to test with doctests.

Documentation

For more information, check the Doctest documentation
https://docs.python.org/3/library/doctest.html