Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 38 ยท Testing Real Projects

Project Layout and Configuration

Organize a real Python project for pytest: src layout, tests folders, conftest.py placement, import modes, and the pytest.ini or pyproject.toml settings every team should set.

A single test file next to a single module works for a tutorial. A real project has packages, many test files, shared fixtures and a team of people who must all run the tests the same way. How you lay out the folders, and which settings you put in the configuration file, decides whether the suite stays pleasant or becomes a puzzle of import errors.

This lesson gives you a layout that scales, explains the import problems that bite beginners, and builds a configuration file with the options worth setting on day one.

TEXT
myproject/
โ”œโ”€โ”€ pyproject.toml          # package metadata + [tool.pytest.ini_options]
โ”œโ”€โ”€ src/
โ”‚   โ””โ”€โ”€ shopkit/
โ”‚       โ”œโ”€โ”€ __init__.py
โ”‚       โ”œโ”€โ”€ cart.py
โ”‚       โ””โ”€โ”€ pricing.py
โ””โ”€โ”€ tests/
    โ”œโ”€โ”€ conftest.py         # fixtures shared by all tests
    โ”œโ”€โ”€ unit/
    โ”‚   โ”œโ”€โ”€ test_cart.py
    โ”‚   โ””โ”€โ”€ test_pricing.py
    โ””โ”€โ”€ integration/
        โ”œโ”€โ”€ conftest.py     # fixtures only for integration tests
        โ””โ”€โ”€ test_checkout_flow.py

Three decisions are worth explaining.

src/ layout. Your package lives in src/shopkit, not in the project root. Because the root is not importable by accident, tests can only import shopkit if it was properly installed (usually pip install -e .). That catches packaging mistakes (a missing file in the distribution) that a flat layout hides.

A separate tests/ folder. Tests do not ship with the package and are easy to exclude. The alternative, tests inside the package, is also valid for libraries that want to ship their tests; pick one and be consistent.

conftest.py at several levels. A conftest.py is imported automatically and its fixtures apply to its folder and everything below. Put widely shared fixtures at tests/conftest.py and specialised ones next to the tests that use them. Never import from a conftest.py in test code; request fixtures instead.

flowchart TB
    R["tests/conftest.py<br/>db_url, tmp settings"] --> U["tests/unit/<br/>sees root fixtures"]
    R --> I["tests/integration/conftest.py<br/>adds live_server"]
    I --> T["tests/integration/test_checkout_flow.py<br/>sees both levels"]

Fixtures flow downward: a test sees its folder's conftest.py and every parent's.

Why imports break, and how to fix them

The classic beginner error is ModuleNotFoundError: No module named 'shopkit'. Pytest must be able to import your package. There are three good answers, in order of preference:

  1. Install the project in editable mode: pip install -e .. Tests then import the real installed package. This is what your users get.
  2. Set pythonpath in the pytest config: pythonpath = ["src"]. Pytest adds that folder to sys.path for the run. Simple and works without installing.
  3. Rely on rootdir insertion (flat layouts only): the default prepend import mode adds the test file's folder to sys.path, which is why import calc works when calc.py sits next to test_calc.py. Avoid depending on this in bigger projects.

There is another trap: duplicate test file names. With the default import mode, tests/unit/test_utils.py and tests/integration/test_utils.py clash unless each folder has an __init__.py, or you use --import-mode=importlib (modern, no sys.path changes, no clash) via addopts. Recent projects often choose importlib and skip __init__.py files in tests.

Naming conventions pytest uses

By default pytest collects files named test_*.py or *_test.py, classes named Test* (without an __init__ method), and functions or methods named test*. You can change all of these with python_files, python_classes and python_functions, but the defaults are what every other developer expects.

Configuring pytest

Pytest reads configuration from the first of pytest.ini, pyproject.toml (under [tool.pytest.ini_options]), tox.ini or setup.cfg it finds walking up from the arguments. Use one; pyproject.toml is the modern home.

TOML
[tool.pytest.ini_options]
minversion = "8.0"
testpaths = ["tests"]
pythonpath = ["src"]
addopts = ["-ra", "--strict-markers", "--strict-config", "--import-mode=importlib"]
markers = [
    "slow: tests that take more than a second",
    "integration: tests that touch real services",
]
filterwarnings = ["error"]
xfail_strict = true
Setting Why
testpaths pytest with no arguments looks only here, so collection is fast and predictable
pythonpath Makes src/ importable without installing
addopts Flags added to every run; -ra summarizes everything except passes
--strict-markers A typo such as @pytest.mark.slwo becomes an error instead of silently doing nothing
--strict-config Unknown config keys are errors
markers Documents and registers every custom marker
filterwarnings = ["error"] Turns warnings into failures so deprecations are fixed early
xfail_strict An xfail test that unexpectedly passes counts as a failure

Here is a complete miniature project, with src layout and a config file, run for real:

Python A src layout with pytest.ini

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 three things in the output: no argument was needed because testpaths pointed at tests; two files are both called test_cart.py yet do not clash thanks to --import-mode=importlib; and cart is available everywhere without any import because it lives in tests/conftest.py.

Now check what --strict-markers buys you. Here the flag is passed on the command line, and the test file has a typo in a marker name (in a real project the flag lives in addopts):

Python strict-markers catches a typo

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.

Without --strict-markers the misspelled marker is silently ignored, and pytest -m slow would quietly skip a test you meant to select.

Environment, dependencies and running

  • List test dependencies separately from runtime ones: pip install -e ".[test]" with an optional-dependency group, or a dependency-groups table, or a requirements-dev.txt.
  • Use a virtual environment per project and run python -m pytest rather than bare pytest: it also puts the current directory on sys.path, which sidesteps some import problems.
  • Add a thin command layer (a Makefile, tox, nox or uv run) so everyone runs the same thing: make test.
  • Keep .pytest_cache/, .coverage, htmlcov/ and __pycache__/ in .gitignore.
  • Useful discovery commands: pytest --collect-only -q lists what would run, and pytest --fixtures lists available fixtures with their docstrings.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main benefit of the src/ layout?

    With src/, the project root does not contain the package, so an accidental import from the working directory cannot succeed.
  2. 2. Which setting turns a misspelled @pytest.mark name into an error?

    --strict-markers requires every marker to be registered, so typos are caught at collection time.
  3. 3. Two files, tests/unit/test_utils.py and tests/integration/test_utils.py, clash on import. What is a modern fix?

    importlib import mode avoids sys.path manipulation and the module name conflicts of the default prepend mode.
  4. 4. A fixture defined in tests/conftest.py is visible to...

    conftest.py fixtures apply to all tests in that directory tree and are found by name.

Summary

  • Use src/ for the package, tests/ beside it, and conftest.py files at the levels where fixtures are shared.
  • Make the package importable with pip install -e . or pythonpath = ["src"].
  • --import-mode=importlib avoids duplicate-name clashes between test files.
  • Configure testpaths, addopts, registered markers, --strict-markers and xfail_strict in pyproject.toml or pytest.ini.
  • Run with python -m pytest and wrap commands in one team-wide entry point.

Next: Testing Command-Line Programs