Mocking external HTTP calls with respx

<p>Tests call external APIs (OpenAI, Stripe, GitHub). Real API calls make tests slow, expensive, and flaky. Need to intercept HTTP calls at the transport layer so the application code doesn't need to change.</p>

<p>Use <code>respx</code> to mock <code>httpx</code> requests at the transport level:</p> <div class="highlight"><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">respx</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">httpx</span> <span class="kn">from</span><span class="w"> </span><span class="nn">unittest.mock</span><span class="w"> </span><span class="kn">import</span> <span class="n">patch</span> <span class="c1"># Basic mock with respx</span> <span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_embedding_service</span><span class="p">():</span> <span class="k">with</span> <span class="n">respx</span><span class="o">.</span><span class="n">mock</span><span class="p">()</span> <span class="k">as</span> <span class="n">mock</span><span class="p">:</span> <span class="n">mock</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">'https://api.openai.com/v1/embeddings'</span><span class="p">)</span><span class="o">.</span><span class="n">mock</span><span class="p">(</span> <span class="n">return_value</span><span class="o">=</span><span class="n">httpx</span><span class="o">.</span><span class="n">Response</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="n">json</span><span class="o">=</span><span class="p">{</span> <span class="s1">'data'</span><span class="p">:</span> <span class="p">[{</span><span class="s1">'embedding'</span><span class="p">:</span> <span class="p">[</span><span class="mf">0.1</span><span class="p">]</span> <span class="o">*</span> <span class="mi">1536</span><span class="p">,</span> <span class="s1">'index'</span><span class="p">:</span> <span class="mi">0</span><span class="p">}],</span> <span class="s1">'model'</span><span class="p">:</span> <span class="s1">'text-embedding-3-small'</span><span class="p">,</span> <span class="s1">'usage'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'prompt_tokens'</span><span class="p">:</span> <span class="mi">8</span><span class="p">,</span> <span class="s1">'total_tokens'</span><span class="p">:</span> <span class="mi">8</span><span class="p">},</span> <span class="p">})</span> <span class="p">)</span> <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">embed_text</span><span class="p">(</span><span class="s1">'test query'</span><span class="p">)</span> <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">result</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1536</span> <span class="k">assert</span> <span class="n">mock</span><span class="o">.</span><span class="n">called</span> <span class="c1"># Mock with pattern matching</span> <span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_github_api</span><span class="p">():</span> <span class="k">with</span> <span class="n">respx</span><span class="o">.</span><span class="n">mock</span><span class="p">()</span> <span class="k">as</span> <span class="n">mock</span><span class="p">:</span> <span class="n">mock</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'https://api.github.com/user'</span><span class="p">)</span><span class="o">.</span><span class="n">mock</span><span class="p">(</span> <span class="n">return_value</span><span class="o">=</span><span class="n">httpx</span><span class="o">.</span><span class="n">Response</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s1">'login'</span><span class="p">:</span> <span class="s1">'testuser'</span><span class="p">,</span> <span class="s1">'id'</span><span class="p">:</span> <span class="mi">12345</span><span class="p">})</span> <span class="p">)</span> <span class="n">mock</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">respx</span><span class="o">.</span><span class="n">pattern</span><span class="o">.</span><span class="n">M</span><span class="p">(</span><span class="s1">'https://api.github.com/repos/**'</span><span class="p">))</span><span class="o">.</span><span class="n">mock</span><span class="p">(</span> <span class="n">return_value</span><span class="o">=</span><span class="n">httpx</span><span class="o">.</span><span class="n">Response</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s1">'stargazers_count'</span><span class="p">:</span> <span class="mi">100</span><span class="p">})</span> <span class="p">)</span> <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">get_github_user</span><span class="p">(</span><span class="n">token</span><span class="o">=</span><span class="s1">'test-token'</span><span class="p">)</span> <span class="k">assert</span> <span class="n">user</span><span class="o">.</span><span class="n">login</span> <span class="o">==</span> <span class="s1">'testuser'</span> <span class="c1"># Fixture for reuse</span> <span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span> <span class="k">def</span><span class="w"> </span><span class="nf">mock_openai</span><span class="p">():</span> <span class="k">with</span> <span class="n">respx</span><span class="o">.</span><span class="n">mock</span><span class="p">()</span> <span class="k">as</span> <span class="n">mock</span><span class="p">:</span> <span class="n">mock</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">'https://api.openai.com/v1/embeddings'</span><span class="p">)</span><span class="o">.</span><span class="n">mock</span><span class="p">(</span> <span class="n">return_value</span><span class="o">=</span><span class="n">httpx</span><span class="o">.</span><span class="n">Response</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="n">json</span><span class="o">=</span><span class="p">{</span> <span class="s1">'data'</span><span class="p">:</span> <span class="p">[{</span><span class="s1">'embedding'</span><span class="p">:</span> <span class="p">[</span><span class="mf">0.0</span><span class="p">]</span> <span class="o">*</span> <span class="mi">1536</span><span class="p">}]</span> <span class="p">})</span> <span class="p">)</span> <span class="k">yield</span> <span class="n">mock</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_with_fixture</span><span class="p">(</span><span class="n">mock_openai</span><span class="p">):</span> <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">embed_text</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</span> <span class="k">assert</span> <span class="n">result</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">assert</span> <span class="n">mock_openai</span><span class="o">.</span><span class="n">calls</span><span class="o">.</span><span class="n">last</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">url</span><span class="o">.</span><span class="n">path</span> <span class="o">==</span> <span class="s1">'/v1/embeddings'</span> </code></pre></div> <p><code>respx.mock()</code> intercepts all httpx requests in the context. Use <code>respx.mock(assert_all_called=True)</code> to ensure all mocked routes were called. Works with both sync and async httpx clients.</p>