Python Doctesting: A Comprehensive Guide

in

Let’s talk about Python doctesting an awesome tool that lets you add interactive tutorials for your code while also testing its functionality. Doctests are like having a built-in tutor for your functions and classes, which is pretty cool if you ask me!

Here’s how it works: you can add comments with examples right inside your code that can be run as tests. For example:

# This function adds two numbers together and returns the result.
def add_numbers(x, y):
    """Add two numbers together and return the result.

    > add_numbers(2, 3)
    5
    """
    # The function takes in two parameters, x and y, and adds them together using the "+" operator.
    # The result is then returned.
    return x + y

In this example, we’ve added a docstring (a string that describes what our function does) along with an example usage of it using triple quotes (the “>” part). This is called a doctest.

Now let’s run the tests:

# Import the necessary modules
import unittest # Importing the unittest module for testing
from my_module import add_numbers # Importing the add_numbers function from the my_module file

# Create a class for testing the add_numbers function
class TestAddNumbers(unittest.TestCase):
    # Create a test method for testing the addition functionality of the add_numbers function
    def test_addition(self):
        # Use the assertEqual method to check if the result of add_numbers(2, 3) is equal to 5
        self.assertEqual(add_numbers(2, 3), 5) # The add_numbers function should return the sum of the two numbers passed in as arguments

# Check if the script is being run directly and not imported as a module
if __name__ == "__main__":
    # Run the tests using the unittest module's main method
    unittest.main() # This will run all the tests defined in the TestAddNumbers class

In this example, we’ve created a new class called `TestAddNumbers` that inherits from the built-in `unittest.TestCase`. We’re using the `assertEqual` method to compare our expected output (5) with what is returned by calling the `add_numbers` function.

Doctests can also be used for testing classes and their methods:

# Creating a new class called TestAddNumbers that inherits from the built-in unittest.TestCase
class TestAddNumbers(unittest.TestCase):
    
    # Using the assertEqual method to compare expected output (5) with the result of calling the add_numbers function
    def test_add_numbers(self):
        self.assertEqual(add_numbers(), 5)

# Doctests can also be used for testing classes and their methods
class MyClass:
    """A simple class that does some stuff."""
    
    # Initializing the class with an internal variable x set to 0
    def __init__(self):
        self.x = 0
        
    # Method to increment the internal x variable by a given amount or 1 if no argument is provided
    def increment(self, amount=1):
        """Increments the internal x variable by a given amount or 1 if no argument is provided.

        >>> my_obj = MyClass()
        >>> my_obj.increment()
        >>> print(my_obj.__dict__)
        {'x': 1}
        """
        self.x += amount
        
    # Method to return a string representation of the class
    def __repr__(self):
        return f"MyClass({self.x})"

In this example, we’ve added a doctest for the `increment` method that creates an instance of our class and calls its `increment` method with no arguments. We then print out the internal dictionary to see if the x variable was updated correctly.

And there you have it! Doctests are a powerful tool in your Python testing arsenal, allowing you to add interactive tutorials for your code while also providing an easy way to test its functionality. Give them a try !

SICORPS