Docstrings in Python are used not only for the description of a class or a function to provide a better understanding of the code and use but, also used for Testing purposes.
The Doctest Module finds patterns in the docstring that looks like interactive shell commands.
The input and expected output are included in the docstring, then the doctest module uses this docstring for testing the processed output.
After parsing through the docstring, the parsed text is executed as python shell commands and the result is compared with the expected outcome fetched from the docstring.
Here’s a simple example:
1. import testmod from doctest to test the function.
2. Define our test function.
3. Provide a suitable docstring containing desired output on certain inputs.
4. Define the logic.
5. Call the testmod function with the name of the function to test and set verbose True as arguments.Note: All the arguments are optional. The name of the function is explicitly passed to the testmod. It’s useful if there are multiple functions.
Implementation
# import testmod for testing our function from doctest import testmod # define a function to test def factorial(n): ''' This function calculates recursively and returns the factorial of a positive number. Define input and expected output: >>> factorial(3) 6 >>> factorial(5) 120 ''' if n <= 1: return 1 return n * factorial(n - 1) # call the testmod function if __name__ == '__main__': testmod(name ='factorial', verbose = True) |
Output:
Trying:
factorial(3)
Expecting:
6
ok
Trying:
factorial(5)
Expecting:
120
ok
1 items had no tests:
factorial
1 items passed all tests:
2 tests in factorial.factorial
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Now, test for failure. What if our logic is wrong?
# import testmod for testing our function from doctest import testmod # define a function to test def factorial(n): ''' This function calculates recursively and returns the factorial of a positive number. Define input and expected output: >>> factorial(3) 6 >>> factorial(5) 120 ''' if n <= 1: return 1 # wrong logic for factorial return factorial(n - 1) # call the testmod function if __name__ == '__main__': testmod(name ='factorial', verbose = True) |
Output:
Trying:
factorial(3)
Expecting:
6
**********************************************************************
File "woking_with_csv.py", line 33, in factorial.factorial
Failed example:
factorial(3)
Expected:
6
Got:
1
Trying:
factorial(5)
Expecting:
120
**********************************************************************
File "woking_with_csv.py", line 35, in factorial.factorial
Failed example:
factorial(5)
Expected:
120
Got:
1
1 items had no tests:
factorial
**********************************************************************
1 items had failures:
2 of 2 in factorial.factorial
2 tests in 2 items.
0 passed and 2 failed.
***Test Failed*** 2 failures.
Note: If ‘verbose’ is set to False(default), output will be shown in case of failure only, not in the case of success.
