Testing Exceptions — pytest.raises

The Basics of Exception Assertion

When writing robust software, ensuring that your functions fail gracefully is just as critical as ensuring they succeed under normal conditions. The `pytest.raises` context manager provides a declarative way to verify that a block of code execution triggers a specific exception type. By wrapping the code that should trigger an error within this block, the test will pass only if that specific exception is raised. If the code completes without an exception, or if it raises a different type of error, the test fails. This works because pytest intercepts the exception signal internally; if the signal matches the provided exception type, it suppresses the error, allowing the test to continue. This pattern is fundamental to testing validation logic where you deliberately pass incorrect arguments to ensure your system identifies them correctly instead of failing silently or producing corrupted state.

import pytest

def divide(a, b):
    if b == 0:
        # We expect a ZeroDivisionError here
        raise ZeroDivisionError("Cannot divide by zero")
    return a / b

def test_divide_by_zero():
    # Assert that calling divide with 0 raises the error
    with pytest.raises(ZeroDivisionError):
        divide(10, 0)

Validating Exception Messages

Simply checking the type of an exception is often insufficient, as many functions might raise the same type of error for different reasons. To make your tests more precise, you should use the match argument within the `pytest.raises` constructor. This argument accepts a string or a regular expression that is checked against the exception object's string representation. By verifying the error message, you ensure that your code is failing for the specific, intended reason rather than some unexpected side effect. This is particularly important for library code where providing helpful, accurate error messages to the user is a requirement. If the exception is raised but the message does not match your regex, the test will fail, alerting you that your error handling might be reporting the wrong issue to the end user or that the implementation has changed.

import pytest

def set_age(age):
    if age < 0:
        raise ValueError(f"Age {age} is invalid")
    return age

def test_set_age_invalid():
    # Validate the message matches the expected format
    with pytest.raises(ValueError, match=r"Age -5 is invalid"):
        set_age(-5)

Extracting the Exception Object

Sometimes you need to inspect the attributes of the caught exception to perform deeper validation beyond the type and the message. By using the 'as' syntax, you can capture the exception instance into a variable within the context manager's scope. This exception info object, which is of type ExceptionInfo, contains metadata about the captured error, including the message, the traceback, and the raw exception object. This is useful when you want to access custom attributes of a user-defined exception or check properties that are set during the exception's initialization. Once captured, the exception info allows you to assert on any property of the exception object, providing granular control over your test verification. This is especially powerful when dealing with complex custom error classes that encapsulate specific state information relevant to the failure of the operation.

import pytest

class CustomError(Exception):
    def __init__(self, code):
        self.code = code

def trigger():
    raise CustomError(404)

def test_custom_exception():
    # Capture the exception object to inspect its properties
    with pytest.raises(CustomError) as excinfo:
        trigger()
    assert excinfo.value.code == 404

Handling Exceptions in Setup and Teardown

While `pytest.raises` is commonly used within test functions, its behavior is fundamentally tied to how pytest manages the call stack. Because it works as a context manager, it must be placed directly inside the function scope where the error is expected to occur. You cannot easily wrap external setup or teardown fixtures in a traditional block within a test; instead, if you are testing that a fixture itself raises an error, you must utilize the pytest mechanism in a way that respects the scope. If an error is expected to occur before your test even begins, you might need to reconsider your test structure or use internal logic within the setup. However, for most functional testing, keeping the `pytest.raises` block tightly scoped around the operation under test is the best practice to avoid false positives and maintain test readability.

import pytest

def setup_database():
    # If connection fails during setup
    raise ConnectionError("Failed to connect")

def test_fixture_logic():
    # Assert the fixture-like behavior fails correctly
    with pytest.raises(ConnectionError):
        setup_database()

Avoiding Common Pitfalls

A common mistake when using `pytest.raises` is wrapping too much code inside the context manager. If you place code that does not throw an exception inside the block, and then something late in that block throws an unexpected exception, you might accidentally mask bugs or misunderstand which line actually triggered the failure. It is essential to keep the code block inside the context manager as small and focused as possible, ideally containing only the single function call that is expected to fail. Additionally, always ensure that your assertions regarding exceptions are specific; catching broad exceptions like 'Exception' or 'BaseException' can lead to brittle tests that pass when they should fail because they accidentally swallowed an unexpected, unrelated error. By being precise, you guarantee that your tests are verifying the specific contract of your function.

import pytest

def risky_process(x):
    # Only this line should be in the context
    return 10 / x

def test_risky_process_isolated():
    # Precise scoping ensures clarity in failure
    with pytest.raises(ZeroDivisionError):
        risky_process(0)

Interview questions

All pytest & Testing interview questions →

Check yourself

Take the full pytest & Testing quiz →