Python comes with a standard doctest module that tests the contents of a docstring, making it easy to write input and output examples in the docstring and making the documentation easier to understand.
The following information is provided here.
- A simple example of testing with doctest
- If there is no error
- If there is an error
- Control output results by options and arguments
-vOptionverboseargument (e.g. function, program, programme)
- Run the doctest module from the command line
- Writing tests in an external text file
- How to write a text file
- Called from py file
- Directly execute a text file
A simple example of testing with doctest
A docstring is a string enclosed in one of the following: (1) the name of the function to be tested, (2) the name of the function to be tested, and (3) the expected output value in Python interactive mode.
"""'''
If there is no error
Make sure that the code is correct in the function and docstring contents.
def add(a, b):
'''
>>> add(1, 2)
3
>>> add(5, 10)
15
'''
return a + b
if __name__ == '__main__':
import doctest
doctest.testmod()
Run this file.
$ python3 doctest_example.py
If there are no errors, nothing will be output.
if __name__ == '__main__'This means “execute subsequent processing only when the corresponding script file is executed from the command line.
If there is an error
If you create and execute the following wrong code, an error will be output.
def add(a, b):
'''
>>> add(1, 2)
3
>>> add(5, 10)
10
'''
return a * b
if __name__ == '__main__':
import doctest
doctest.testmod()
$ python3 doctest_example_error.py
**********************************************************************
File "doctest_example_error.py", line 3, in __main__.add
Failed example:
add(1, 2)
Expected:
3
Got:
2
**********************************************************************
File "doctest_example_error.py", line 5, in __main__.add
Failed example:
add(5, 10)
Expected:
10
Got:
50
**********************************************************************
1 items had failures:
2 of 2 in __main__.add
***Test Failed*** 2 failures.
It is shown as follows.
| Expected output values written in doctest. | Expected |
| Actual output value | Got |
Control output results by options and arguments
-vOption
If you want the output results to be displayed even when there are no errors, run the command with the -v option on the command line.
$ python3 doctest_example.py -v
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items had no tests:
__main__
1 items passed all tests:
2 tests in __main__.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
verboseargument (e.g. function, program, programme)
If you want to always display the output results, specify the argument verbose=True in doctest.testmod() in the py file.
if __name__ == '__main__':
import doctest
doctest.testmod(verbose=True)
The output results will always be displayed without the -v option at runtime.
$ python3 doctest_example_verbose.py
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items had no tests:
__main__
1 items passed all tests:
2 tests in __main__.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Run the doctest module from the command line
if __name__ == '__main__'If you want to do something else in it, you can run the doctest module directly from the command line without calling doctest.testmod() in the py file.
For example, in the following cases
def add(a, b):
'''
>>> add(1, 2)
3
>>> add(5, 10)
15
'''
return a + b
if __name__ == '__main__':
import sys
result = add(int(sys.argv[1]), int(sys.argv[2]))
print(result)
It can receive command line arguments and execute the process as usual.
$ python3 doctest_example_without_import.py 3 4
7
If you run doctest as a script with the -m option, the test will be run against the function in which doctest is written. If you want to display the output results, add -v as before.
$ python3 -m doctest doctest_example_without_import.py
$ python3 -m doctest -v doctest_example_without_import.py
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items had no tests:
doctest_example_without_import
1 items passed all tests:
2 tests in doctest_example_without_import.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Writing tests in an external text file
You can also write the test code in an external text file instead of in the docstring.
How to write a text file
Write in Python interactive mode format, as described in docstring. It is necessary to import the functions to be used.
If you want to put the text file in the same directory as the .py file to be tested, just import it as follows.
>>> from doctest_example import add
>>> add(1, 2)
3
>>> add(5, 10)
15
Called from py file
Call doctest.testfile() in another .py file for testing.
Specify the path of the text file where the test code is written as the argument of doctest.testfile().
import doctest
doctest.testfile('doctest_text.txt')
Run this py file.
$ python3 doctest_example_testfile.py -v
Trying:
from doctest_example import add
Expecting nothing
ok
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items passed all tests:
3 tests in doctest_text.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.
Directly execute a text file
Even if you don't have the py file, you can read the text file directly from the command line and run the tests.
Run the Python command with the -m option to run doctest as a script. You can specify the text file path as a command line argument.
$ python3 -m doctest -v doctest_text.txt
Trying:
from doctest_example import add
Expecting nothing
ok
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 10)
Expecting:
15
ok
1 items passed all tests:
3 tests in doctest_text.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.