Introduction to Testing and pytest

The Anatomy of a Test Function

At its core, a test in pytest is simply a function that starts with the prefix 'test_'. The framework uses discovery mechanisms to scan your file system for these functions and execute them automatically. When pytest runs, it monitors the 'assert' statements within these functions. Unlike traditional programming where an assertion might cause the program to crash, pytest intercepts these assertion failures, records them, and continues to the next test. The magic lies in how pytest introspects the state of your variables during an assertion failure. It doesn't just tell you that a test failed; it breaks down the expression to show you exactly which components contributed to the failure. By writing standard functions, you keep your testing logic decoupled from complex frameworks, allowing you to focus on verifying the logical correctness of your domain objects rather than fighting against an obscure testing API or rigid class-based structures.

# File: test_math.py

def add(a, b):
    return a + b

def test_add_two_numbers():
    # The assert keyword is the fundamental building block
    # pytest inspects this and provides a detailed error report on failure
    result = add(2, 3)
    assert result == 5, "Adding 2 and 3 should result in 5"

Understanding Test Discovery

Pytest is designed to be 'zero-configuration' by default, which relies heavily on a strict set of discovery rules. When you trigger the test runner from your terminal, it recursively searches through your project directory for files that start with 'test_' or end in '_test.py'. Inside these modules, it identifies functions with the 'test_' prefix and methods within classes prefixed with 'Test'. This convention-over-configuration approach is crucial because it ensures that tests remain organized in a predictable hierarchy that mirrors your source code structure. By adhering to these naming conventions, you allow the framework to map your test suite automatically without manual registry updates. This reduces the friction of adding new tests to the codebase, encouraging a workflow where small, isolated tests are written alongside new features, ensuring that the test suite scales linearly with the project's complexity while remaining easy to navigate for team members.

# Directory structure: 
# /project
#   /src
#     logic.py
#   /tests
#     test_logic.py

# Inside test_logic.py, discovery happens automatically.
# Running 'pytest' in the root triggers these files.

Handling Exceptions with pytest.raises

Robust software must handle failure states just as gracefully as success scenarios. Sometimes, the correct behavior for a function is to raise an error when given invalid input. Testing these scenarios requires a context manager, 'pytest.raises', which tells the framework that you expect a specific exception to occur within a designated block of code. This is a critical pattern because it allows you to verify not just the existence of an error, but the specific type of error, ensuring that your error handling remains predictable. If an error of the specified type is not raised, the test will fail, alerting you that the function is either too permissive or has been modified. By explicitly declaring what should fail, you create a safety net for edge cases, ensuring that internal failures don't lead to silent data corruption or undefined behavior in production environments.

import pytest

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

def test_divide_by_zero_raises_error():
    # We expect a ValueError. If the function succeeds, the test fails.
    with pytest.raises(ValueError, match="Cannot divide by zero"):
        divide(10, 0)

Sharing Setup Logic with Fixtures

As your test suite grows, you will inevitably find that many tests require the same setup, such as creating a database connection, initializing a temporary file, or mocking a network call. Copying this setup code into every test function creates 'boilerplate' that is hard to maintain and prone to error. Pytest solves this with the 'fixture' decorator. A fixture is a function that performs setup, yields a value, and then handles cleanup. Because fixtures are injected into tests by name, you can declare your dependencies explicitly in the function signature. This inversion of control is powerful; it allows the test runner to manage the lifecycle of your resources. Furthermore, fixtures can depend on other fixtures, building a sophisticated dependency graph that ensures your test environment is initialized exactly as needed, every single time, without duplicating resource allocation logic across your codebase.

import pytest

@pytest.fixture
def sample_data():
    # Setup: prepare resources
    data = {"user": "admin", "permissions": ["read", "write"]}
    return data

def test_user_permissions(sample_data):
    # The fixture is passed as an argument automatically
    assert "admin" in sample_data["user"]
    assert "write" in sample_data["permissions"]

Parameterizing Tests for Coverage

One of the most common mistakes in testing is writing a single, complex test function that tries to cover too many inputs using loops. When a loop fails, it is often difficult to determine exactly which input caused the issue without adding complex diagnostic logging. Pytest addresses this with 'pytest.mark.parametrize', which allows you to run the same test logic against multiple sets of data. Each set of inputs is executed as an independent, isolated test case. If one set fails, the others will still run, and the report will clearly indicate exactly which parameters caused the failure. This technique drastically increases your test coverage while keeping your code clean and readable. By separating your test data from the test logic, you create a maintainable suite where adding a new edge case is as simple as adding a single line of data to a list, rather than writing a new test function.

import pytest

@pytest.mark.parametrize("input_a, input_b, expected", [
    (1, 2, 3),
    (5, 5, 10),
    (0, 0, 0)
])
def test_add_multiple_cases(input_a, input_b, expected):
    # This function runs 3 times, once for each tuple provided above.
    assert input_a + input_b == expected

Interview questions

All pytest & Testing interview questions →

Check yourself

Take the full pytest & Testing quiz →