Doctests are essentially tests embedded in a docstring. They serve both as example use cases and test cases! A Python expression is provided along with an expected outcome, a test runner collects that and evaluates the expression.

Getting started

Let's take a look at a run-of-the-mill docstring.

def hello(name):
    """
    Returns a greeting message saying Hello.
    :param name: str
    :return: str
    """
    return 'Hello, ' + name

It's a normal docstring with nothing too special. Let's try to get the doctest module to test our test-less function.

$ python -m doctest -v hello.py

2 items had no tests:
    hello
    hello.hello
0 tests in 2 items.
0 passed and 0 failed.
Test passed.

Well, the output says it clear that we have no tests. Now, let's add a doctest. Remember how the Python Shell or REPL works? Remember how you have three arrows indicating input? Yes. Just copy that style.

def hello(name):
    """
    Returns a greeting message saying Hello.
    :param name: str
    :return: str

    >>> hello('Anam')
    'Hello, Anam'
    """
    return 'Hello, ' + name

Time to run the doctest module again.

$ python -m doctest -v hello.py

Trying:
    hello('Anam')
Expecting:
    'Hello, Anam'
ok
1 items had no tests:
    hello
1 items passed all tests:
   1 tests in hello.hello
1 tests in 2 items.
1 passed and 0 failed.
Test passed.

Ah, that looks more like it.

Expecting Exceptions

Let's try something more fun. Let's add a case in our function, if the provided name is just composed of digits, we refuse to greet digits!

def hello(name):
    """
    Returns a greeting message saying Hello.
    :param name: str
    :return: str

    >>> hello('Anam')
    'Hello, Anam'
    """

    if name.isdigit():
        raise ValueError('We do not greet numbers')

    return 'Hello, ' + name

Now, how do we test for exceptions? Well, remember the mantra.

Replicate your shell; success you will be showered with upon you.

So, just replicate your shell! Let's see how the shell reacts to digits.

So, in the doctest,

def hello(name):
    """
    Returns a greeting message saying Hello.
    :param name: str
    :return: str

    >>> hello('Anam')
    'Hello, Anam'
    >>> hello('121')
    Traceback (most recent call last):
    ...
    ValueError: We do not greet numbers
    """

    if name.isdigit():
        raise ValueError('We do not greet numbers')

    return 'Hello, ' + name

Just the first line and the last line of the exception. Don't confuse doctest with a complete, well-formatted and fully laid out stack trace, please! And just three dots to indicate there were more to it. So, let's run this again.

$ python -m doctest -v hello.py

Trying:
    hello('Anam')
Expecting:
    'Hello, Anam'
ok
Trying:
    hello('121')
Expecting:
    Traceback (most recent call last):
    ...
    ValueError: We do not greet numbers
ok
1 items had no tests:
    hello
1 items passed all tests:
   2 tests in hello.hello
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

And yes.

In Production

Of course, in production, you do need to use a test runner. Something in the category of pytest or nose. I personally prefer pytest. Let's take a look at configuring pytest for this.

Not so surprisingly, it discovered no tests in the default configuration. We need to add a simple flag to it --doctest-modules .

That seems to be working, let's try to intentionally run our tests to check if it is really working.

And that is working perfectly. To avoid putting the --doctest-modules flag all the time, consider making a tox.ini file to place your pytest configuration. More on this in the pytest documentation.