Python Doctest

Checking for Exceptions in Python Using `doctest`

When writing code in Python, we often need to ensure that our functions behave as expected, especially when it comes to error handling. One common scenario is testing whether a function raises an exception under certain conditions. If you’re using Python’s doctest module to conduct your tests, you might wonder: Can I check that an exception is thrown with doctest? The answer is a resounding yes! Let’s explore how to utilize doctest to verify exceptions in your Python functions.

The Problem: Testing for Exceptions

Consider a function called foo(x). This function is designed to raise an exception if its argument is less than zero. The central question here is how to write a doctest that confirms the function behaves correctly in this scenario. Specifically, when we pass in a value less than zero, we want to ensure an exception is raised to indicate that something went wrong.

Example Function

Here’s a simple version of the foo(x) function:

def foo(x):
    if x < 0:
        raise ValueError("x must be non-negative")
    return x

The Solution: Writing a `doctest`

To create a doctest that checks for exceptions, we’ll utilize the following approach. In our doctest, we can specify that we expect an exception to be raised when calling foo() with a value that should trigger the error. Here’s how to do it step by step:

Step 1: Write the Doctest

In your function’s docstring, you can add a test case demonstrating the expected exception. Here’s what that looks like:

def foo(x):
    """
    Returns x if it is non-negative.
    
    Raises:
        ValueError: If x < 0.
    
    Examples:
    >>> foo(-1)
    Traceback (most recent call last):
      ...
    ValueError: x must be non-negative
    >>> foo(3)
    3
    """
    if x < 0:
        raise ValueError("x must be non-negative")
    return x

Step 2: Run the Doctest

To run the doctest, include the following snippet at the bottom of your Python script:

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Step 3: Expected Output

When you run the script, doctest will process the examples in the docstring. If everything is functioning correctly, you’ll see no output (indicating all tests passed). If the exception is not raised as expected, doctest will report an error.

Additional Resources

For more information on how to effectively use doctest in your modules, check the official doctest module documentation.

Conclusion

Using doctest to verify that exceptions are raised correctly is not just possible; it’s straightforward! By adding a few lines in your function’s docstring, you can effectively document and test the behavior of your code, ensuring it adheres to expected patterns. Whether you’re writing new functions or testing existing ones, doctest offers a powerful way to include example-driven tests directly alongside your code. Enjoy making your code robust, and happy coding!

Checking for Exceptions in Python Using doctest