Python's standard distribution contains 'doctest' module. This module's functionality makes it possible to search for pieces of text that look like interactive Python sessions and executes these sessions to see if they work exactly as shown. These examples are extracted from docstring expressions in class, module or function. Doctests can also be run from a text file from an accompanying text file.
In Python, a 'docstring' is a string literal which appears as the first expression in a class, function or module. It is ignored when the suite is executed, but it is recognized by the compiler and put into the __doc__ attribute of the enclosing class, function or module.
The docstrings are commonly put to describe example usage of different parts of Python code. The doctest module allows to verify that these docstrings are up-to-date with the intermittent revisions in code.
In the following code, a factorial function is defined interspersed with example usage. In order to verify if the example usage is correct, call the testmod() function in doctest module.
def add(a,b):
'''
>>> add(10,20)
30
>>> add('aaa','bbb')
'aaabbb'
>>> add('aaa',20)
Traceback (most recent call last):
...
TypeError: must be str, not int
'''
return a+bFirst enter and save above script as mytest.py and try to execute this script from command line.
Python mytest.py
No output will be shown unless the example fails. Now change the command line to
Python mytest.py –v
Now the console will show the following result −
F:\Python36>python mytest.py -v
Trying:
add(10,20)
Expecting:
30
ok
Trying:
add('aaa','bbb')
Expecting:
'aaabbb'
ok
Trying:
add('aaa',20)
Expecting:
Traceback (most recent call last):
...
TypeError: must be str, not int
ok
1 items had no tests:
__main__
1 items passed all tests:
3 tests in __main__.add
3 tests in 2 items.
3 passed and 0 failed.
Test passed.Checking Examples in a Text File
Another simple application of doctest is testing interactive examples in a text file. This can be done with the testfile() function.
Following text is stored in a text file named as 'example.txt'
Using ''add'' ------------------- This is an example text file . First import ''add'' from the ''mytest'' module: >>> from mytest import add >>> add(10,20) 30
The file content is treated as docstring. In order to verify the examples in the text file use the testfile() function of doctest module.
def add(a,b):
return a+b
if __name__ == "__main__":
import doctest
doctest.testfile("example.txt")As with testmod(), testfile() won’t display anything unless an example fails. If an example does fail, then the failing example(s) and the cause(s) of the failure(s) are printed to console, using the same format as testmod().
In most cases a copy-and-paste of an interactive console session works fine, but doctest isn’t trying to do an exact emulation of any specific Python shell.
Any expected output must immediately follow the final '>>>' or '...' line containing the code, and the expected output (if any) extends to the next '>>>' or all-whitespace line.
Expected output cannot contain an all-whitespace line, since such a line is taken to signal the end of the expected output. If expected output does contain a blank line, put <BLANKLINE> in your doctest example each place a blank line is expected.
In this article testmod() and testfile() functions in doctest module have been discussed.