How to Mock External HTTP APIs in .NET Integration Tests

The example uses the typed client registration in the test host to configure the fake primary handler. If the production registration includes additional settings, such as a base address, authentication, or delegating handlers, preserve or explicitly configure the settings required by the test.

For applications that need to replace an existing typed-client registration, inspect the service registrations and remove or override the relevant registration deliberately. Avoid leaving two conflicting registrations and assuming the intended one will always be selected.

Next, write a test using xUnit:

using System.Net;
using Xunit;

public class InventoryIntegrationTests
    : IClassFixture<TestApplicationFactory>
{
    private readonly HttpClient _client;

    public InventoryIntegrationTests(
        TestApplicationFactory factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetInventory_ReturnsProductDetails()
    {
        var response = await _client.GetAsync(
            "/api/products/10");

        Assert.Equal(
            HttpStatusCode.OK,
            response.StatusCode);

        var item = await response.Content
            .ReadFromJsonAsync<InventoryItem>();

        Assert.NotNull(item);
        Assert.Equal(10, item.Id);
        Assert.Equal("Keyboard", item.Name);
        Assert.Equal(25, item.AvailableQuantity);
    }
}

This test sends an HTTP request through the application's test server. When the endpoint calls InventoryClient, the fake handler supplies the inventory response.

The test verifies the application-level result rather than only checking the HTTP client in isolation.

For this example to compile, the application must define an endpoint at /api/products/{id} that calls InventoryClient, and Program must be accessible to the test project. A common approach is to add public partial class Program { } to the application entry-point file when required by the test project.

Test External API Failures

A successful response is only one part of an HTTP integration test suite. External services can return errors, and your application should respond predictably.

For example, you can create a handler that always returns a server error:

using System.Net;

public sealed class InventoryErrorHandler
    : HttpMessageHandler
{
    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        return Task.FromResult(
            new HttpResponseMessage(
                HttpStatusCode.ServiceUnavailable));
    }
}

Because InventoryClient calls EnsureSuccessStatusCode(), a 503 response causes an HttpRequestException.

A test can verify that behavior directly:

using System.Net;
using Xunit;

public class InventoryClientTests
{
    [Fact]
    public async Task GetItemAsync_ThrowsForServerError()
    {
        using var httpClient = new HttpClient(
            new InventoryErrorHandler())
        {
            BaseAddress =
                new Uri("https://inventory.example.test")
        };

        var inventoryClient =
            new InventoryClient(httpClient);

        await Assert.ThrowsAsync<HttpRequestException>(
            () => inventoryClient.GetItemAsync(10));
    }
}

This is a focused test of the HTTP client rather than a full application integration test. Both styles are useful: client tests cover request and response handling, while application integration tests verify how controllers, services, and middleware work together.

If your application translates external service failures into domain-specific responses, test that translation too. For example, a controller might return a 503 response to its caller rather than exposing an unhandled exception.

Verify That the Application Sends the Correct Request

A fake handler can also inspect incoming requests. This helps test query parameters, HTTP methods, headers, and request bodies.

For example, an API may require a specific authorization header. A test handler can capture the request and verify that the expected header is present.

Do not put real API keys or production credentials in tests. Use dummy credentials and a controlled test configuration.

For more complex HTTP behavior, a dedicated mocking library can provide request matching and response setup with less custom code. Choose a tool that makes the test readable and does not obscure which request is expected or which response should be returned.

Regardless of the library, verify both sides of the interaction: the application sends the intended request, and it handles the returned response correctly.

Common Mistakes When Mocking HTTP APIs

Accidentally making real network requests

If the fake handler is not registered for the client used by the application, the test may still use the production HTTP configuration.

Make the test configuration explicit and ensure the relevant typed client uses the fake handler.

Testing only the successful response

External APIs can return errors, time out, or provide unexpected data. Include tests for non-success status codes, invalid JSON, and cancellation where those cases matter to the application.

Mocking too much of the application

If every service and repository is replaced with a mock, the test may no longer verify meaningful application integration.

Keep the ASP.NET Core pipeline and the components you want to test real. Replace only the external dependency that needs to be isolated.

Assuming a fake handler tests network behavior

A fake HttpMessageHandler does not test DNS resolution, TLS negotiation, real connection pooling, or the external service's behavior.

Use appropriate staging or contract tests when you need confidence in those areas.

Sharing mutable fake state between parallel tests

A handler that stores requests or changes its response based on previous calls can cause tests to interfere with one another if it is shared.

Keep test state isolated, reset it deliberately, or create a separate handler for each test when necessary.

Best Practices for Reliable HTTP Integration Tests

Use typed HTTP clients to keep external API logic separate from application endpoints. Configure test handlers explicitly, and use predictable responses that describe the scenario under test.

Test successful responses, error responses, request cancellation, and malformed payloads when relevant. Avoid depending on a live external service for ordinary automated integration tests.

Keep the application pipeline real enough to verify the behavior you care about. A test that exercises the routing, dependency injection, service layer, and response mapping provides more confidence than a test that only invokes a method directly.

Finally, remember that mocks verify your application's assumptions about an external API. They do not prove that the external API still follows those assumptions. Add contract checks or targeted tests against a controlled environment when compatibility is important.

Conclusion

Mocking external HTTP APIs in .NET makes integration tests faster, more predictable, and easier to repeat. Replacing HttpMessageHandler allows you to control HTTP responses while keeping the rest of the ASP.NET Core application available for testing.

Use typed clients, configure fake handlers through the test host, and verify both successful responses and failure scenarios. Keep real network tests separate from ordinary integration tests so each test has a clear purpose.

With this approach, you can test how your application behaves when external services succeed, fail, or return unexpected data without making your entire test suite depend on their availability.