Unit Testing with pytest: A Complete Guide

Why Testing Matters (Beyond "It's Good Practice")

Let's be real: writing tests takes time. Why should you do it?

Confidence. When your test suite passes, you know your code behaves as intended. Months later, when you touch something, you'll know immediately if you broke it.

Regression prevention. That bug you fixed last Tuesday? Write a test for it now. It can never come back without your noticing.

Living documentation. Your tests show how your code is meant to be used. They're examples that never go out of date.

Faster refactoring. Want to rewrite a function for performance? Run the tests. If they pass, you're good. Without tests, you're flying blind.

Fewer code reviews. Tests catch entire classes of bugs before human eyes see them. Code reviews become about design, not "did you handle the None case?"

We built a full-stack inventory system in the previous article. It works, but if you tried to refactor the database layer or tweak a calculation, you'd be crossing your fingers. Tests would let you sleep at night.

Why pytest Over unittest

Before we write a single line of test code, we need to answer the question every newcomer eventually asks: Python ships with a testing module called unittest, so why does everyone use pytest instead?

The short answer is that pytest dramatically reduces the ceremony required to write a good test. With unittest, you must create a class that inherits from TestCase, call special assertion methods like self.assertEqual and self.assertRaises, and remember a specific method-naming convention. pytest throws all of that out the window. You write plain Python functions with plain assert statements, and pytest handles the rest. That reduction in boilerplate isn't just aesthetic, it lowers the activation energy for writing tests, which means you write more of them.

Beyond simplicity, pytest has a vastly superior plugin ecosystem. Tools for measuring code coverage, generating HTML reports, running tests in parallel, and integrating with hypothesis-based property testing all exist as first-class pytest plugins. unittest has none of that breadth. pytest also plays nicely with existing unittest and nose tests, so you can migrate incrementally without rewriting everything on day one.

Perhaps most importantly, pytest's failure output is genuinely useful. When an assertion fails, pytest rewrites the expression to show you the actual values on both sides of the comparison. assert result == expected becomes a clear message showing what result actually was and what you expected it to be. With unittest, you'd need to use assertEqual(result, expected) and write a custom message if you wanted that clarity. We'll dig into this in the Assertion Introspection section, but for now: pytest is the right choice for any new Python project, and it's worth migrating older projects toward it.

Installing pytest

First things first. You probably don't have pytest yet.

pip install pytest

That's it. pytest is zero-configuration by design, no massive setup, no boilerplate. You can start writing tests immediately. If you're working in a virtual environment (and you should be, see our earlier article on environments and packaging), this installs pytest only for that project, which keeps your system Python clean.

Verify the install:

pytest --version

You should see pytest 7.x.x or higher. If you see a version below 7, consider upgrading, recent versions include significant improvements to error messages, fixture handling, and parallel execution support.

Your First Test: The Arrange-Act-Assert Pattern

Let's start simple. Here's a function we want to test:

# calculator.py
def add(a, b):
    """Return the sum of two numbers."""
    return a + b

Boring, but it teaches the pattern. Here's how we test it:

# test_calculator.py
def test_add_two_positive_numbers():
    # Arrange: set up the inputs
    a = 3
    b = 5
 
    # Act: call the function
    result = add(a, b)
 
    # Assert: verify the output
    assert result == 8

Three lines, three phases. This is Arrange-Act-Assert (AAA), the backbone of every good test. The comments are here for clarity; in real tests you'll often skip them, but the mental model stays. Every test you ever write, no matter how complex, maps onto these three phases.

• Arrange: Set up your test data and environment.
• Act: Call the function or code you're testing.
• Assert: Check that the result is what you expected.

Now run it:

pytest test_calculator.py -v

The -v flag means verbose, pytest will show you each test name and whether it passed. You should see:

test_calculator.py::test_add_two_positive_numbers PASSED

Congratulations. You just wrote your first test.

How pytest Discovers Tests

pytest is magical about finding tests. Here's what it looks for:

• Files: Anything named test_*.py or *_test.py.
• Functions: Any function starting with test_.
• Classes: Any class starting with Test (with test methods inside).

When you run pytest with no arguments, it scans the current directory and subdirectories for files matching test_*.py, then runs every function starting with test_. You don't need to register anything or wire up discovery. It just works.

Testing Different Scenarios: Happy Path, Edge Cases, Errors

One test is a start, but add(3, 5) is the happy path, the obvious case. Real testing means covering edge cases and error conditions. Think of it this way: if you only test the happy path, you're only confident your code works when everything goes right. Production code encounters negative numbers, zeros, None values, empty strings, and other inputs that developers forget to consider. Your tests should model the real world, not a sanitized version of it.

# test_calculator.py (expanded)
 
def test_add_two_positive_numbers():
    assert add(3, 5) == 8
 
def test_add_negative_numbers():
    assert add(-3, -5) == -8
 
def test_add_mixed_signs():
    assert add(10, -3) == 7
 
def test_add_with_zero():
    assert add(5, 0) == 5
 
def test_add_floats():
    assert add(2.5, 3.5) == 6.0

Now run all tests:

pytest test_calculator.py -v

You get output like this:

test_calculator.py::test_add_two_positive_numbers PASSED
test_calculator.py::test_add_negative_numbers PASSED
test_calculator.py::test_add_mixed_signs PASSED
test_calculator.py::test_add_with_zero PASSED
test_calculator.py::test_add_floats PASSED

5 passed in 0.03s

See how fast that was? That's the beauty of unit tests. They're cheap to run and safe to run often. Notice that these five tests ran in 30 milliseconds. You could run this suite hundreds of times an hour as you work without it ever feeling like a burden.

Testing Exceptions: When Things Go Wrong

Not all functions return numbers. Some raise exceptions. Here's a function that validates input:

# calculator.py (continued)
 
def divide(a, b):
    """Divide a by b. Raises ValueError if b is zero."""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

Testing the happy path, division that actually works, is straightforward. But the more important test is what happens when someone passes zero as the divisor. Division by zero should be an explicit, documented failure mode, and your test should confirm that it raises exactly the right exception with exactly the right message.

How do we test that the exception is raised? With pytest.raises:

# test_calculator.py (continued)
 
import pytest
 
def test_divide_valid_numbers():
    assert divide(10, 2) == 5.0
 
def test_divide_by_zero_raises_error():
    with pytest.raises(ValueError, match="Cannot divide by zero"):
        divide(10, 0)

The pytest.raises context manager is a safety net. It says: inside this block, I expect a ValueError with this message to be raised. If it's not, the test fails. If the function raises no exception at all, the test fails. If it raises a different exception type, the test fails. Only a ValueError with the matching message causes the test to pass.

The match parameter is a regex pattern. It checks that the exception message matches. This prevents false positives, if the code raises a ValueError for the wrong reason, the test catches it. Always use match when the error message carries meaning, because "the right exception type" and "the right exception message" are two different guarantees.

Assertion Introspection: pytest's Secret Weapon

One of the biggest practical advantages of pytest over other testing frameworks is something called assertion introspection, and it kicks in automatically any time a plain assert statement fails. When you write assert result == expected and the assertion fails, pytest doesn't just tell you the assertion failed, it rewrites the expression and shows you the actual values involved. This sounds like a minor convenience until you've spent thirty minutes debugging a failing test in a framework that only says "AssertionError" and leaves the rest to you.

Here's a concrete example. Suppose you have a function that formats a price, and your test looks like this:

def test_price_formatting():
    result = format_price(9.9)
    assert result == "$9.90"

If format_price returns "$9.9" instead of "$9.90", pytest will output something like:

AssertionError: assert '$9.9' == '$9.90'
  - $9.9
  + $9.90

That diff-style output tells you exactly what went wrong without any additional debugging. Compare that to unittest, where the equivalent assertEqual call would need a custom message argument to be comparably informative. pytest's assertion introspection also works on complex data structures, dicts, lists, and sets all get formatted with clear before/after diffs when a comparison fails. For dict comparisons, pytest will show you exactly which keys differ and what the expected versus actual values were. This is genuinely valuable in real codebases where test failures need to be diagnosed quickly.

The mechanism behind this feature is a compilation hook that pytest installs at import time. When pytest loads your test files, it rewrites the bytecode of any assert statements to capture the sub-expressions and format them for display on failure. You get all of this for free just by using plain assert statements rather than the special-purpose assertion methods that unittest requires.

Useful pytest Flags: Running Tests Strategically

Running all 50 tests every time is slow. pytest gives you surgical control:

Run tests matching a pattern:

pytest -k "divide" -v

Runs only tests whose name contains "divide".

Stop on first failure:

pytest -x

Useful when you're in the middle of a debugging session.

Run tests and stop after N failures:

pytest --maxfail=3

Show detailed failure info:

pytest --tb=long

When a test fails, --tb=long shows the full traceback with local variables.

Run a specific test:

pytest test_calculator.py::test_add_negative_numbers -v

Run tests from a specific file:

pytest test_calculator.py -v

These flags are your friends. Learn them and you'll spend less time digging through test output.

Test Organization Patterns

As your test suite grows from ten tests to a hundred to a thousand, the way you organize those tests becomes as important as the tests themselves. A disorganized test suite is almost as bad as no test suite, when a test fails, you need to find it quickly, understand what it's testing, and diagnose the failure without hunting through hundreds of functions in a single file.

The most common organization pattern is to mirror your source directory structure in your test directory. If your source code lives in src/calculator.py, your tests live in tests/test_calculator.py. If you have src/inventory/item.py, your tests live in tests/inventory/test_item.py. This one-to-one correspondence makes it immediately clear where the tests for any given module live, and it scales naturally as the codebase grows.

Within a test file, grouping related tests into classes is a powerful organizational tool. A TestInventoryItem class contains all the tests for that class, a TestRestocking class contains the restock-related tests, and so on. Classes give you a namespace, allow shared setup with class-level fixtures, and make the pytest output easier to read, failures show up as TestRestocking::test_restock_invalid_amount rather than test_restock_invalid_amount, which tells you immediately which group the failure belongs to.

For cross-cutting concerns, marks are the tool of choice. Mark slow integration tests with @pytest.mark.integration and fast unit tests with @pytest.mark.unit, then configure your CI pipeline to run unit tests on every commit and integration tests only on pull requests. This keeps your fast feedback loop fast. A project with good test organization makes it easy to answer the question "which tests are relevant to the change I just made?" without reading every test in the suite.

Grouping Tests with Classes and Marks

As your test suite grows, you'll want organization. pytest offers two approaches:

Test Classes

Group related tests into a class:

# test_calculator.py (refactored)
 
class TestAddition:
    """Tests for the add function."""
 
    def test_positive_numbers(self):
        assert add(3, 5) == 8
 
    def test_negative_numbers(self):
        assert add(-3, -5) == -8
 
    def test_mixed_signs(self):
        assert add(10, -3) == 7
 
class TestDivision:
    """Tests for the divide function."""
 
    def test_valid_division(self):
        assert divide(10, 2) == 5.0
 
    def test_division_by_zero(self):
        with pytest.raises(ValueError):
            divide(10, 0)

Now you can run just the addition tests:

pytest test_calculator.py::TestAddition -v

This is exactly the kind of surgical targeting that makes a large test suite manageable. Instead of waiting for all 200 tests to run while you're iterating on the addition logic, you can run just the 15 tests that cover that code path.

Test Marks

Mark tests with decorators to organize them logically:

import pytest
 
@pytest.mark.slow
def test_expensive_computation():
    result = some_heavy_calculation()
    assert result > 0
 
@pytest.mark.integration
def test_database_connection():
    db = connect_to_database()
    assert db.is_connected()
 
@pytest.mark.unit
def test_simple_arithmetic():
    assert add(1, 1) == 2

Then run only certain marks:

pytest -m "unit" -v          # Run only unit tests
pytest -m "not slow" -v      # Run everything except slow tests

This is essential for large projects. You want a fast suite of unit tests that runs in seconds, and a slower integration test suite that runs less frequently. Register your custom marks in a pytest.ini or pyproject.toml to avoid warnings about unknown marks, pytest will tell you exactly how to do this when it detects an unregistered mark.

Test-Driven Development: The Complete Workflow

Here's where testing transforms your productivity. Instead of writing code then testing it, we flip the order: write the test first, then write code to make it pass.

The TDD Cycle

1. Red: Write a test that fails (because the feature doesn't exist yet).
2. Green: Write the minimum code to make it pass.
3. Refactor: Clean up, improve, but keep tests passing.

Repeat.

A Worked Example: Building a User Validator

Imagine we need a function that validates usernames. Requirements:

• Username must be 3-20 characters
• Must contain only letters, numbers, underscores
• Must start with a letter

Here's the TDD approach:

Step 1: Write the test (it fails)

# test_validator.py
 
import pytest
from validator import validate_username
 
def test_valid_username():
    assert validate_username("john_doe") == True
 
def test_username_too_short():
    assert validate_username("ab") == False
 
def test_username_too_long():
    assert validate_username("a" * 21) == False
 
def test_username_with_invalid_chars():
    assert validate_username("john-doe") == False
 
def test_username_starts_with_number():
    assert validate_username("1john") == False

Run pytest:

pytest test_validator.py -v

All tests fail. That's okay, we haven't written the function yet. This is Red. In TDD, this step is actually meaningful: you're confirming that your tests can fail, which means they have the ability to tell you when things go wrong. A test that can never fail is worthless.

Step 2: Write minimal code to pass (Green)

# validator.py
 
import re
 
def validate_username(username):
    """Validate a username according to requirements."""
    # Must be 3-20 characters
    if len(username) < 3 or len(username) > 20:
        return False
 
    # Must start with a letter
    if not username[0].isalpha():
        return False
 
    # Must contain only letters, numbers, underscores
    if not re.match(r"^[a-zA-Z][a-zA-Z0-9_]*$", username):
        return False
 
    return True

Run pytest again:

pytest test_validator.py -v

All tests pass. This is Green. Notice that we didn't write the cleanest possible implementation, we wrote the simplest one that satisfies the tests. That's intentional. Getting to green fast tells you your tests are correctly specified.

Step 3: Refactor (optional, but keep tests green)

The current code works, but we can tighten it with a single regex:

import re
 
def validate_username(username):
    """Validate a username according to requirements."""
    pattern = r"^[a-zA-Z][a-zA-Z0-9_]{2,19}$"
    return bool(re.match(pattern, username))

Run tests, still passing. This is Refactor. The key insight here is that refactoring with a test suite in place is fundamentally different from refactoring without one. When your tests pass after a refactor, you have evidence that the behavior is unchanged. Without tests, a refactor is just optimism.

This process feels backwards at first, but it's powerful. You define what success looks like before you write the code. There's no vague "make this work somehow." The tests are your spec.

What to Test: A Practical Framework

Not everything needs a test. Testing is about managing risk. Ask yourself:

• Does this code have logic? If it's just pass-through or wrapper code, skip it.
• Could this code have edge cases or fail? If yes, test it.
• Is this code used by other code? If it's a utility, test it hard.
• Is this a common source of bugs? Definitely test it.
• Could this cause data loss or security issues? Test it thoroughly.

For the inventory system from the previous article, what would you test?

• The calculation of total inventory value: Yes. Math can be tricky, and it directly affects business logic.
• The database connection setup: No (or minimal). That's integration testing, and it's slow. We'll cover that later.
• API endpoints that call business logic: Yes. But test the logic itself, not the HTTP machinery.
• Input validation: Absolutely. This is a goldmine for bugs.
• Edge cases like zero inventory, negative prices: Yes. These will happen in production.

Here's a rule of thumb: test the behavior, not the implementation. If your function calculates a discount, test that it calculates correctly, not that it uses a specific formula internally.

Common Testing Mistakes

Even developers who understand testing in principle fall into predictable traps that make their test suites less useful or actively misleading. Knowing these patterns in advance will save you from discovering them the hard way in production.

The first and most common mistake is writing tests that are coupled to the implementation rather than the behavior. If your test asserts that a function calls a specific helper method, or that an internal variable has a specific intermediate value, you've written a test that breaks every time you refactor, even when the external behavior remains correct. These tests create friction without providing safety. Test what the function returns or what side effects it produces, not how it produces them.

The second common mistake is test interdependence, writing tests that rely on side effects from other tests to set up their preconditions. If test_sell_inventory relies on test_add_inventory having run first and populated some shared state, you have a fragile test suite that only works when tests run in a specific order. pytest supports randomized test ordering for exactly this reason. Every test should be fully self-contained: it sets up everything it needs in its Arrange phase and tears it down (or doesn't care) afterward.

The third mistake is testing the framework instead of your code. If you're testing that a Django model saves to the database, you're partially testing Django's ORM, not your business logic. Extract your business logic into plain Python functions that can be tested without any framework dependency, then write a separate, thinner integration test that confirms the wiring between your logic and the framework is correct. This separation produces a fast, reliable unit test suite and a smaller, slower integration test suite.

The fourth mistake is writing assertions that can never fail. assert len(results) >= 0 is always true. assert result is not None is true unless the function explicitly returns None. Think carefully about what your assertion is actually checking, and ask yourself: if someone introduced a bug into this function tomorrow, would my test catch it?

A Real-World Example: Testing the Inventory System

Let's bring this together with a simplified piece of the inventory system:

# inventory.py
 
class InventoryItem:
    def __init__(self, name, quantity, price):
        self.name = name
        self.quantity = quantity
        self.price = price
 
    def restock(self, amount):
        """Add items to inventory."""
        if amount <= 0:
            raise ValueError("Restock amount must be positive")
        self.quantity += amount
 
    def sell(self, amount):
        """Remove items from inventory."""
        if amount <= 0:
            raise ValueError("Sale amount must be positive")
        if amount > self.quantity:
            raise ValueError("Insufficient inventory")
        self.quantity -= amount
 
    def total_value(self):
        """Calculate the total value of this item in inventory."""
        return self.quantity * self.price

This class is a good candidate for thorough testing. It has business logic (the value calculation), boundary conditions (you can't sell more than you have), and error paths (invalid amounts). Each of those categories deserves its own tests, and we want to make sure they all interact correctly.

Here's the full test suite:

# test_inventory.py
 
import pytest
from inventory import InventoryItem
 
class TestInventoryItemCreation:
    def test_create_item(self):
        item = InventoryItem("Widget", 10, 5.0)
        assert item.name == "Widget"
        assert item.quantity == 10
        assert item.price == 5.0
 
class TestRestocking:
    def test_restock_valid_amount(self):
        item = InventoryItem("Widget", 10, 5.0)
        item.restock(5)
        assert item.quantity == 15
 
    def test_restock_invalid_amount(self):
        item = InventoryItem("Widget", 10, 5.0)
        with pytest.raises(ValueError, match="must be positive"):
            item.restock(-5)
 
    def test_restock_zero(self):
        item = InventoryItem("Widget", 10, 5.0)
        with pytest.raises(ValueError):
            item.restock(0)
 
class TestSelling:
    def test_sell_valid_amount(self):
        item = InventoryItem("Widget", 10, 5.0)
        item.sell(3)
        assert item.quantity == 7
 
    def test_sell_all_inventory(self):
        item = InventoryItem("Widget", 10, 5.0)
        item.sell(10)
        assert item.quantity == 0
 
    def test_sell_insufficient_inventory(self):
        item = InventoryItem("Widget", 10, 5.0)
        with pytest.raises(ValueError, match="Insufficient"):
            item.sell(15)
 
    def test_sell_invalid_amount(self):
        item = InventoryItem("Widget", 10, 5.0)
        with pytest.raises(ValueError, match="must be positive"):
            item.sell(-5)
 
class TestTotalValue:
    def test_total_value_calculation(self):
        item = InventoryItem("Widget", 10, 5.0)
        assert item.total_value() == 50.0
 
    def test_total_value_after_transactions(self):
        item = InventoryItem("Widget", 10, 5.0)
        item.restock(5)
        item.sell(3)
        assert item.total_value() == 12 * 5.0  # 60.0
 
    def test_total_value_with_zero_inventory(self):
        item = InventoryItem("Widget", 0, 5.0)
        assert item.total_value() == 0.0

Run the suite:

pytest test_inventory.py -v

You get comprehensive coverage of happy paths, edge cases, and error conditions. If someone breaks the sell method next month, these tests will scream. If someone refactors the calculation logic, they'll know immediately if they broke something. Notice also how the test suite reads like a specification of the class's behavior, the class names (TestRestocking, TestSelling, TestTotalValue) tell you what capability is being tested, and the method names tell you the specific scenario.

Running Your Tests Continuously

As your codebase grows, you'll want tests running constantly, on every save, before every commit, in CI/CD pipelines.

For now, here's a simple habit: before committing code, run:

pytest

No flags. Just pytest. It finds all tests, runs them, and gives you a summary. Make it part of your workflow.

Summary: You're Ready

You now understand:

• Why testing matters: confidence, regression prevention, living documentation.
• Why pytest wins: less boilerplate, better output, superior plugin ecosystem.
• pytest basics: test discovery, naming conventions, how pytest finds and runs tests.
• Arrange-Act-Assert: the pattern that structures every good test.
• Assertion introspection: how pytest rewrites failed assertions to show you exactly what went wrong.
• Running tests strategically: using flags like -k, -x, and -v.
• Testing exceptions: using pytest.raises to verify error handling.
• Organizing tests: classes, marks, and directory structure for manageable suites.
• Test-driven development: the red-green-refactor cycle that shapes better code.
• What to test: business logic, edge cases, error paths, not implementation details.
• Common mistakes: coupled tests, interdependent tests, and assertions that can't fail.

The inventory system you built in the last article? It works now. But add tests, and it becomes maintainable. You can refactor confidently. You can onboard new team members who understand exactly how the system should behave by reading the test suite rather than the implementation. Tests are executable documentation that never drifts out of date.

There's a mindset shift that happens when you write tests regularly. You stop thinking of code as "done" when it runs without crashing and start thinking of it as "done" when the behavior is specified and verified. That shift changes how you write code in the first place, you write smaller functions with clearer responsibilities because small, focused functions are easier to test. You think about error cases upfront because you know you'll be writing tests for them. Testing and good design reinforce each other, and the combination produces code that's genuinely easier to work with over time.

Testing isn't extra work. It's insurance that saves you hundreds of hours debugging in production.

Write your first test. Run it. Watch it fail. Fix the code. Watch it pass. You'll see what we mean.

In the next article, we'll level up to pytest fixtures and parametrization, patterns that make testing at scale practical and powerful. Fixtures let you share setup code across tests without duplicating it, and parametrization lets you run the same test logic across dozens of input cases with a single decorator. If you found this article useful, those two features will double your testing productivity overnight.

Until then, test fearlessly.