Doctests

The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as required. 

Module or function tests are written inside triple quoted strings called docstrings. The content inside these strings are excerpts of simple python interpreter sessions, where functions are executed after the ">>>" prompt and the results are printed.

When the doctest module finds docstrings it secretly starts an interpreter session and sends it the sample input string. The interpreter will call your code and send the output to doctest. Doctest will compare the output from the interpreter to the docstring output. If they match exactly, then doctest silently exits and continues running your program.

If anything doesn't match, then doctest outputs the error messages. You'll know if your code is working if your program executes normally with no docstring errors being printed.

Consider the following:
def my_function(a, b): """ >>> my_function(2, 3) 6 """ return a * b def main(): print "running..." print "3 * 4 = ",my_function(3,4) if __name__ == "__main__": import doctest doctest.testmod() main()
The red code is the docstring.  It basically says "if you call my_function() with the parameters 2 and 3, you'd better get a 6 back. Anything else is wrong!".  The green code is what makes the doctest module run. It says "when this program runs, load and run doctest first, then run the program".

Running the program in python does the following:

>>> 
running...
3 * 4 =  12
>>> 

Nothing happened. That's because when doctest tried my_function(2,3) it returned a 6 as required. The test passed, so doctest completed quietly and let the program continue. The program then executed the main() function, which then used our function with 3 and 4.

Let's change our function:

def my_function(a, b): """ >>> my_function(2, 3) 6 """ return a * b + 1


Now when we run it this is what we get:

>>> 
**********************************************************************
File "__main__", line 3, in __main__.my_function
Failed example:
    my_function(2, 3)
Expected:
    6
Got:
    7
**********************************************************************
1 items had failures:
   1 of   1 in __main__.my_function
***Test Failed*** 1 failures.
running...
3 * 4 =  13
>>> 

This time doctest tried the sample input. Since we changed our function we got back a 7 instead of the correct answer 6. Doctest promptly told us which function in which module failed. It also told us what we were supposed to get, and what we actually got. It then told us the total number of failures and then it let the program continue.

Doctest is useful for ensuring our functions basically do what we want them to. It's an easy way for me to make sure your functions are passing some fundamental "sanity" tests by having you include them in your programs. When your functions pass all my doctest code, you're probably nearly done. 

Doctests are also a handy way to make sure you didn't accidentally break something in your code when you're trying to fix some other problem. This is called "regression testing". A regression is when you break something that used to work by trying to fix something else, and it happens a lot.