Welcome, guest | Sign In | My Account | Store | Cart

Doctest and unittest are like 2 extremes of testing your python code. One is simple and intuitive and the other is powerful and requires more formality. In Python 2.4, doctest, builds in some of the power of unittest, perhaps bridging the gap between the two. This example shows you how to use doctest and the doctest.DocFileSuite feature.

Python, 44 lines
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
A simple doctest involves pasting the results of actually using a
function into a string at the beginning of the function.  Doctest then
checks to make sure that the usage examples work, including
errors. Note -- doctest ignores traceback information, just include
the first line of the traceback and the actual error. In this case,
create a file called example1.py and put into it the following add
function. Simply, running example1.py is all that is necessary to go
thru the tests. If you run example1.py -y, you'll get verbose output.

def add(a,b):
     """
     >>> import example1
     >>> example1.add(1,2)
     3
     >>> example1.add([1],[2])
     [1, 2]
     >>> example1.add([1],2)
     Traceback (most recent call last):
     TypeError: can only concatenate list (not "int") to list
     """
     return a+b

if __name__ == "__main__":
    print '**running standard doctest'
    import doctest,example1
    doctest.testmod(example1)


#To put additional doctests somewhere else and make them a unittest
#testcase, put your tests in a different file like test1.txt. Note ---
#no quoting needed

 >>> import example1
 >>> example1.add('a','b')
'ab'

#then add a few likes of code to the end of example1.py to run the unittest
if __name__ == "__main__":
    print '**running standard doctest'
    import doctest,example1
    doctest.testmod(example1)
    print '**running unittest doctest'
    suite = doctest.DocFileSuite('test1.txt')
    unittest.TextTestRunner().run(suite)

Doctest is a way to use docstring examples (that look like interactive intrepreter sessions) as a way to check your code. Docstrings (text you put at the beginning of a files, functions, and classes) are a simple way of documenting your code and is also leveraged by pydoc and help. It is a good feature in python and adding testing capability to it just makes it even better. Doctest keep examples alive. A potential problem with doctest is that you may have so many tests that your docstrings would hinder rather than help understanding of your code.

Python's unittest is a more formal framework for testing. You put your tests in a separate file and generally inherit from unittest.TestCase to build your own testing class. If you have lots of testcases you can put them together in a suite.

In python 2.4, doctest takes advantage of unittest. You can move your doctests into a separate file with doctest.DocFileSuite -- avoiding the problems of clutter with doctest. The DocFileSuite function adds all of your doctests as unittest testcase to a unittest suite. This hybrid lets you take advantage of the best of both worlds.

Created by John Nielsen on Thu, 16 Sep 2004 (PSF)
Python recipes (4591)
John Nielsen's recipes (36)

Required Modules

  • (none specified)

Other Information and Tasks