httpclient-interception
A .NET library for intercepting and stubbing HTTP requests made by HttpClient, primarily for testing purposes.
What is httpclient-interception?
HttpClient Interception is a .NET library that intercepts HTTP requests made by the HttpClient class, allowing developers to return stub responses. It solves the problem of testing applications that rely on external HTTP services by eliminating the need for a real server, making tests faster and more deterministic.
.NET developers writing integration or functional tests for applications that use HttpClient to call external APIs, particularly those working with ASP.NET Core and IHttpClientFactory.
Developers choose this library because it integrates natively with HttpClient and .NET's DI system, offers a clean fluent API and JSON bundle support for configuration, and is lightweight with no external server dependencies, leading to reliable and performant tests.
Overview
A .NET library for intercepting server-side HTTP requests
Use Cases
Best For
- Stubbing external API calls in .NET integration tests
- Testing ASP.NET Core applications that use IHttpClientFactory
- Simulating HTTP faults and error responses for resilience testing
- Managing complex HTTP stub configurations via JSON bundle files
- Writing deterministic tests without network dependencies
- Intercepting HttpClient requests in .NET Standard and .NET Framework projects
Not Ideal For
- Testing applications that require actual HTTP server interactions, such as testing network latency, proxy configurations, or third-party services with dynamic responses.
- Projects using HTTP clients other than HttpClient, like WebClient, RestSharp, or language-specific libraries in non-.NET environments.
- Scenarios where mocking at the interface level (e.g., with Moq) is preferred for pure unit tests over HTTP interception.
- Legacy .NET projects targeting frameworks older than .NET Framework 4.7.2, as the library requires .NET Standard 2.0 or later.
Pros & Cons
Pros
Uses HttpRequestInterceptionBuilder for declarative setup, making it intuitive to define request matches and stub responses directly in C# code, as shown in the minimal example with JSON content.
Supports defining request/response pairs in JSON files, simplifying management of multiple stubs for complex test scenarios without cluttering test code, with a full JSON schema provided.
Works with IHttpClientFactory and .NET's DI container via custom filters, enabling interception in ASP.NET Core applications without modifying production code, as demonstrated in the sample application.
No actual HTTP server is required, reducing resource usage and making tests faster; benchmarks show interception times in microseconds for common operations like JSON retrieval.
Cons
Only intercepts requests made via HttpClient, so it cannot stub calls from alternative HTTP clients like WebClient or third-party libraries, limiting its use in heterogeneous codebases.
Stubbed responses are predefined and static; simulating dynamic behaviors or stateful interactions (e.g., changing data per request) requires additional custom logic, which isn't built-in.
Integrating with IHttpClientFactory requires implementing a custom IHttpMessageHandlerBuilderFilter, which can be non-trivial and error-prone for developers unfamiliar with .NET's HTTP handler pipeline.
Frequently Asked Questions
Related Projects
AutoMapperA convention-based object-object mapper in .NET.
HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities
FluentValidationA popular .NET validation library for building strongly-typed validation rules.
AngleSharp:angel: The ultimate angle brackets parser library parsing HTML5, MathML, SVG and CSS to construct a DOM based on the official W3C specifications.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.