pytest, from first principles

A fixture is a function that prepares something a test needs, and hands that thing to the test. The word is borrowed from lab work: a "fixture" is the rig that holds your specimen in a known, repeatable position so every measurement starts from the same place.

In pytest, a fixture is a normal Python function marked with the @pytest.fixture decorator. A test asks for a fixture by naming it as a parameter. pytest sees that name, runs the fixture, and passes whatever the fixture produces into the test as an argument.

import pytest

@pytest.fixture
def sample_cart():
    # build the "known specimen"
    return {"apples": 3, "pears": 2}

def test_total_items(sample_cart):   # <- asks for the fixture by name
    assert sum(sample_cart.values()) == 5

The key mental shift: the test never calls sample_cart() itself. It just declares "I need a sample_cart" by putting that word in its parameter list, and pytest supplies it. That pattern — you declare a dependency by name and the framework provides it — is called dependency injection, and it is the whole idea behind fixtures.

Fixtures are also composable: a fixture can request other fixtures the same way a test does. That lets you build small pieces (a database connection) and assemble them into bigger ones (a seeded database with a logged-in user) without repeating yourself.

Under the hood pytest does something that feels like magic but is completely mechanical: it reads the signature of your test function and matches parameter names against a registry of known fixtures.

Here is the sequence pytest runs for every single test it is about to execute:

When a test asks for user, pytest reads that name, finds the user fixture, sees it asks for db, and keeps recursing until every dependency is resolved — building a directed graph and running it from the bottom up:

Two consequences fall out of this that trip people up:

• Names matter, types don't. pytest matches purely on the parameter name being identical to a fixture name. There is no type annotation lookup, no registration by class. Rename the fixture and every test that used it breaks.
• Fixtures form a graph, not a list. Because fixtures can request fixtures, pytest builds a directed acyclic graph and topologically sorts it. If db is needed by user which is needed by your test, db runs first, then user, then the test — automatically.

@pytest.fixture
def db():
    return Database(":memory:")          # leaf of the graph

@pytest.fixture
def user(db):                          # depends on db
    return db.create_user("ada")

def test_login(user):                    # depends on user → depends on db
    assert user.name == "ada"
# execution order pytest computes:  db()  →  user(db)  →  test_login(user)

You can see the entire resolved graph for your suite without running anything by asking pytest to list fixtures: pytest --fixtures shows every available fixture and where it came from, and pytest --setup-plan prints the exact setup/teardown order it would execute.

yield is a keyword that pauses a function, hands a value back to the caller, and remembers exactly where it stopped so it can resume later from that same point — with all its local variables intact.

A normal function has one exit: return. When it returns, its stack frame is destroyed and all its local state is gone. A function containing yield is fundamentally different — Python compiles it into a generator function. Calling it does not run the body; it hands you a generator object, a resumable, paused computation.

def plain():
    return 1                 # runs, exits, frame discarded

def gen():
    print("A: before yield")
    yield 1                  # PAUSE here, hand back 1
    print("B: after yield")   # resumes here on next request
    yield 2

g = gen()                   # nothing printed yet! body hasn't run
next(g)                     # prints "A: before yield", returns 1, PAUSES
next(g)                     # prints "B: after yield",  returns 2, PAUSES
next(g)                     # raises StopIteration — body finished

The crucial property is suspended state. When the generator pauses at a yield, its local variables, its position in the code, even a half-finished loop — all of it is frozen and stored on the generator object. The next time you drive it forward, execution picks up on the line right after the yield, as if it had never stopped.

Generators are what power for loops (a for loop just calls next() until StopIteration), lazy sequences, and streaming pipelines. But for our purposes the single most important fact is: code before a yield runs now; code after it runs later, when someone resumes the generator.

This is where §03 pays off. pytest treats a yield fixture as a two-act play: everything before the yield is setup, the value you yield is what the test receives, and everything after the yield is teardown that runs once the test (or scope) is done.

@pytest.fixture
def tmp_server():
    server = Server()
    server.start()          #  ← SETUP  (runs before the test)
    yield server           #  ← the test runs right here, with `server`
    server.stop()           #  ← TEARDOWN (runs after the test finishes)

def test_ping(tmp_server):
    assert tmp_server.ping() == "pong"

Mechanically, pytest does this: it calls your fixture function, which (because it contains yield) returns a generator. pytest calls next() on it once — that runs the setup and stops at the yield, capturing the yielded server. pytest injects that value into the test. When the test is over, pytest calls next() again, which resumes the generator past the yield and runs your teardown until the generator finishes.

pytest                         your fixture generator
  │
  ├── next(gen) ───────────▶  server.start(); yield server   (pause)
  │   ◀── receives `server`
  │
  ├── run test_ping(server)
  │
  └── next(gen) ───────────▶  resumes: server.stop()        (StopIteration)

Why teardown is reliable

The teardown after yield runs even if the test fails or raises an exception. pytest guarantees the generator is driven to completion during teardown, so your server.stop() is not skipped just because an assertion blew up. (The one case it won't run: if the setup before the yield itself raises, then there is nothing to tear down and pytest reports a fixture error.)

If you have several yield fixtures in play, their teardowns run in reverse order of setup — last set up, first torn down — mirroring how nested resources should be released. This is the same LIFO discipline as a stack of with blocks.

A fixture's scope answers one question: how often should this fixture be set up and torn down? Once per test? Once per file? Once for the entire run? Scope is the dial that controls the lifetime of the fixture's cached value.

You set it with the scope= argument on the decorator. There are five, from narrowest to widest:

The rule most people remember is the nesting session → module → function: a session-scoped fixture is built once and lives for the whole run; a module-scoped one is rebuilt for each file; a function-scoped one is rebuilt for every test.

@pytest.fixture(scope="session")
def db_engine():
    engine = create_engine("postgresql://…")   # slow — do it ONCE
    yield engine
    engine.dispose()                            # torn down at end of the run

@pytest.fixture(scope="function")                 # default; shown for contrast
def db_session(db_engine):
    conn = db_engine.connect()
    txn = conn.begin()
    yield conn
    txn.rollback()                              # fresh, isolated per test
    conn.close()

There is also dynamic scope: scope can be a function that returns the scope string at collection time, letting a command-line flag decide whether a fixture is session- or function-scoped. That's advanced, but worth knowing it exists.

Yes — and this is a genuinely useful way to understand it. Within its scope, a fixture behaves like a singleton: the first request builds it, and every later request in that same scope gets the identical, cached object back, not a fresh one.

A classic singleton means "there is exactly one instance of this thing, globally." A fixture is a scoped singleton: exactly one instance per scope window. Widen the scope and the window of one-ness widens with it.

@pytest.fixture(scope="session")
def shared():
    return object()

def test_a(shared):
    test_a.seen = id(shared)

def test_b(shared):
    # SAME object — session scope cached it across both tests
    assert id(shared) == test_a.seen        # passes
#
# If `shared` were scope="function", each test would get a
# DIFFERENT object() and this assert would FAIL.

So the relationship is precise: scope defines the cache key. pytest caches a fixture's result keyed by (fixture, scope-instance). Two tests in the same module share a module-scoped fixture's value because they map to the same cache key; two tests in different modules do not.

A conftest.py file is a special, pytest-recognized module where you put fixtures (and hooks, and plugins) you want available to every test in that directory and below — without importing anything.

You define a fixture in conftest.py exactly the way you would anywhere else. The only difference is location: because the file is named conftest.py, pytest discovers and loads it on its own, and the fixtures inside become visible to sibling and descendant test files automatically.

import pytest

@pytest.fixture(scope="session")
def api_client():
    client = ApiClient(base_url="http://localhost:8000")
    yield client
    client.close()

# notice: NO "from conftest import api_client"
def test_list_users(api_client):     # just name it — pytest supplies it
    assert api_client.get("/users").status == 200

The name conftest is short for "conftest" as in configuration for tests — a local, per-directory hook point. You can have many of them: one at the project root for truly global fixtures, and more specific ones deeper in the tree for fixtures only relevant to a subset of tests. Fixtures with the same name in a nearer conftest.py override those in a farther one, which is a deliberate and useful feature.

pytest discovers conftest.py files by walking the filesystem, not by importing them from your code. For any test it collects, it loads every conftest.py sitting on the path from the project's rootdir down to the directory that test lives in.

Concretely, given this layout and a run of pytest tests/api/test_auth.py:

The fixtures visible to test_auth.py are the union of all three loaded conftest.py files, plus fixtures defined in test_auth.py itself, plus fixtures from any installed plugins. Nearer files win on name collisions. The tests/ui/conftest.py is never touched because the test being run is not underneath it — this is how pytest keeps unrelated corners of a large suite isolated.

Loaded once, applied broadly

pytest imports each relevant conftest.py a single time at the start of collection and registers its contents into the plugin/fixture system. From that point the fixtures and hooks it defines are simply part of pytest's runtime for the matching scope. There is no re-import per test.

No. You should never write import conftest or from conftest import .... pytest loads it for you; importing it by hand fights the framework and causes real bugs.

Why it's actively wrong, not just unnecessary:

• Double loading. pytest already imports conftest.py as a plugin. If you also import it, Python may load it a second time under a different module identity, so you end up with two copies of the same fixtures and confusing "fixture not found / defined twice" errors.
• It breaks discovery. The entire point of conftest.py is importless availability by directory. Manually importing couples files together and defeats the mechanism that makes fixtures flow down the tree.
• Fixtures aren't meant to be called. A fixture function decorated with @pytest.fixture is not an ordinary function you invoke — calling it directly is an error in modern pytest. You request it by name; you don't import and call it.

The same holds for the test files themselves: you don't import your test modules either. pytest's collector imports them. Your job is to write functions named test_* and fixtures; pytest's job is the importing.

Put the fixture in a conftest.py at the lowest directory that is a common ancestor of every test that needs it. That is the idiomatic, framework-blessed way to share — no imports, no plugins, no ceremony.

Choose the level by asking "who needs this?":

The three ordered options, from most local to most reusable:

1. conftest.py — the default answer for sharing inside one repository. Fixtures placed here are automatically available to all tests at or below that directory. This covers ~95% of real cases.
2. A fixture plugin module — for sharing across repos, package a module of fixtures and register it via pytest_plugins or as an installable plugin with an entry point. Now pip install your-fixtures makes them available anywhere.
3. The pytest_plugins variable — in a root conftest.py you can write pytest_plugins = ["myapp.testing.fixtures"] to pull a module of fixtures into scope explicitly. Useful when fixtures live inside your application package rather than the test tree.

Hooks are pytest's plugin extension points — named functions that pytest calls at specific moments in its lifecycle (startup, collection, before each test, after each test, at reporting) so that you, or a plugin, can inject custom behavior.

pytest is itself built on a plugin system called pluggy. pytest defines a set of hook specifications (the callable slots, all named pytest_*), and any plugin — including your conftest.py — can supply a hook implementation by defining a function with the matching name. When the moment arrives, pytest calls every registered implementation of that hook.

def pytest_addoption(parser):          # add a --slow CLI flag
    parser.addoption("--slow", action="store_true", default=False)

def pytest_collection_modifyitems(config, items):
    # runs AFTER collection — skip @slow tests unless --slow given
    if config.getoption("--slow"):
        return
    skip = pytest.mark.skip(reason="needs --slow")
    for item in items:
        if "slow" in item.keywords:
            item.add_marker(skip)

def pytest_runtest_setup(item):         # runs before EACH test
    print(f"about to run {item.nodeid}")

A representative slice of the hook lifecycle, in call order:

pytest_configure            once, after config is built
pytest_collection           discover test files & items
pytest_collection_modifyitems  reorder / filter / mark collected tests
   for each test item:
     pytest_runtest_setup      fixtures set up
     pytest_runtest_call       the test body runs
     pytest_runtest_teardown   fixtures torn down
     pytest_runtest_makereport build the pass/fail report
pytest_sessionfinish        once, at the very end

A pytest run is two big phases wrapped in a plugin manager: first it collects every test into a tree of nodes, then it executes each one, running fixtures around it and building a report. Almost every step is a hook, which is why pytest is so extensible.

Phase 0 — bootstrap

pytest starts, reads configuration (from pyproject.toml, pytest.ini, the CLI), determines the rootdir, and initializes pluggy, its plugin manager. It registers built-in plugins, installed third-party plugins, and every relevant conftest.py. One quiet but important step here: pytest installs its assertion rewriting import hook (see §13).

Phase 1 — collection

pytest walks the test paths and builds a tree of collector and item nodes: Session → Package → Module → Class → Function. It imports each test module (this is why your test files must be importable), finds functions named test_* and classes named Test*, and expands any @pytest.mark.parametrize into multiple concrete items. Each leaf is a test item with a unique nodeid like tests/test_users.py::test_login[case2].

Phase 2 — execution

For each collected item pytest runs the setup → call → teardown protocol:

Phase 3 — reporting & exit

pytest aggregates all outcomes, prints the summary (18 passed in 0.3s), and sets a process exit code (0 = all passed, 1 = failures, others for usage errors / no tests). CI systems read that exit code to pass or fail a build.

Running python test_thing.py executes a script top to bottom and stops at the first uncaught error. pytest is a framework that finds your tests, runs them independently, explains failures in detail, injects dependencies, and reports structured results. The gap is large.

The signature trick: assertion rewriting

The feature that most feels like magic is assertion introspection. In plain Python, assert a == b raises a bare AssertionError with no context. pytest installs an import hook that rewrites the bytecode of your test modules as they load, replacing plain asserts with instrumented versions that capture the operands. That's why a failing pytest assert shows you exactly what each side evaluated to — no need for self.assertEqual or special assert methods like unittest requires.

# the code you write:
def test_math():
    assert add(2, 2) == 5

# python test.py  →  "AssertionError"      (that's all)
# pytest          →  assert 4 == 5
#                     +  where 4 = add(2, 2)   ← the introspected detail

So the difference isn't cosmetic. A plain script can contain asserts, but pytest turns "a file that crashes on the first bad assert" into "a test suite that reports every outcome, tells you precisely why each failure happened, wires up dependencies, and integrates with CI."

In Python, an object is the single, universal kind of thing that all data is. Every value you can name — a number, a string, a list, a function, a class, a module, even a type itself — is an object. There is nothing in Python that is not an object.

The language model says every object has exactly three properties:

• Identity — a fixed, unique tag for its lifetime, revealed by id(x). Two names pointing at the same object share an identity (a is b).
• Type — what kind of object it is and what it can do, revealed by type(x). The type never changes.
• Value — the actual contents. Some objects are mutable (a list can change value), some immutable (an int or str cannot).

x = [1, 2, 3]
id(x)          # 140237… — its identity
type(x)        # <class 'list'> — its type
x              # [1, 2, 3] — its value (mutable)

# functions, classes, modules are objects too:
def f(): pass
f.tag = 99            # attach an attribute to a function — it's an object
type(f)               # <class 'function'>
type(int)             # <class 'type'>  — even the type `int` is an object

An object generally bundles state (its data, the value) with behavior (its methods — functions that act on that data). You reach both through attribute access: obj.data and obj.method(). This is why the pytest concepts in §15 — a "session," a "module," a "function under test" — are all literally objects: they carry data (a nodeid, a parent, markers) and behavior (collect, run, report).

These words carry two related meanings: they're kinds of Python objects, and pytest also uses them as the names of the nodes in its collection tree (and as fixture scopes). Understanding both removes most of the mystery around scope and collection.

As Python objects

As pytest's node tree

pytest models your suite as a tree of nodes, and reuses these very words for the levels. This is the same hierarchy that defines fixture scopes:

So when §05 says a fixture is scope="session" or scope="module", it is naming a level of this tree. A session-scoped fixture is cached on the Session node (one per run); a module-scoped fixture is cached on each Module node (one per file). "Function scope" means cached on the individual Function item — the default, freshest, narrowest level.

A .toml file is a configuration file written in TOML — "Tom's Obvious, Minimal Language." Its whole purpose is to hold settings in a format that's easy for humans to read and edit and unambiguous for tools to parse. In modern Python, the canonical one is pyproject.toml, the single place that configures your project and its tools — pytest included.

TOML's data model is simple: key = value pairs, grouped under bracketed tables (sections). Values are typed — strings, numbers, booleans, dates, arrays, and nested tables.

# a table (section) is written in [brackets]
[project]
name = "etch"                       # string
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["pytest", "httpx"]   # array

# nested table via dotted name — pytest reads THIS one:
[tool.pytest.ini_options]
minversion = "8.0"
addopts = "-ra -q"                  # default CLI flags
testpaths = ["tests"]              # where to look for tests

Why the ecosystem standardized on it:

• One file, many tools. Before pyproject.toml, each tool had its own file (setup.cfg, pytest.ini, .flake8, …). Now build backends, linters, formatters, and pytest all read their own [tool.*] table from one place.
• Unambiguous & typed. Unlike ad-hoc INI, TOML has a real spec: "3" is a string, 3 is an integer, true is a boolean. No guessing.
• Standardized in Python. Python 3.11+ ships tomllib in the standard library to read TOML, cementing it as the config format.

A marker is a label you stick on a test with @pytest.mark.something. Markers let you tag tests ("this one is slow," "this needs a network," "skip this on Windows") and then select, skip, or specially treat groups of them. You declare/register the tag names in TOML; you apply them in your test modules.

Applying markers in a test module

import pytest

@pytest.mark.slow                       # custom tag — "this test is slow"
def test_full_reindex():
    ...

@pytest.mark.skip(reason="flaky on CI")   # built-in marker
def test_known_bad():
    ...

@pytest.mark.parametrize("n,expected", [(2, 4), (3, 9)])
def test_square(n, expected):        # built-in — expands to 2 test items
    assert n * n == expected

pytest ships built-in markers — skip, skipif, xfail (expected to fail), parametrize, usefixtures — and lets you invent custom markers like slow or integration for your own selection needs.

Registering custom markers in TOML

Custom markers should be registered so pytest knows they're intentional (unregistered ones trigger a warning, and --strict-markers turns that into an error — a good safety net against typos like @pytest.mark.slwo):

[tool.pytest.ini_options]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "integration: touches external services",
]

Selecting by marker on the command line

pytest -m slow                 # only tests tagged @pytest.mark.slow
pytest -m "not slow"           # everything EXCEPT slow ones
pytest -m "integration and not slow"   # boolean expressions work
pytest -k reindex              # -k selects by NAME substring, not markers

Here is the whole system in one story. Picture a small project and a single command — pytest -m "not slow" — and watch every concept from §01–§17 do its job in sequence.

myproject/
├── pyproject.toml          # [tool.pytest.ini_options]: markers, testpaths (§16,§17)
├── conftest.py             # session fixtures + a hook          (§07,§08,§11)
└── tests/
    ├── conftest.py         # function fixtures for this folder  (§07)
    └── test_orders.py      # the actual tests                   (§01)

1. BOOTSTRAP   pytest reads pyproject.toml (§16): loads markers, testpaths,
              default flags. Starts pluggy, installs assertion rewriting (§13).
              Finds & loads both conftest.py files by walking the tree (§08) —
              you never imported them (§09).

2. COLLECTION  Builds the node tree: Session → Module → Function (§15).
              Imports test_orders.py (a module object, §14). Finds test_*
              functions (function objects, §14). Expands @parametrize into
              items. A hook, pytest_collection_modifyitems (§11), plus the
              -m "not slow" filter (§17), deselects @pytest.mark.slow tests.

3. EXECUTION  For each surviving item:
                setup    → reads the test's parameter names, resolves the
                           fixture DAG (§02). db_engine (session scope, §05)
                           is built ONCE and cached like a scoped singleton
                           (§06); db_session (function scope) is fresh per test.
                           Each yield fixture runs its setup, pauses at
                           `yield`, hands over its value (§03,§04).
                call     → the test body runs; a bare `assert` gives a rich
                           failure thanks to rewriting (§13).
                teardown → generators resume PAST their `yield` (§04), in
                           reverse order; function-scoped fixtures finalize now,
                           session-scoped ones wait until the very end.

4. REPORT     Outcomes become dots / F / s. Summary printed, exit code set
              for CI. Session-scoped teardowns (db_engine.dispose) run last.

Read as a single sentence: TOML configures the run and names your markers; conftest.py supplies shared fixtures and hooks without imports; pytest collects your test functions into a session/module/function tree of objects; for each test it lazily builds a scoped fixture graph — using yield to interleave setup and teardown and scope to decide how singleton-like each fixture is — runs the body with introspected assertions, and reports a structured result.