Pytest conftest.py organization for large test suites

<p>My pytest test suite is growing and I'm having trouble managing shared fixtures. I need to organize conftest.py files across a test hierarchy, understand fixture scoping, and share fixtures between different test modules without circular imports.</p>

<p>Use scoped conftest.py files at different directory levels:</p> <div class="highlight"><pre><span></span><code>tests/ conftest.py # session-scoped: engine, db schema fixtures/ users.py # user factories traces.py # trace factories unit/ conftest.py # unit test specific overrides test_tags.py integration/ conftest.py # integration-specific: real DB session test_search.py </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># tests/conftest.py — session-scoped shared fixtures</span> <span class="kn">import</span><span class="w"> </span><span class="nn">pytest</span> <span class="kn">import</span><span class="w"> </span><span class="nn">pytest_asyncio</span> <span class="nd">@pytest_asyncio</span><span class="o">.</span><span class="n">fixture</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s1">'session'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">engine</span><span class="p">():</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">create_async_engine</span><span class="p">(</span><span class="n">TEST_DB_URL</span><span class="p">)</span> <span class="k">async</span> <span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span> <span class="k">await</span> <span class="n">conn</span><span class="o">.</span><span class="n">run_sync</span><span class="p">(</span><span class="n">Base</span><span class="o">.</span><span class="n">metadata</span><span class="o">.</span><span class="n">create_all</span><span class="p">)</span> <span class="k">yield</span> <span class="n">engine</span> <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">dispose</span><span class="p">()</span> <span class="nd">@pytest_asyncio</span><span class="o">.</span><span class="n">fixture</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s1">'session'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">seed_user</span><span class="p">(</span><span class="n">engine</span><span class="p">):</span> <span class="k">async</span> <span class="k">with</span> <span class="n">async_sessionmaker</span><span class="p">(</span><span class="n">engine</span><span class="p">)()</span> <span class="k">as</span> <span class="n">sess</span><span class="p">:</span> <span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">email</span><span class="o">=</span><span class="s1">'test@example.com'</span><span class="p">,</span> <span class="n">is_seed</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="n">sess</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">user</span><span class="p">)</span> <span class="k">await</span> <span class="n">sess</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="k">await</span> <span class="n">sess</span><span class="o">.</span><span class="n">refresh</span><span class="p">(</span><span class="n">user</span><span class="p">)</span> <span class="k">return</span> <span class="n">user</span> <span class="c1"># tests/fixtures/traces.py — factory fixtures</span> <span class="kn">import</span><span class="w"> </span><span class="nn">pytest_asyncio</span> <span class="nd">@pytest_asyncio</span><span class="o">.</span><span class="n">fixture</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">sample_trace</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">seed_user</span><span class="p">):</span> <span class="n">trace</span> <span class="o">=</span> <span class="n">Trace</span><span class="p">(</span> <span class="n">title</span><span class="o">=</span><span class="s1">'Test trace'</span><span class="p">,</span> <span class="n">context_text</span><span class="o">=</span><span class="s1">'Test context'</span><span class="p">,</span> <span class="n">solution_text</span><span class="o">=</span><span class="s1">'Test solution'</span><span class="p">,</span> <span class="n">contributor_id</span><span class="o">=</span><span class="n">seed_user</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">status</span><span class="o">=</span><span class="s1">'validated'</span><span class="p">,</span> <span class="p">)</span> <span class="n">session</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">trace</span><span class="p">)</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span> <span class="k">return</span> <span class="n">trace</span> </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># pytest.ini</span> <span class="k">[pytest]</span> <span class="na">asyncio_mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">auto</span> <span class="na">testpaths</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">tests</span> </code></pre></div> <p>Key points: - <code>scope='session'</code> fixtures run once for the entire test session — use for expensive setup - <code>scope='function'</code> (default) resets between tests — use for DB state - Fixtures can be in separate files and imported into conftest.py - <code>pytest_asyncio.fixture</code> required for async fixtures (not just <code>pytest.fixture</code>)</p>