Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Fixtures

conftest.py and Sharing Fixtures

Learn how conftest.py makes fixtures available to many test files without imports, how its folder scope and override rules work, and how to organize shared fixtures.

So far each fixture lived in the same file as the tests that use it. In a real project, ten test files need the same app or user fixture. Copy-pasting it is wrong, and importing fixtures from a helper module (from helpers import user) works poorly because linters flag them as unused and pytest then sees them as module-level names.

The pytest solution is a special file called conftest.py. Fixtures defined there are available to every test in the same folder and below it, without any import. pytest finds the file by itself.

A first conftest.py

Python Sharing a fixture through conftest.py

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.

Neither test file imports user. Both asked for it by name; pytest looked in the test file first, then in conftest.py in the same folder, then in parent folders.

Folder scope: conftest at several levels

A conftest.py applies to its folder and all subfolders. You can have several, each adding or overriding fixtures for a part of the tree:

TEXT
tests/
  conftest.py            # fixtures for all tests
  test_math.py
  api/
    conftest.py          # extra fixtures only for tests/api
    test_users.py
  web/
    test_pages.py        # cannot see api's fixtures
Python Nested conftest files

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 first two tests pass. The last one gets an error fixture 'api_url' not found, because api_url lives in tests/api/conftest.py, a sibling folder. Putting a fixture as low in the tree as practical keeps the namespace tidy; pytest lists what is available with pytest --fixtures.

Overriding a fixture

A fixture with the same name in a closer place overrides the one further up. This is a powerful way to specialise behavior for one folder, one file, or even one class:

Python Overriding 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.

Notice how the class fixture asks for mode and receives the file-level one, then builds on it. This "extend the parent" trick works at every level.

flowchart TD
    A["test function / class fixture"] --> B["test file fixtures"]
    B --> C["conftest.py in the same folder"]
    C --> D["conftest.py in parent folders"]
    D --> E["plugins and built-in fixtures"]

pytest searches from the most specific place outward and uses the first match.

What else belongs in conftest.py

conftest.py is the place for things pytest should know about for a whole folder:

  • Fixtures shared by several files.
  • Hooks such as pytest_addoption (custom command-line flags), pytest_collection_modifyitems (reorder or skip tests) and pytest_configure (register markers).
  • Plugin loading through pytest_plugins = ["myproject.fixtures"] (only in the top-level conftest).

Here is a small hook that adds a command-line option and a fixture that reads it:

Python A custom option from conftest.py

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 option is now part of the command line: pytest --env staging. You will see more hooks and plugin machinery in the Plugins and Coverage chapter.

Rules and pitfalls

  1. Never import from conftest.py in your tests (from conftest import x). Tests should receive things through fixtures; importing a conftest makes it a normal module and can run it twice.
  2. Keep it readable. A conftest with 800 lines is a smell. Split fixtures into modules, such as tests/fixtures/db.py, and load them from conftest with pytest_plugins or by importing the fixture functions with # noqa.
  3. conftest.py is not collected as tests. Do not name it test_conftest.py.
  4. Unique test file names still matter across folders; see Test Discovery.
  5. Fixture visibility follows the folder, not the import graph. A fixture needed by two sibling folders belongs in their common parent.

A typical project layout

TEXT
project/
  pyproject.toml
  src/shop/...
  tests/
    conftest.py          # app, client, db session
    unit/
      conftest.py        # tiny fixtures, no network
      test_pricing.py
    integration/
      conftest.py        # real database fixtures, marked slow
      test_checkout.py

Unit tests stay fast because their conftest has no heavy fixtures; integration tests get the expensive ones. The folder structure is the configuration.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a test file use a fixture defined in conftest.py?

    pytest discovers conftest.py itself. Fixtures defined there are available to tests in the folder and below by name.
  2. 2. tests/api/conftest.py defines fixture api_client. Which tests can use it?

    A conftest.py applies to its own folder and everything below it.
  3. 3. A fixture named mode exists in conftest.py and also in the test file. Which one does a test in that file receive?

    pytest searches from the test outward; the first match wins.
  4. 4. Why should tests not import from conftest.py?

    Share things through fixtures instead of imports so pytest manages loading and scope.

Summary

  • conftest.py makes fixtures available to all tests in its folder and subfolders without imports.
  • Several conftest files can coexist; closer definitions override farther ones, and an override can request the original by the same name.
  • It also holds hooks (like pytest_addoption) and plugin settings.
  • Do not import from conftest and do not let it grow huge; split fixtures into modules.
  • Put each fixture as low in the tree as it can be while still serving everyone who needs it.

Next: Built-in Fixtures