https://github.com/oatsoda/teepee
A fluent API to configure HttpClients for unit testing.
https://github.com/oatsoda/teepee
httpclient injection mocking unit-testing
Last synced: 2 months ago
JSON representation
A fluent API to configure HttpClients for unit testing.
- Host: GitHub
- URL: https://github.com/oatsoda/teepee
- Owner: oatsoda
- Created: 2020-10-03T10:58:32.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-04-25T17:29:59.000Z (2 months ago)
- Last Synced: 2026-04-25T18:09:26.358Z (2 months ago)
- Topics: httpclient, injection, mocking, unit-testing
- Language: C#
- Homepage:
- Size: 315 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# TeePee
NuGet: [](https://www.nuget.org/packages/TeePee/)
A fluent API to configure HttpClients for unit testing.
[](https://dev.azure.com/oatsoda/TeePee/_build/latest?definitionId=5&branchName=main)
# TeePee.Refit
Also, [TeePee.Refit](/TeePee.Refit/) an add on adaptor when production code is using Refit.
# Documentation
## Mocking
Everything in TeePee starts by creating a `TeePeeBuilder`.
```csharp
var teePeeBuilder = new TeePeeBuilder();
```
### Matching requests
Add requests that you want to support by using the fluent API to specify as little or as much you want to match on:
```csharp
teePeeBuilder.ForRequest("https://some.api/path/resource", HttpMethod.Post)
.ThatHasBody(new { Value = 12 })
.ThatContainsQueryParam("filter", "those")
.ThatContainsHeader("ApiKey", "123abc-xyz987");
```
#### Query strings
Query strings can either be included in the URL:
```csharp
teePeeBuilder.ForRequest("https://some.api/path/resource?filter=those")
```
or by matching using the `ContainsQueryParam`
```csharp
teePeeBuilder.ForRequest("https://some.api/path/resource", HttpMethod.Post)
.ThatContainsQueryParam("filter", "those")
```
You cannot combine both though. Once you specify `ContainingQueryParam` then incoming requests at execution-time will have their query string removed when attempting to match a rule which is using `ContainingQueryParam`.
### Returning responses
The response to a matching request is set using the `Responds()` fluent method:
```csharp
teePeeBuilder.ForRequest("https://some.api/path/resource", HttpMethod.Post)
.Responds()
.WithStatus(HttpStatusCode.OK)
.WithBody(new { Result = "Done" })
.WithHeader("Set-Cookie", "Yum");
```
#### Defaults
If you don't specify a Status Code in the response, the default is `204 NoContent`. (i.e. it matched, but you didn't tell it what status to return)
If you don't call `Responds()` then the default response Status Code is `202 Accepted`. (i.e. it matched, but you didn't tell it to respond)
### Defaults for no matches & Strict Mode
If there is no match for a request, the default is to response with a Status Code is `404 NotFound`. (This is configurable using the `WithDefaultResponse` on `TeePeeBuilder`)
## Unit Testing
It's worth [making sure you fully understand](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-requests?view=aspnetcore-3.1#consumption-patterns) the various `HttpClientFactory` mechanisms for registering and resolving `HttpClient`s before reading this.
### Classicist/Detroit/Black Box vs Mockist/London/White Box
TeePee is focused on the Classicist/Detroit/Black Box approach to unit testing. It can be used for Mockist/London/White Box approaches, but be aware that due to the way `HttpClientFactory` is implemented, you may find there are limitations if you are planning to mock and inject your dependencies into your test subject manually.
### Verifying
When Black Box unit testing, it's recommended to be as passive with mocked dependencies as possible. This means, where possible, not asserting specific details about calls to the HttpClient but instead mocking the requests and responses and instead asserting the outcomes of the Subject Under Test.
This isn't always possible - for example in a Fire and Forget situation where the behaviour is that the Subject Under Test is required to call an external HTTP service, but the SUT itself doesn't indicate this was done correctly.
In this case, you can set up a tracker using `TrackRequest()` to make simple verification of the requests that you set up.
```csharp
var requestTracker = teePeeBuilder.ForRequest("https://some.api/path/resource", HttpMethod.Post)
.TrackRequets();
// Execute SUT
reququestTracker.WasCalled(1);
```
### Injection during Unit Tests
As stated above, TeePee is more focused on the Classicist/Detroit/Black Box of testing approach and this allows unit test coverage of DI registrations for `HttpClientFactory`. You can of course still manually inject should you wish to.
### Manual Injection
Once you have finished setting up one or more requests in you `TeePeeBuilder` then depending on your `HttpClientFactory` approach, you can create the relevant objects to inject:
#### Basic HttpClient
Basic HttpClient usage is very limited and is only really meant for intermediate refactoring stages. You probably won't want to use this in your production code.
```csharp
var teePee = await teePeeBuilder.Build();
var httpClientFactory = teePee.Manual().CreateHttpClientFactory();
var subjectUnderTest = new UserController(httpClientFactory);
```
#### Named HttpClient
For Named HttpClient instances, you need to specify the expected Name of the instance when creating the `TeePeeBuilder`:
```csharp
var teePeeBuilder = new TeePeeBuilder("GitHub");
// Setup request matching...
var teePee = await teePeeBuilder.Build();
var httpClientFactory = teePee.Manual().CreateHttpClientFactory();
var subjectUnderTest = new UserController(httpClientFactory);
```
#### Typed HttpClient
For Typed HttpClient instances, you need to create the HttpClient instead of the HttpClientFactory:
```csharp
var teePeeBuilder = new TeePeeBuilder();
// Setup request matching...
var teePee = await teePeeBuilder.Build();
var typedHttpClient = new MyTypedHttpClient(teePee.Manual().CreateClient());
var subjectUnderTest = new UserController(typedHttpClient);
```
#### HttpClient BaseAddress
If you are wanting to specify the `BaseAddress` in your `HttpClient` and use Relative URLs in your Subject Under Test when calling the HttpClient, you can set TeePee up to ALSO configure this in your tests. (Note, this obviously means you are not covering this in your tests, it is just so that the HttpClient accepts Relative URLs.
To do this, pass a dummy Base Address into the `Manual()` call.
```csharp
var teePeeBuilder = new TeePeeBuilder("GitHub");
teePeeBuilder.ForRequest("https://some.api/path/resource", HttpMethod.Get)
.Responds()
.WithStatusCode(HttpStatusCode.OK);
var teePee = await teePeeBuilder.Build();
var typedHttpClient = new MyTypedHttpClient(teePee.Manual("https://some.api").CreateClient());
var subjectUnderTest = new UserController(typedHttpClient);
```
### Auto Injection
Injecting automatically allows you to cover the startup DI registrations as part of your unit tests. This is mostly done using the `Resolve` static class.
#### Basic HttpClient
Basic HttpClient usage is very limited and is only really meant for intermediate refactoring stages. You probably won't want to use this in your production code.
```csharp
var subjectUnderTest = await Resolve.WithDefaultClient(teePeeBuilder);
```
#### Named HttpClient
For Named HttpClient instances, you need to specify the expected Name of the instance when creating the `TeePeeBuilder`:
```csharp
var teePeeBuilder = new TeePeeBuilder("GitHub");
// Setup request matching...
var subjectUnderTest = await Resolve.WithNamedClients(
services =>
{
// Call your production code/extension methods here - but for this example we're inlining it - see examples for further details
// Expect any intermediate dependencies to also be registered
services.AddHttpClient("GitHub, c => c.BaseAddress = "https://external.api");
},
teePeeBuilder);
```
#### Typed HttpClient
For Typed HttpClients, your unit tests unfortunately will need to know which Type is the HttpClient (therefore exposing a bit of internal implementation detail into your tests):
```csharp
var teePeeBuilder = new TeePeeBuilder();
// Setup request matching...
var subjectUnderTest = await Resolve.WithTypedClient(
services =>
{
// Call your production code/extension methods here - but for this example we're inlining it - see examples for further details
// Expect any intermediate dependencies to also be registered
services.AddHttpClient(c => c.BaseAddress = "https://external.api");
},
teePeeBuilder);
```
## Multiple HttpClient dependencies
See [Examples](https://github.com/oatsoda/TeePee/tree/main/TeePee/Examples) for demonstrations of how to apply the above Manual or Auto injection when you have multiple HttpClient dependencies.