Testing custom exceptions in PyTest - Deep Dive

Overview - Testing custom exceptions

What is it?

Testing custom exceptions means checking that your program correctly raises special error messages you create. These custom exceptions help your code explain problems clearly when something goes wrong. By writing tests for them, you make sure your program behaves as expected in error situations. This helps catch bugs early and improves code reliability.

Why it matters

Without testing custom exceptions, errors might go unnoticed or be misunderstood, causing bigger problems later. Imagine a safety alarm that never sounds when danger appears. Testing ensures your program signals problems clearly and stops bad actions before they cause harm. This builds trust in your software and saves time fixing hidden bugs.

Where it fits

Before testing custom exceptions, you should know basic Python programming and how to write simple tests with pytest. After this, you can learn about advanced error handling, test fixtures, and mocking to test more complex scenarios.

Mental Model

Core Idea

Testing custom exceptions confirms your program raises the right errors at the right time to handle unexpected situations safely.

Think of it like...

It's like checking that a fire alarm sounds only when there is smoke, not when you burn toast. You want to be sure the alarm works correctly to warn you of real danger.

┌─────────────────────────────┐
│       Function runs          │
├─────────────┬───────────────┤
│ Normal case │ Error case    │
│             │               │
│ Returns     │ Raises custom │
│ result      │ exception     │
└─────────────┴───────────────┘
          │
          ▼
┌─────────────────────────────┐
│ pytest test checks if error  │
│ is raised when expected      │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What are custom exceptions

Concept: Custom exceptions are special error types you create to describe specific problems in your program.

In Python, you create a custom exception by making a new class that inherits from Exception. For example: class MyError(Exception): pass This means MyError is a new kind of error you can raise when something specific goes wrong.

Result

You have a new error type that you can use to signal special problems in your code.

Understanding how to create custom exceptions lets you communicate errors clearly and handle them separately from general errors.

2

Foundation

How to raise custom exceptions

Concept: You use the raise statement to trigger your custom exception when a problem happens.

Example: def divide(a, b): if b == 0: raise MyError('Cannot divide by zero') return a / b This stops the function and signals the error with your message.

Result

If b is zero, the function raises MyError instead of returning a result.

Knowing when and how to raise custom exceptions helps your program stop bad actions and explain why.

3

Intermediate

Basic pytest exception testing

🤔Before reading on: do you think pytest can check if any exception is raised, or only built-in exceptions? Commit to your answer.

Concept: pytest can check if your code raises any exception, including custom ones, using the pytest.raises context manager.

Example test: import pytest def test_divide_by_zero(): with pytest.raises(MyError): divide(10, 0) This test passes only if divide(10, 0) raises MyError.

Result

Test passes if MyError is raised; fails otherwise.

Using pytest.raises lets you confirm your code signals errors exactly as you designed.

4

Intermediate

Checking exception messages

🤔Before reading on: do you think pytest.raises can check the error message text automatically? Commit to your answer.

Concept: You can capture the raised exception and check its message to ensure it contains the right information.

Example: with pytest.raises(MyError) as exc_info: divide(10, 0) assert 'divide by zero' in str(exc_info.value) This confirms the error message is correct.

Result

Test passes only if the exception message contains the expected text.

Verifying error messages ensures your exceptions communicate the exact problem clearly.

5

Advanced

Testing exceptions in complex flows

🤔Before reading on: do you think testing exceptions in functions that call others is straightforward or tricky? Commit to your answer.

Concept: When exceptions happen deep inside multiple function calls, tests must trigger the right conditions and catch the exceptions properly.

Example: def process(data): if not data: raise MyError('No data') return divide(10, data) Test: with pytest.raises(MyError): process(0) This tests exceptions raised indirectly through nested calls.

Result

Test passes if MyError is raised anywhere inside process.

Understanding exception flow through multiple calls helps you write tests that catch errors no matter where they happen.

6

Expert

Avoiding false positives in exception tests

🤔Before reading on: do you think any exception raised inside pytest.raises block counts as a pass? Commit to your answer.

Concept: pytest.raises passes if any exception of the expected type is raised, even if it happens earlier than intended. You must write tests carefully to avoid false positives.

Example pitfall: with pytest.raises(MyError): setup() divide(10, 0) If setup() raises MyError, test passes but misses the real test target. Better: with pytest.raises(MyError): divide(10, 0) This isolates the code that should raise the error.

Result

Tests become more precise and reliable, avoiding false passes.

Knowing how pytest.raises works internally prevents tests that pass for the wrong reasons, improving test quality.

Under the Hood

When pytest runs a test with pytest.raises, it temporarily watches for exceptions inside the block. If the expected exception type occurs, pytest catches it and marks the test as passed. If no exception or a different type occurs, the test fails. The exception object is stored so you can inspect its message or attributes.

Why designed this way?

This design lets tests focus on error conditions without crashing the whole test run. It provides a clean, readable way to check errors, improving test clarity and maintainability. Alternatives like try-except blocks are more verbose and error-prone.

┌───────────────────────────────┐
│ pytest test starts             │
├───────────────────────────────┤
│ Enter pytest.raises context    │
│ ┌───────────────────────────┐ │
│ │ Run code block             │ │
│ │ ┌───────────────────────┐ │ │
│ │ │ Exception raised?      │─┤─┤
│ │ └───────────────────────┘ │ │
│ │       Yes                 │ │
│ │       │                  │ │
│ │       ▼                  │ │
│ │ Catch exception if type matches │
│ │ Mark test passed          │ │
│ │ Store exception info      │ │
│ └───────────────────────────┘ │
│ Exit pytest.raises context     │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does pytest.raises catch exceptions raised outside its block? Commit to yes or no.

Common Belief: pytest.raises catches any exception raised during the test function, no matter where.

Reality: pytest.raises only catches exceptions raised inside its own with-block, not outside.

Why it matters: If you expect pytest.raises to catch exceptions outside its block, your tests may miss real errors or give false passes.

Quick: Do you think pytest.raises checks the exception message automatically? Commit to yes or no.

Common Belief: pytest.raises automatically verifies the exception message matches the expected error.

Reality: pytest.raises only checks the exception type; you must manually assert the message if needed.

Why it matters: Assuming automatic message checking can let wrong error messages slip through tests unnoticed.

Quick: Can pytest.raises detect if the wrong exception type is raised? Commit to yes or no.

Common Belief: pytest.raises passes the test if any exception is raised, regardless of type.

Reality: pytest.raises only passes if the exact expected exception type (or subclass) is raised.

Why it matters: This prevents tests from passing due to unrelated errors, ensuring precise error handling.

Quick: Do you think catching exceptions with pytest.raises can hide bugs? Commit to yes or no.

Common Belief: Using pytest.raises always improves test quality and never hides bugs.

Reality: Improper use of pytest.raises can hide bugs if the block is too large or includes setup code that raises exceptions.

Why it matters: Tests may pass incorrectly, giving false confidence and letting bugs reach production.

Expert Zone

1

pytest.raises can be used as a context manager or a function decorator, each with subtle differences in scope and readability.

2

Custom exceptions can carry extra data attributes; testing these requires accessing the exception instance via exc_info.value.

3

Stacked or nested exceptions require careful test design to ensure the correct exception is caught and verified.

When NOT to use

Avoid using pytest.raises for testing exceptions in asynchronous code; instead, use pytest-asyncio's async support or other async test tools. Also, do not use pytest.raises to catch exceptions that should be handled inside the code logic rather than tested externally.

Production Patterns

In real projects, tests for custom exceptions often include checking error messages, error codes, and side effects like logging. Teams use parameterized tests to cover many error cases efficiently. Exception tests are integrated into CI pipelines to catch regressions early.

Connections

Error handling

builds-on

Testing custom exceptions deepens understanding of error handling by verifying not just that errors occur, but that they are the right errors with clear messages.

Defensive programming

supports

Testing exceptions supports defensive programming by ensuring your code fails safely and predictably under bad inputs or states.

Medical diagnostics

analogy in process

Just like doctors test for specific symptoms to diagnose diseases accurately, testing custom exceptions checks for precise error signals to diagnose software problems.

Common Pitfalls

#1 Catching exceptions outside the pytest.raises block

Wrong approach:

def test_error():
with pytest.raises(MyError):
setup()
divide(10, 0)

Correct approach:

def test_error():
setup()
with pytest.raises(MyError):
divide(10, 0)

Root cause:

Misunderstanding that pytest.raises only watches exceptions inside its block, so exceptions raised earlier are missed.

#2 Not checking exception message content

Wrong approach:

with pytest.raises(MyError):
divide(10, 0)

Correct approach:

with pytest.raises(MyError) as exc_info:
divide(10, 0)
assert 'divide by zero' in str(exc_info.value)

Root cause:

Assuming that raising the correct exception type is enough without verifying the error message.

#3 Using too large code block inside pytest.raises

Wrong approach:

with pytest.raises(MyError):
setup()
divide(10, 0)

Correct approach:

setup()
with pytest.raises(MyError):
divide(10, 0)

Root cause:

Including unrelated code in the block can cause false positives if that code raises the exception.

Key Takeaways

Custom exceptions let your program signal specific problems clearly and safely.

pytest.raises is the main tool to test that your code raises these exceptions correctly.

Always check both the exception type and its message to ensure precise error handling.

Write tests that isolate the code raising exceptions to avoid false positives.

Understanding how pytest.raises works internally helps you write reliable and maintainable tests.