pctechguide.com

  • Home
  • Guides
  • Tutorials
  • Articles
  • Reviews
  • Glossary
  • Contact

Guidelines on Troubleshooting Python Code

Whenever we write a computer program we need to verify that it works as expected. Usually we execute the code, if necessary we provide some inputs, and finally we observe if the output obtained is what we want. If not, check the program, make the necessary corrections, and repeat the previous process. The action of testing and verifying that a program generates the expected results is usually done manually and not automatically. This can be tedious and time consuming when the software being written goes beyond a relatively small application.

Fortunately, there are automated unit tests, which are portions of code designed to check that the main code is working as expected.

Let’s look at an example. Suppose we want to write in Python a function that calculates the hypotenuse c of a right triangle given its a and b legs:

Pythagoras’ theorem states that the square of the hypotenuse is equal to the sum of the squares of the respective legs, that is:

In Python the hypotenuse function could be coded as follows:
from math import sqrt

def hypotenuse(a, b):
return sqrt(a ** 2 + b ** 2)
NOTE: All code presented here was tested with Python 3.7.

The following code could be considered a unit test to verify that the hypotenuse function returns the expected result from entries 3 and 4:
if hypotenuse(3.0, 4.0) == 5.0:
print(‘Passed the test’)
else
print(‘Test failed’)
However, writing tests similar to the previous example is not recommended because it requires a lot of code when we want to make multiple tests and it is not the conventional way to do it.

Source: searchengineland.com

The standard Python distribution provides two mechanisms that simplify the writing and automation of our unit tests: unittest and doctest. The first option is a module inspired by the unit testing frameworks developed by Erich Gamma and Kent Beck for the Java and Smalltalk languages. The second option, doctest, is generally considered simpler to use than unittest, although the latter may be more suitable for more complex tests.

Next I will make a brief introduction to the doctest module in order to elaborate unit tests when defining functions in Python.

The doctest goes inside the docstring
A docstring is a string of characters that is placed as the first statement of a module, class, method or function in order to explain its intent. I explained this a few years ago in more detail in this blog post titled Documenting Programs in Python.

The hypotenuse function, defined above, could have the docstring shown here:
from math import sqrt

def hypotenuse(a, b):
Calculate the hypotenuse of a right triangle.

Use the Pythagorean theorem to determine the
hypotenuse from the legs of a triangle.

Parameters:
a -- first leg
b -- second leg

'''
return sqrt(a ** 2 + b ** 2)

Here the docstring is a string of multi-line characters, which begins and ends with single (”’) or double (“””) double quotes.

The doctest module searches docstrings for text fragments that look like interactive Python sessions in order to execute them and verify that they work exactly as shown.

For example, the next Python interactive session shows how the hypotenuse function behaves with different arguments:

hypotenuse(3.0, 4.0)
5.0
hypotenuse(0.0, 0.0)
0.0
hypotenuse(8.0, 15.0)
17.0
hypotenuse(39.0, 80.0)
89.0
round(hypotenuse(1.0, 1.0), 4)
1.4142
NOTE: In the latter case the round function was used to round the result to 4 digits after the decimal point. It is recommended to do it in this way in order to avoid the precision problems that arise when real numbers appear with a fractional part composed of many digits.

The full text of this interactive session, including the prompts of the interpreter (>>>), is placed inside the doctring, typically at the end, although it can actually go anywhere:
from math import sqrt

def hypotenuse(a, b):
Calculate the hypotenuse of a right triangle.

Use the Pythagorean theorem to determine the
hypotenuse from the legs of a triangle.

Parameters:
a -- first leg
b -- second leg

Examples of use:

>>> hypotenuse(3.0, 4.0)
5.0
>>> hypotenuse(0.0, 0.0)
0.0
>>> hypotenuse(8.0, 15.0)
17.0
>>> hypotenuse(39.0, 80.0)
89.0
>>> round(hypotenuse(1.0, 1.0), 4)
1.4142

'''
return sqrt(a ** 2 + b ** 2)

Running the evidence
There are two options for running the tests. The first option is to use the system terminal and run a command similar to the next one (assuming that the file containing our code is called pitagoras.py):
python3 -m doctest pitagoras.py
The -m doctest option tells the Python interpreter to run the doctest module. The command does not produce any output if it passes all tests.

If any test fails, then you will see a message with the relevant information. For example, if we add to the doctring the following case, which has an incorrect result:

hypotenuse(2.0, 2.0)
2.0
when running the tests again we get a message similar to the following one:


File “pitagoras.py”, line 25, in
pitagoras.hypotenusa
Failed example:
hypotenuse(2.0, 2.0)
Expected:
2.0
Got:
2.8284271247461903


1 items had failures:
1 of 6 in pitagoras.hypotenusa
Test Failed 1 failures.
You can also add the -v option (enable verbose or detailed mode) on the command line when running our tests. In this case a complete report is produced with the information of all the tests, whether they were successful or not:
python3 -m doctest pitagoras.py -v
The way out in this case would be:
Trying:
hypotenuse(3.0, 4.0)
Expecting:
5.0
ok
Trying:
hypotenuse(0.0, 0.0)
Expecting:
0.0
ok
Trying:
hypotenuse(8.0, 15.0)
Expecting:
17.0
ok
Trying:
hypotenuse(39.0, 80.0)
Expecting:
89.0
ok
Trying:
round(hypotenuse(1.0, 1.0), 4)
Expecting:
1.4142
Okay.
Trying:
hypotenuse(2.0, 2.0)
Expecting:
2.0


File “pitagoras.py”, line 25, in
pitagoras.hypotenusa
Failed example:
hypotenuse(2.0, 2.0)
Expected:
2.0
Got:
2.8284271247461903
1 items had no tests:
pitagoras


1 items had failures:
1 of 6 in pitagoras.hypotenusa
6 tests in 2 items.
5 passed and 1 failed.
Test Failed 1 failures.
The second option to run the tests is to add the following three lines of code at the end of the pitagoras.py file:
if name == ‘main‘:
import doctest
doctest.testmod()
The previous if statement checks whether the current file is being executed as a program (when the name variable is equal to the string ‘main‘) or if it was imported as a module (when the name variable is equal to the module name, in this case the string ‘pitagoras’). We only want to carry out the tests when the file is run as a program and, when so, we import the doctest module followed by the invocation of its testmod function.

After this we can run our file as we see fit (for example, from the terminal or using our favorite development environment). If it is from the terminal, just type the following command:
python3 pitagoras.py
As we saw before, if no output is produced it means that all the tests were passed.

If we want to see the whole report of successful and failed tests we can add again the -v option in the terminal command:
python3 pitagoras.py -v
Alternatively, the same effect can be achieved by modifying the code to add the optional True verbose parameter when invoking the testmod function:
doctest.testmod(verbose=True)
Now, every time the file is run as a program, regardless of whether or not the -v option was used from the terminal, you will get the full report with the result of all tests.

With all the mentioned adjustments, the file pitagoras.py remains in its final version like this:
from math import sqrt

def hypotenuse(a, b):
Calculate the hypotenuse of a right triangle.

Use the Pythagorean theorem to determine the
hypotenuse from the legs of a triangle.

Parameters:
a -- first leg
b -- second leg

Examples of use:

>>> hypotenuse(3.0, 4.0)
5.0
>>> hypotenuse(0.0, 0.0)
0.0
>>> hypotenuse(8.0, 15.0)
17.0
>>> hypotenuse(39.0, 80.0)
89.0
>>> round(hypotenuse(1.0, 1.0), 4)
1.4142
>>> hypotenuse(2.0, 2.0)
2.0

'''
return sqrt(a ** 2 + b ** 2)

if name == ‘main‘:
import doctest
doctest.testmod(verbose=True)
This version of the program can be run from the terminal, as already explained, or from any editor or development environment for Python (IDLE, Spyder, Visual Studio Code, etc.) using the respective mechanisms available to execute code.

Best Practices
These are some recommended practices when writing unit tests using doctest:
They should logically be as simple as possible.

Filed Under: Articles

Latest Articles

Capturing Digital Video

The digitisation of the analogue TV signal is performed by a video capture card which converts each frame into a series of bitmapped images to be displayed and manipulated on the PC. This takes one horizontal line at a time and, for the PAL … [Read More...]

HP Stream 11 – The Cheaper Answer to Chromebooks?

Microsoft probably has now found the contender with Hewlett Packard’s frontliner HP Stream 11 against Google’s Chromebooks in the cheap netbook department. For the budget conscious, they may want to take a good look at this inexpensive piece of a contender. If you only need is to access the web, … [Read More...]

Illustrated guide to high-k dielectrics and metal gate electrodes

The Penryn processor debuted Intel's 45nm fabrication, and was the first to utilize high-k gate dielectrics and metal gate electrodes. This change in technology was significant for a number of reasons: the processes used were far in advance of Intel's competition it provided a basis on which … [Read More...]

Gaming Laptop Security Guide: Protecting Your High-End Hardware Investment in 2025

Since Jacob took over PC Tech Guide, we’ve looked at how tech intersects with personal well-being and digital safety. Gaming laptops are now … [Read More...]

20 Cool Creative Commons Photographs About the Future of AI

AI technology is starting to have a huge impact on our lives. The market value for AI is estimated to have been worth $279.22 billion in 2024 and it … [Read More...]

13 Impressive Stats on the Future of AI

AI technology is starting to become much more important in our everyday lives. Many businesses are using it as well. While he has created a lot of … [Read More...]

Graphic Designers on Reddit Share their Views of AI

There are clearly a lot of positive things about AI. However, it is not a good thing for everyone. One of the things that many people are worried … [Read More...]

Redditors Talk About the Impact of AI on Freelance Writers

AI technology has had a huge impact on our lives. A 2023 survey by Pew Research found that 56% of people use AI at least once a day or once a week. … [Read More...]

11 Most Popular Books on Perl Programming

Perl is not the most popular programming language. It has only one million users, compared to 12 million that use Python. However, it has a lot of … [Read More...]

Guides

  • Computer Communications
  • Mobile Computing
  • PC Components
  • PC Data Storage
  • PC Input-Output
  • PC Multimedia
  • Processors (CPUs)

Recent Posts

What’s Behind the Increasing Demand for VPNs

Virtual Private Networks (VPNs) have emerged as a must-have tool over the last year. VPN downloads surged in 2023 for businesses and personal use. … [Read More...]

Safe Mode Backup

The boot.ini file is on the system partition at the root of the drive, usually C:boot.ini. By default, it's a hidden system file, so you'll … [Read More...]

Core i7 3rd Gen

Finally, the long rumored and much hyped third generation Core processors were unveiled by Intel in April 2012.  This series of Intel processors is … [Read More...]

[footer_backtotop]

Copyright © 2025 About | Privacy | Contact Information | Wrtie For Us | Disclaimer | Copyright License | Authors