Triage for dotnet/runtime#115697 by Mr0N

[MihuBot]

Triage for dotnet/runtime#115697.
Last updated: 2025-05-18_23-00-47

[API Proposal]: IHttpClient by Mr0N
[Tool] Searching for IHttpClient interface, HttpClient interface proposal, mocking HttpClient, HttpClient testability, HttpClient abstraction
[Tool] Found 31 issues, 44 comments, 39 returned results (7579 ms)
[Tool] Obtained 2 comments for issue #25884: Backing up HttpClient by an interface
[Tool] Obtained 157 comments for issue #14535: An simple way to mock an httpClient.GetAsync(..) method for unit tests?

Here are the most relevant related issues and discussions for triaging #115697 ([API Proposal]: IHttpClient):

---

1. Issue #14535 - An simple way to mock an httpClient.GetAsync(..) method for unit tests? (157 comments)

Summary:
This is the canonical, long-running discussion about the desire for an IHttpClient interface or similar abstraction to make HttpClient easier to mock for unit testing. The thread includes:

• Many developers expressing frustration that HttpClient is not easily mockable via standard mocking frameworks, since it does not have an interface and its key methods are not virtual.
• The official guidance from .NET team members and community experts is to mock or fake the HttpMessageHandler and inject it into HttpClient for testing, rather than mocking HttpClient itself.
• Several community libraries (notably RichardSzalay.MockHttp and HttpClient.Helpers) are recommended for this purpose.
• There is significant debate about discoverability and ease-of-use: many developers find the handler-based approach non-intuitive and would prefer an interface on HttpClient for consistency with other .NET APIs.
• The .NET team explains that adding an interface to HttpClient is problematic for versioning and would not necessarily improve testability, since the handler is the true abstraction point.
• Some suggest that developers should wrap HttpClient in their own abstraction if they need an interface, or design their code to depend on higher-level abstractions.
• The thread includes code samples, alternative patterns, and a variety of opinions, but the conclusion is that the current design is intentional and not likely to change.

Key Quotes:

• "Mocks should use HttpMessageHandler. It also greatly simplifies the methods a mock needs to provide."
• "The API design of HttpClient does not lend itself to a pure interface-based mechanism for testing."
• "If the API is not mockable, we should fix it. But it has nothing to do with interfaces vs classes. Interface is no different than pure abstract class from mockability perspective, for all practical purposes."
• "The status quo of 'go learn the plumbing of HttpClient, which will lead you to HttpMessageHandler, etc' is a poor situation. We don't need to do this for many other libraries, etc."

---

2. Issue #25884 - Backing up HttpClient by an interface (2 comments)

Summary:
A short issue proposing that HttpClient should be backed by an interface to make it easier to mock and fake. The issue was closed as a duplicate of #14535, with a pointer to the long discussion there. A comment reiterates that mocking should be done via HttpMessageHandler.

---

3. Issue #115697 - [API Proposal]: IHttpClient (current issue)

Summary of comments so far:

• The author proposes an IHttpClient interface for easier mocking and substitution.
• A reviewer asks for motivating use cases.
• The author responds that it would allow for easier mocking in tests and future replacement.
• Another commenter points out that mocking should be done via HttpMessageHandler, as it simplifies the methods a mock needs to provide.

---

Conclusion / Guidance:

• The request for an IHttpClient interface has been raised many times over the years. The .NET team has consistently declined to add such an interface, citing versioning concerns and the design intent that HttpMessageHandler is the extensibility and testability point.
• The recommended approach for unit testing code that uses HttpClient is to inject a custom or mocked HttpMessageHandler into the HttpClient constructor. Libraries like MockHttp make this easier.
• If a higher-level abstraction is needed (e.g., for business logic or to decouple from HttpClient), it is recommended that developers define their own interface and adapter/wrapper as appropriate for their application.
• The discoverability and ergonomics of this approach are acknowledged as pain points, but the design is considered stable and unlikely to change.

---

Related links for further reading:

• RichardSzalay.MockHttp
• HttpClient.Helpers

---

Summary Table:

Issue/PR #	Title/Link	Main Discussion Points	Conclusion
#14535	Mocking HttpClient	Extensive debate on testability, interfaces, and handlers	Use HttpMessageHandler for mocking; no plans for IHttpClient
#25884	Backing up HttpClient by an interface	Short, closed as duplicate	See #14535
#115697	[API Proposal]: IHttpClient	Current proposal, similar arguments	See above; handler-based mocking is recommended

---

If you need a concise summary for triage:
This proposal is a duplicate of long-standing requests for an IHttpClient interface. The .NET team has repeatedly declined to add such an interface, recommending instead that developers use HttpMessageHandler for mocking and testability. See #14535 for the canonical discussion.