Python Doctest

“We know that Python’s docstring provides more details on its functions and classes. The doctest packages write the program that begins with >>> and contrasts the results with what was anticipated. By executing illustrations included in the specification and confirming that they provide the desired results, the doctest tool enables you to evaluate your script. It extracts samples from the reference text, executes them, and then contrasts the results with the target value.

The fact that there has been no API to memorize in the most basic version makes doctest simpler for many programmers to use over unittest. Creating doctest tests could be more difficult than just consuming unittest even as instances get more complicated since there is no resource handling.”

Example 01

Let’s get started with the first example of this article now. We have been starting this example with the import of the “doctest” module at the first line. After this, we have been defining a new function, “testing” with the pointer “args” parameter pointing toward the use of integer values for the testing method. Within this method, we have been using the triple quotes to pass the integer values to the “testing” method to test whether the sum of all values passed is equal to a certain value defined in the very next line.

So, we have passed the 5 values to the testing method and expected the result of 49 as a sum. Then, we tried another test by passing three numbers to the testing function expecting the result of 22, and in the last, again, 5 values were passed to expect the result of 15. The sum() function has been taking the values passed to the testing function as an argument and returning the sum of all. The testmod() function of the doctest module of python has been used here to testify that the calculated value is the same as the expected value. If not, it will throw an error on our console.

Let’s save and execute this program within the Spyder 3 tool to see what happens within the test part. This example’s detailed code is seen in the screenshot.

After the execution of this python code, we have got the output displayed below. It shows that the program has been trying to test the 5 values and expecting 49 as a sum. The returned value “ok” shows that the test has been passed and validated; the returned sum is 49. The next test was applied to three values expecting 22 as a sum, while the test failed because the sum we got was 21.

Text Description automatically generated

After the use of the doctest testing function on the next 5 values, we have passed the test as expected, and the returned sum value is 15. In the end, we have been reported with the result that a total of 2 tests have been passed out of 3. In the screenshot, the outcome of this example is shown.

Example 02

We have been using another example to use the doctest module in our python code to testify to a different mathematical condition. So, we have started this example with the import of the testmod function of the doctest package in python. The function “fact” has been defined by taking a variable value “v” as an argument. The triple quotes followed by the >>> sign are using the fact() function to find out the factorial of a “4” and “2” on two different lines. While the expected result would be 24 and 3 in this case.

The “if” condition has been used to check whether the value of the “v” variable passed to the fact function is equal to or less than 1 and returns 1; otherwise, the factorial of a value “v” would be calculated by the formulae “v*fact(v-1)”.

The main() function is here to use the tesmod() function using the “fact” function within it. It would be testing that the factorial of both the values “4” and “2” passed to the fact() functions would be 24 and 3 or not. This program has been saved and is ready for use now. This example’s detailed code is seen in the screenshot.

After running it, we have got to know that the factorial of 4 returned by the function is 24, which is equal to the expected result, i.e. the test has been passed in this case, i.e. 24. For the second value, the test has failed as the expected factorial of 2 is 3 while the actual result must be 2. So, the report has been displaying that 1 test has been passed while 1 failed. In the screenshot, the outcome of this example is shown.

Example 03

Within this example, we have been importing the testmod function from its doctest module and using the check() function to check that the multiplication result of two values is as expected or not. In the first function call, we have been passing 5 and 3 and expected 15 as a multiplication result, while in the second function call, we have been passing character m and integer 3 while expecting “mmm” as the multiplication result.

The “m*r” multiplication result would be returned to the calling main() function. The main() function is only calling the testmod function to perform 2 tests. This program is now completed and ready to get executed. This example’s detailed code is seen in the screenshot.

On execution, we have got the same values for both multiplication results as the expected result, i.e. 15 and “mmm”. In this case, no test case has been failed, i.e. both tests are passed.


This is it and all about the use of the doctest package of Python in our codes to test programs. For this, we have tried three different examples to compare the resultant value with the expected value of the functions by taking some arguments. All three examples are simple and easy to do on Spyder 3 tool, and you can easily learn the doctest by practising them.

About the author

Kalsoom Bibi

Hello, I am a freelance writer and usually write for Linux and other technology related content