You heard me right, With doctest, you can write test cases directly in the docstring of your functions or classes. This is especially useful when working with complex algorithms or APIs where it’s not always clear how to use them without seeing some examples first.
Here’s an example: let’s say we have a function that calculates the factorial of a number using recursion. Instead of writing separate test cases in another file, we can add doctests directly inside our docstring!
# This function calculates the factorial of a number using recursion.
def factorial(n):
"""
Calculate the factorial of n (a non-negative integer) using recursion.
Args:
n (int): The number to calculate the factorial of.
Returns:
int: The factorial of n.
Raises:
ValueError: If n is a negative number.
"""
# Base case: if n is 0 or 1, return 1.
if n <= 1:
return 1
# Recursive case: calculate the product of n and the result of calling this function with n-1 as argument.
else:
return n * factorial(n-1)
# Doctest example usage:
> factorial(5) # Should return 120 (5 x 4 x 3 x 2 x 1)
"""
> factorial(-5) # Raises a ValueError since n must be non-negative.
Traceback (most recent call last):
...
ValueError: n must be non-negative!
"""
# The doctest example usage shows how to use the function and what error to expect if the argument is negative.
In this example, we’ve added doctest examples to the docstring of our `factorial()` function. The first one tests if calling `factorial(5)` returns 120 (which it should), and the second one raises a `ValueError` since n must be non-negative.
To run these tests, simply add this line at the end of your Python script:
# This script is used to run doctest examples for the factorial function.
# Importing the doctest module to use its testmod() function.
import doctest
# Defining the factorial function with a parameter n.
def factorial(n):
"""
Calculates the factorial of a given number.
>>> factorial(5)
120
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be non-negative
"""
# Checking if n is negative, if so, raise a ValueError.
if n < 0:
raise ValueError("n must be non-negative")
# Initializing the result variable to 1.
result = 1
# Looping from 1 to n+1, since range() excludes the upper bound.
for i in range(1, n+1):
# Multiplying the result by the current value of i.
result *= i
# Returning the final result.
return result
# Checking if the script is being run directly.
if __name__ == '__main__':
# Running the doctest examples for the factorial function.
doctest.testmod()
This will execute all doctests in your module (in our case, the `factorial()` function). If any tests fail, it’ll print an error message and exit with a non-zero status code.
That’s it! With Python Doctests, you can write test cases directly inside your docstrings for easy testing and documentation. It’s like having built-in unit tests without any extra setup or configuration required. Give it a try and let us know what you think in the comments below!