Test Your Python Project

Let’s start with a function that calculates the absolute value of a number.

def to_absolute(number):
    if number <= 0:
        return -number
    return number

Python has built-in functionality that, in my opinion, is really impressive: doctests.

You may have already come across docstrings. If you look at the code in the course projects, you’ll see many instances of three double quotes, some text, and then three more double quotes.

Here’s an example of a docstring with our function  to_absolute(value)  :

def to_absolute(number):
    """
        Return the absolute value

        :param number: Initial number
        :return:  The absolute value
    """
    if number <= 0:
        return -number
    return number

Docstrings are very similar to comments, but they appear over several lines. They are used to document the code, i.e., to explain what the code is supposed to do.

But why are we talking about docstrings in a course about testing? Because you can actually use them to execute tests within the code. This is what we call a “doctest.”

Write a Doctest

A doctest imitates an interactive terminal. Type three chevrons at the start of a line to emulate a terminal, and put the expected result right underneath. I’ll show you.

"""
>>> to_absolute(3)
3
"""

We’re running the to_absolute function with an argument of  3  , exactly as we would if we were using a terminal. We then provide the expected result on the line below:  3 .

We can add a whole sequence of tests to check various scenarios, as shown below: 

"""
>>> to_absolute(3)
3
>>> to_absolute(-10)
10
"""

By using the following command on your terminal:

python -m doctest <filename>

For example, if your function is contained within the  main.py  file, you need to enter the following command:

python -m doctest main.py

And there you have it! Everything’s ready!

Nothing appeared? That’s great—it means all our tests passed successfully! If we want to see the full output, we need to tell it to talk to us. 

To do this, add the-v flag after the keyworddoctest:

python -m doctest -v <module name>

Great! The tests ran correctly.

I’ve made a little screencast to show you all of the steps required to set up doctests for a function: 

If you have any functions that don’t contain any tests, the doctest is smart enough to tell us all of the methods that don’t have any tests. You can try to create a function without a doctest and run the command again to check the result.

Doctests are really useful as documentation. They provide a concrete example showing how the program is supposed to work.

I’m pretty happy with that, but I would like to have a document that only details my tests. This is why I’m going to show you another way of creating tests in a dedicated test document.

Create a Test File

Create a new file in the script parent folder, at the same level as the  README.md, or create the file in a tests/  package containing the full set of tests for the application. This will allow us to distinguish between the source code and the test files.

You can’t use doctests here, because these are designed to be an integral part of the code. So, we need to use a testing framework, which will give us a full environment to start us off.

Understand Testing Frameworks

There are a number of testing frameworks, including Unittest, which is the Python default. In this course, we’re mostly going to use Pytest, which is another highly regarded framework.

Pytest enables you to create highly readable tests and includes a number of tools to make your life easier. We’ll see them in action in the next chapter!

Let’s Recap!

• Doctests can be found within docstrings and are part of a function’s documentation.

• Doctests can provide program documentation and check the behavior of a function.

• There are two testing frameworks, Unittest and Pytest.

You’ve seen some doctests and you’ve been introduced to some testing frameworks. Now it’s time to add your first tests to the project.