Diagnosing Pytest Fixture-Resolution and Collection Failures

Your suite fails before a single test runs: fixture 'db_conn' not found, or pytest --collect-only shows half your tests missing, or a fixture runs far more often than its scope says it should. These failures look mysterious because pytest's fixture discovery is directory-based and mostly invisible until it breaks. The useful takeaway: nearly all of these problems are diagnosable with two commands (--collect-only and --fixtures) and a small set of rules about where conftest.py files live.

Examples below assume pytest 7.x/8.x. Exact error wording varies across versions, so match messages against the version pinned in your project.

Recognizable conditions

• fixture 'x' not found error at setup time, with a list of "available fixtures" that doesn't include yours.
• Collection errors (E lines) when running pytest --collect-only, often an import error inside a conftest.py.
• Tests silently not collected — no error, just fewer items than expected.
• A fixture executing more or fewer times than expected, or state leaking between tests that should be isolated.

Cause-to-symptom map

Ordered checks

1. Confirm what is collected. From the project root, run pytest --collect-only -q. No special permissions needed. Verify the expected test count and node IDs appear. If items are missing here, the problem is collection, not fixtures — check file and function naming first.
2. List visible fixtures. Run pytest --fixtures path/to/test_file.py (substitute the actual test file). This lists every fixture visible from that location. If your fixture is absent, the cause is visibility or naming, not the fixture body.
3. Check conftest placement. A fixture in conftest.py is visible only to tests in that directory and below. A fixture defined in tests/unit/conftest.py is invisible to tests/integration/. Verify the conftest is an ancestor of the test file, not a sibling.
4. Check plugin loading. If the fixture comes from a plugin, run pytest --trace-config and confirm the plugin registers. Check whether PYTEST_DISABLE_PLUGIN_AUTOLOAD is set in the environment or CI — it changes which fixtures exist at all.
5. For scope bugs, check declared scope. Remember the constraint: a session-scoped fixture cannot depend on a function-scoped one. If state leaks between tests, isolate the first failure with pytest -x --lf.

Fixes tied to findings

• Fixture not visible: move it to a higher-level conftest.py (e.g., tests/conftest.py) so it covers all directories that need it.
• Plugin fixture missing: install the plugin in the active environment, or explicitly load it with -p pluginname if autoload is disabled.
• Scope mismatch: change the declaration, e.g. @pytest.fixture(scope="module") for a resource shared across a file, and remove any dependency on narrower-scoped fixtures.
• conftest import error: fix the import at the top of the traceback first; one broken conftest aborts collection for its entire subtree, producing cascading errors that disappear once the root cause is fixed.

Escalation criteria

If --fixtures shows the fixture but resolution still fails, suspect a plugin conflict or a swallowed conftest import error. Run pytest -rA -v and read the warnings summary, then bisect plugins by disabling them one at a time with -p no:<plugin>. At that point the problem is environmental, and it is worth capturing pip freeze and the --trace-config output for the team rather than continuing to edit fixtures.

Verifying the fix

After any change, re-run pytest --collect-only -q and confirm the expected node IDs, then pytest --fixtures <file> to confirm the fixture is listed. Reproduce the original failure with pytest -x -v and confirm the first error is gone, then run the full suite with pytest -rA to check for regressions and unexpected skips.