Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

Test Discovery and Project Layout

Learn how pytest discovers tests, the naming rules for files, classes and functions, the src layout, pytest.ini settings, and why a tests folder works.

pytest does not need a list of your tests. When you run it, it walks the folders, imports the files that look like tests, and picks out the functions and classes that look like tests. That is called discovery, and understanding its rules explains nearly every "why did pytest not run my test?" question you will ever have.

This lesson covers the default rules, how to change them, and the two project layouts you will meet in real code.

The default naming rules

What Default pattern
Test files test_*.py or *_test.py
Test functions names starting with test
Test classes names starting with Test, with no __init__ method
Test methods names starting with test inside a Test class

Everything else is ignored. A helper called make_user() in a test file is never run as a test, and a file called helpers.py is never collected (although test files can import it).

Python What gets collected?

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.

Collected: the three functions that start with test, the method inside TestGroup, and the test in shapes_test.py. Not collected: check_not_collected, helper, the class named Helper, and everything in helpers.py.

A very common mistake is to name a test file tests.py or check_cart.py, or to name a function cart_total_test. pytest silently ignores them, and a test that never runs can never fail. After writing a test, watch it fail once to prove it is collected.

Changing the rules

All of the patterns are settings. Put them in pytest.ini (or the [tool.pytest.ini_options] table of pyproject.toml):

INI
[pytest]
python_files = test_*.py check_*.py
python_classes = Test* Check*
python_functions = test_* verify_*
testpaths = tests

testpaths tells pytest where to look when you run plain pytest with no arguments, which also speeds up collection. The next example changes the rules and collects a file the default would have ignored.

Python Custom discovery patterns

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 only verify_positive ran: once you change python_functions, the old test_ prefix is no longer special. Most teams never change the defaults, because other developers expect them.

Two common layouts

Tests next to a flat package

Small projects often keep everything at the top level:

TEXT
project/
  cart.py
  test_cart.py

This works with no configuration because pytest adds the test file's folder to sys.path.

Separate tests folder and a src layout

Larger projects keep code and tests apart:

TEXT
project/
  pyproject.toml
  src/
    shop/
      __init__.py
      cart.py
  tests/
    test_cart.py

The src layout prevents an accidental import of your uninstalled source tree, so tests exercise the installed package, which is what users get. During development you either install the project in editable mode (pip install -e .) or tell pytest where the source is with the pythonpath option. The example below does the second.

Python A src layout with pythonpath

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 test imports shop.cart even though src/ is not a package itself. pythonpath = src put it on the import path for the test session.

flowchart TD
    P["project/"] --> C["pyproject.toml / pytest.ini"]
    P --> S["src/shop/"]
    P --> T["tests/"]
    T --> TA["test_cart.py"]
    T --> TB["conftest.py<br/>shared fixtures"]
    S --> SA["cart.py"]

A typical layout. conftest.py holds fixtures and hooks shared by every test in its folder; you will meet it in Conftest and Sharing.

Unique file names and import modes

Python imports test files as modules, so two files with the same base name in different folders can collide:

TEXT
tests/api/test_utils.py
tests/web/test_utils.py     # clash!

You have two ways out. The classic one is to add an empty __init__.py to each folder so the files become api.test_utils and web.test_utils. The modern one is to set --import-mode=importlib in addopts, which imports each file by its path without touching sys.path. New projects should prefer importlib mode or unique file names.

Rootdir and configuration files

pytest looks for configuration in this order and uses the first match it finds walking upward from the arguments: pytest.toml, .pytest.toml, pytest.ini, pyproject.toml (with a [tool.pytest] or [tool.pytest.ini_options] table), tox.ini, setup.cfg. The folder of that file becomes the rootdir, which anchors node ids and the cache.

A small pyproject.toml looks like this:

TOML
[tool.pytest.ini_options]
addopts = "-ra"
testpaths = ["tests"]
pythonpath = ["src"]

Troubleshooting "no tests ran"

If pytest reports no tests ran (exit code 5), walk through this list:

  1. Is the file name test_*.py or *_test.py?
  2. Does the function start with test, and does the class start with Test and have no __init__?
  3. Are you in the right folder, and is it covered by testpaths?
  4. Does pytest --collect-only -q list what you expect?
  5. Did a syntax or import error stop collection? pytest reports it as an error with the traceback.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these names is collected by default?

    The file must match test_*.py or *_test.py and the function must start with test. utils_tests.py matches neither file pattern.
  2. 2. Why might a TestCart class with an init method not be collected?

    pytest creates a new instance for every test and does not pass constructor arguments, so a class with init is skipped (use fixtures for setup).
  3. 3. What does the pythonpath = src setting do?

    pythonpath lists directories that pytest adds to sys.path so tests can import the code under src.
  4. 4. pytest prints 'no tests ran'. What is the best first diagnostic?

    --collect-only shows exactly what discovery found, which points to naming, path or import problems.

Summary

  • pytest collects test_*.py / *_test.py files, test* functions and Test* classes without __init__.
  • Change the patterns with python_files, python_functions and python_classes, but the defaults are best.
  • Use testpaths to say where tests live and pythonpath or pip install -e . to make your code importable.
  • The src layout plus a tests/ folder is the standard for larger projects.
  • Same-named test files in different folders need __init__.py files or --import-mode=importlib.
  • When tests do not run, check naming first and use --collect-only.

Next: Assertions and Failure Reports