Skip to content
Tutorials Center
My learning

Topics

Lesson 96 of 149 ยท Beyond the Basics

Testing with pytest

Learn pytest from the ground up. Write plain assert tests, share setup with fixtures, run many cases with parametrize, mock dependencies, and measure coverage.

The unittest lesson showed the framework built into Python. Most Python projects, however, use pytest: a third-party test runner that lets you write tests as plain functions with plain assert statements, and gives you detailed failure reports, reusable setup called fixtures, and a one-line way to run the same test with many inputs. It also runs unittest tests, so you can adopt it gradually.

In this lesson you will write and run pytest tests, use fixtures for setup and cleanup, test exceptions and floats, run one test over many inputs with parametrize, replace slow or unpredictable dependencies with mocks, and measure test coverage. pytest itself needs to be installed on your computer, so its commands and output are shown in read-only blocks (all of them were run with pytest 9). The runnable editors on this page use the standard library's unittest.mock, which pytest tests use too.

Installing and running pytest

Install it in a virtual environment and run it from your project folder:

TEXT
python -m pip install pytest
python -m pytest          # discover and run everything
python -m pytest -v       # one line per test
python -m pytest -q       # quiet

pytest finds files named test_*.py (or *_test.py), and inside them functions named test_* and methods named test_* in classes named Test*. No base class is needed. Let us test this small shopping cart, saved as cart.py:

Python
class Cart:
    def __init__(self):
        self.items = {}                      # name -> (price, quantity)

    def add(self, name, price, qty=1):
        if qty < 1:
            raise ValueError("qty must be at least 1")
        if name in self.items:
            old_price, old_qty = self.items[name]
            self.items[name] = (old_price, old_qty + qty)
        else:
            self.items[name] = (price, qty)

    def total(self):
        return sum(price * qty for price, qty in self.items.values())

    def discount(self, percent):
        if not 0 <= percent <= 100:
            raise ValueError("percent must be between 0 and 100")
        return round(self.total() * (100 - percent) / 100, 2)

Here is a first test file, test_cart.py. A test is just a function, and it passes if it finishes without raising an exception:

Python
from cart import Cart


def test_empty_cart_costs_nothing():
    assert Cart().total() == 0


def test_total_multiplies_price_by_quantity():
    cart = Cart()
    cart.add("pen", 2.50, 4)
    assert cart.total() == 10.0

pytest rewrites assert statements so a failure explains itself. If the expected total were wrong, you would see the actual value, the expression that produced it and the comparison, not just AssertionError:

TEXT
    def test_total(cart):
>       assert cart.total() == 23.0
E       assert 22.0 == 23.0
E        +  where 22.0 = total()

test_cart.py:14: AssertionError
=========================== short test summary info ===========================
FAILED test_cart.py::test_total - assert 22.0 == 23.0
1 failed, 9 passed in 0.30s

For lists, dicts and long strings pytest even prints a diff of what differs. The one habit to keep: use the real comparison (==, in, is None) rather than helper methods; pytest handles the explanation.

Fixtures: reusable setup

Many tests need the same starting objects. A fixture is a function decorated with @pytest.fixture that builds one. A test asks for it simply by naming it as a parameter, and pytest calls the fixture and passes in the result. Each test gets a fresh value by default, so tests cannot affect each other. (Decorators are explained in Decorators.)

Python
import pytest
from cart import Cart


@pytest.fixture
def cart():
    c = Cart()
    c.add("pen", 2.50, 4)
    c.add("book", 12.00)
    return c


def test_total(cart):
    assert cart.total() == 22.0


def test_adding_same_item_merges_quantity(cart):
    cart.add("pen", 2.50, 2)
    assert cart.items["pen"] == (2.50, 6)

A fixture can also clean up. Use yield instead of return: everything before yield is setup, the yielded value goes to the test, and everything after runs once the test finishes, even if it failed.

sequenceDiagram
    participant R as pytest
    participant F as fixture
    participant T as test
    R->>F: call fixture
    F-->>R: setup done, yield value
    R->>T: run test with value
    T-->>R: pass or fail
    R->>F: resume after yield
    F-->>R: teardown done

A yield fixture runs its setup, hands the value to the test, then resumes for cleanup whatever the test result was.

Under the hood a yield fixture works like a generator wrapped in a context manager (see Context Managers). This runnable stand-in shows the order of events without needing pytest:

Python How a yield fixture behaves (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that teardown runs in both cases, and that each test received a fresh connection. Real pytest adds three things on top: it finds fixtures by parameter name, it can scope them, and it lets you share them between files.

  • Scope. @pytest.fixture(scope="module") creates the value once per file; "session" once per run. Use wider scopes for expensive setup (a database connection), but only for objects tests do not modify.
  • conftest.py. Fixtures placed in a file named conftest.py are available to every test in that folder and below, with no import.
  • Built-in fixtures. pytest provides several. tmp_path is a fresh temporary directory (a pathlib.Path), capsys captures what the code prints, and monkeypatch temporarily changes attributes, dictionaries and environment variables.
Python
def test_writes_report(tmp_path):
    target = tmp_path / "report.txt"
    target.write_text("hello\n")
    assert target.read_text() == "hello\n"


def test_greeting_prints(capsys):
    print("hi there")
    captured = capsys.readouterr()
    assert captured.out == "hi there\n"


def test_reads_environment(monkeypatch):
    monkeypatch.setenv("APP_MODE", "test")
    import os
    assert os.environ["APP_MODE"] == "test"

monkeypatch undoes every change automatically after the test, so nothing leaks into the next one.

Testing exceptions and floats

To assert that code raises, use pytest.raises as a context manager. The optional match is a regular expression searched in the error message (see Regular Expressions):

Python
def test_bad_quantity_raises(cart):
    with pytest.raises(ValueError, match="at least 1"):
        cart.add("cap", 5, 0)

The test fails if no exception, or a different one, is raised. For floats, never compare with ==, because 0.1 + 0.2 is not exactly 0.3. Use pytest.approx:

Python
def test_floats_need_approx():
    assert 0.1 + 0.2 == pytest.approx(0.3)

Parametrize: one test, many inputs

Writing a separate test for each input is repetitive. @pytest.mark.parametrize runs the same test once per set of arguments, and reports each as its own test:

Python
@pytest.mark.parametrize(
    "percent, expected",
    [(0, 22.0), (50, 11.0), (100, 0.0), (10, 19.8)],
)
def test_discount(cart, percent, expected):
    assert cart.discount(percent) == expected


@pytest.mark.parametrize("percent", [-1, 101])
def test_discount_out_of_range(cart, percent):
    with pytest.raises(ValueError):
        cart.discount(percent)

Running python -m pytest -v shows one line per case, with the values in the name, which makes a failing case easy to spot:

TEXT
test_cart.py::test_discount[0-22.0] PASSED
test_cart.py::test_discount[50-11.0] PASSED
test_cart.py::test_discount[100-0.0] PASSED
test_cart.py::test_discount[10-19.8] PASSED
test_cart.py::test_discount_out_of_range[-1] PASSED
test_cart.py::test_discount_out_of_range[101] PASSED

Parametrize combines with fixtures (as above, cart is a fixture and percent comes from the decorator). Put edge cases such as zero, negative and boundary values in the list; that is where bugs hide.

Mocking dependencies

Some code talks to things a test should not touch: the network, the clock, a payment service, the file system. A mock is a stand-in object that records how it was used and returns what you tell it to. Python ships unittest.mock for this, and pytest tests use it directly. The two key tools are Mock (an object that accepts any call) and patch (which temporarily replaces a name).

This function fetches a price from a service and applies a discount. We test it without any network by passing in a mock:

Python A mock stands in for a service

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Passing the dependency in as an argument (as service here) is the easiest design to test, called dependency injection. When the code imports its dependency directly, use patch to swap the name for the duration of a with block:

Python patch replaces a name temporarily

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The rule for patch is to patch the name where it is looked up, not where it is defined. If shop.py does from pricing import get_price, then patch "shop.get_price", not "pricing.get_price". In pytest you can write the same with the monkeypatch fixture (monkeypatch.setattr(shop, "get_price", fake)), or install the pytest-mock plugin and use its mocker fixture, which cleans up automatically.

Do not over-mock. A test whose every dependency is mocked can pass while the real program is broken. Mock the slow and unreliable edges (network, clock, randomness) and let your own code run for real.

Organizing and selecting tests

Real projects keep tests in a tests/ folder next to the code. A few options make large suites manageable:

  • python -m pytest tests/test_cart.py::test_total runs one test.
  • -k discount runs tests whose names contain "discount".
  • -x stops at the first failure, --lf re-runs only the tests that failed last time.
  • @pytest.mark.skip(reason="..."), @pytest.mark.skipif(...) and @pytest.mark.xfail skip a test or mark a known failure.
  • Custom markers such as @pytest.mark.slow let you run -m "not slow"; declare them under [tool.pytest.ini_options] in pyproject.toml so typos are caught.

A small pyproject.toml section sets project defaults:

TOML
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-q"
markers = ["slow: tests that take more than a second"]

Measuring coverage

Coverage tells you which lines of your code ran while the tests ran. The pytest-cov plugin adds it:

TEXT
python -m pip install pytest-cov
python -m pytest --cov=cart --cov-report=term-missing
TEXT
Name      Stmts   Miss  Cover   Missing
---------------------------------------
cart.py      16      0   100%
---------------------------------------
TOTAL        16      0   100%

The Missing column lists line numbers no test reached; those are the places to look for untested behavior. Treat the percentage as a flashlight, not a goal: 100% coverage proves every line ran, not that the assertions are meaningful. A test with no assert can still "cover" a line. Aim for tests that check behavior and failure cases, and use coverage to find the gaps.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How does pytest decide that a function is a test?

    pytest discovers files matching test_*.py or *test.py, and functions whose names start with test. No base class or decorator is needed.
  2. 2. How does a test receive a fixture?

    pytest matches parameter names to fixtures, calls the fixture and passes the result in. Fixtures in conftest.py are available without any import.
  3. 3. What runs after the yield in a yield fixture?

    Code after yield is teardown. pytest resumes the fixture after the test, whether it passed or failed.
  4. 4. What does @pytest.mark.parametrize("n, sq", [(1, 1), (2, 4), (3, 9)]) do to a test function?

    Each tuple becomes its own test case with its own pass or fail result and a name that includes the values.
  5. 5. If shop.py runs from pricing import get_price, which name should you patch to replace it in shop's tests?

    Patch the name where it is looked up. After the from-import, shop holds its own reference called shop.get_price, so patching pricing.get_price would not affect it.

Summary

  • pytest runs plain functions named test_* and explains failed assert statements in detail; run it with python -m pytest.
  • Fixtures (@pytest.fixture) provide setup by parameter name; yield adds cleanup; conftest.py shares them; tmp_path, capsys and monkeypatch are built in.
  • pytest.raises(..., match=...) checks errors and pytest.approx compares floats.
  • @pytest.mark.parametrize runs one test over many inputs.
  • unittest.mock (Mock, patch) replaces unreliable dependencies; patch where the name is looked up, and do not over-mock.
  • pytest-cov shows which lines ran; use it to find untested code, not as a score.

Next: Static Type Checking with mypy.