pytest async fixtures with proper scope

<p>Async pytest fixtures are slow because they recreate expensive resources (database connections, HTTP clients) for each test. Need to understand fixture scoping in async contexts and how to share resources safely.</p>

<p>Use <code>pytest_asyncio.fixture</code> with appropriate scope levels:</p> <div class="highlight"><pre><span></span><code><span class="c1"># conftest.py</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="kn">from</span><span class="w"> </span><span class="nn">httpx</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncClient</span><span class="p">,</span> <span class="n">ASGITransport</span> <span class="c1"># Session scope: created once for entire test run</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">db_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_DATABASE_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="c1"># Module scope: once per test file</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">'module'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">seed_data</span><span class="p">(</span><span class="n">db_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">db_engine</span><span class="p">)()</span> <span class="k">as</span> <span class="n">session</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">'module@test.com'</span><span class="p">,</span> <span class="o">...</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">user</span><span class="p">)</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="k">yield</span> <span class="p">{</span><span class="s1">'user_id'</span><span class="p">:</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="p">}</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">user</span><span class="p">)</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="c1"># Function scope (default): fresh for each test</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">session</span><span class="p">(</span><span class="n">db_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">db_engine</span><span class="p">)()</span> <span class="k">as</span> <span class="n">s</span><span class="p">:</span> <span class="k">yield</span> <span class="n">s</span> <span class="k">await</span> <span class="n">s</span><span class="o">.</span><span class="n">rollback</span><span class="p">()</span> <span class="c1"># Important: pytest.ini or pyproject.toml must set asyncio_mode</span> <span class="c1"># [tool.pytest.ini_options]</span> <span class="c1"># asyncio_mode = 'auto' # or 'strict'</span> <span class="c1"># Sharing state safely across session-scoped fixtures</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">http_client</span><span class="p">(</span><span class="n">db_engine</span><span class="p">):</span> <span class="c1"># Session-scoped client shares the engine</span> <span class="n">factory</span> <span class="o">=</span> <span class="n">async_sessionmaker</span><span class="p">(</span><span class="n">db_engine</span><span class="p">)</span> <span class="k">async</span> <span class="k">with</span> <span class="n">factory</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span> <span class="n">app</span><span class="o">.</span><span class="n">dependency_overrides</span><span class="p">[</span><span class="n">get_db</span><span class="p">]</span> <span class="o">=</span> <span class="k">lambda</span><span class="p">:</span> <span class="n">session</span> <span class="k">async</span> <span class="k">with</span> <span class="n">AsyncClient</span><span class="p">(</span> <span class="n">transport</span><span class="o">=</span><span class="n">ASGITransport</span><span class="p">(</span><span class="n">app</span><span class="o">=</span><span class="n">app</span><span class="p">),</span> <span class="n">base_url</span><span class="o">=</span><span class="s1">'http://test'</span> <span class="p">)</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span> <span class="k">yield</span> <span class="n">client</span> <span class="n">app</span><span class="o">.</span><span class="n">dependency_overrides</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span> </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># pyproject.toml</span> <span class="k">[tool.pytest.ini_options]</span> <span class="n">asyncio_mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'auto'</span> <span class="k">[tool.pytest_asyncio]</span> <span class="n">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'auto'</span> </code></pre></div> <p>Session scope creates the engine once (expensive) and function scope creates a fresh session per test (cheap, isolated). Never mix function-scoped fixtures as dependencies of session-scoped fixtures — pytest will error.</p>