Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 38 ยท Testing and CI

Testing a Package with pytest

Test your Python package properly with pytest. Learn the src layout, fixtures, parametrization, pytest settings in pyproject.toml, and testing the installed package.

Packaging and testing belong together. A package that installs perfectly but fails on the first import, or works only because you ran it from the source folder, is a broken package. pytest is the standard test runner for Python: tests are plain functions with plain assert statements, and it reports exactly what differed when one fails.

In this lesson you will run pytest for real, learn the features packaging projects use most (fixtures, parametrization, markers), and see how to arrange the project so tests exercise the installed package, the same thing your users get.

Your first tests

pytest finds files named test_*.py (or *_test.py), and inside them functions named test_*. Here pytest runs for real on two files it creates in a temporary folder:

Python Run pytest on a tiny project

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 the failure report: pytest rewrites assert statements so it can show both sides of the comparison ('a-b' == 'a_b') with no special assertion methods. The exit code is 0 when everything passes, 1 when tests fail, and other numbers for usage errors or no tests collected. CI systems rely on that code.

Parametrization and fixtures

Two features remove most repetition.

@pytest.mark.parametrize runs one test with many inputs, and reports each case separately. Fixtures provide setup (and cleanup) to tests that ask for them by name. Built-in fixtures include tmp_path (a fresh temporary directory), monkeypatch (temporarily change environment variables or attributes), capsys (capture printed output) and caplog.

Python Parametrize and fixtures

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.

With -v each parametrized case appears by name (test_debug_flag[1-True]), so a failure tells you which input broke. monkeypatch guarantees the environment variable is restored after each test, so tests cannot leak state into each other.

Useful extras you will meet quickly:

  • @pytest.mark.skipif(sys.platform == "win32", reason="...") and @pytest.mark.xfail for known gaps.
  • Custom markers such as @pytest.mark.slow, selected with -m "not slow".
  • conftest.py files share fixtures across a directory without importing them.
  • pytest -x stops at the first failure; --lf re-runs only what failed last time; -k expression selects tests by name.

Project layout: test the installed package

Where you put the code changes what your tests prove. The recommended layout is the src layout:

TEXT
myproject/
  pyproject.toml
  src/
    myproject/
      __init__.py
      core.py
  tests/
    test_core.py

With the code inside src/, import myproject does not work from the repository root unless the package is installed. That is the point: you must install it (normally in editable mode) before testing, so your tests run against the package as installed, including pyproject.toml data files, entry points and package discovery. A flat layout (package next to tests/) can hide mistakes such as a missing __init__.py or a data file that never makes it into the wheel, because Python imports straight from the source folder.

Terminal
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"      # editable install plus test dependencies
pytest

For release checks, build the wheel and test that: install the built file into a fresh environment, then run the tests against it. That is exactly what tools like tox and nox automate (see the next lesson).

Configure pytest in pyproject.toml

TOML
[tool.pytest.ini_options]
minversion = "8.0"
testpaths = ["tests"]
addopts = "-ra --strict-markers --strict-config"
markers = [
    "slow: tests that take more than a second",
    "network: tests that need internet access",
]
filterwarnings = ["error"]
  • testpaths avoids scanning the whole repository.
  • -ra prints a summary of skipped and failed tests; --strict-markers turns a mistyped marker into an error.
  • filterwarnings = ["error"] makes any warning fail a test. It is a good habit for libraries because deprecation warnings show up as failures before your users hit removals. Add exceptions for third-party warnings you cannot fix.

Doctests and test dependencies

Examples in docstrings can double as tests: pytest --doctest-modules src runs them. Keep test-only requirements out of the runtime dependency list, using a dependency group (test = ["pytest>=8", "coverage"]) or an optional extra.

Write a test that checks the installed version of your package matches the one in pyproject.toml, and a test that imports every public module. These cheap smoke tests catch most packaging mistakes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What exit code does pytest return when all tests pass?

    Zero means success; non-zero values signal failures or errors, which is what CI checks.
  2. 2. What does @pytest.mark.parametrize do?

    Each argument set becomes its own test case, so one failing input is easy to identify.
  3. 3. Why does the src layout help catch packaging mistakes?

    Because Python cannot import the package straight from the source folder, missing files or wrong package configuration show up during testing.
  4. 4. What does monkeypatch.setenv("APP_DEBUG", "1") guarantee?

    Monkeypatch changes are undone at the end of each test, so tests stay independent.

Summary

  • pytest discovers test_* functions, uses plain assert, and exits with 0 only if everything passes.
  • Fixtures and parametrize reduce repetition; tmp_path, monkeypatch and capsys are built in.
  • Use the src layout and an installed (editable) package so tests prove the package works as users get it.
  • Configure pytest in [tool.pytest.ini_options], use strict markers and consider turning warnings into errors.
  • Keep test dependencies in a group or extra, not in runtime dependencies.

Next: Coverage, tox and nox