Skip to content

Commit da65ff1

Browse files
martincostellomartincostello
authored
Merge pull request #79 from martincostello/Update-Docs
Update docs
2 parents b60b750 + e8a9a6c commit da65ff1

File tree

4 files changed

+154
-18
lines changed

4 files changed

+154
-18
lines changed

‎README.md

Lines changed: 72 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ dotnet add package JustEat.HttpClientInterception
3131

3232
#### Request Interception
3333

34-
Below is a minimal example of intercepting a request to an HTTP API for a JSON resource to return a custom response:
34+
##### Fluent API
35+
36+
Below is a minimal example of intercepting a request to an HTTP API for a JSON resource to return a custom response using the fluent API:
3537

3638
```csharp
3739
// using JustEat.HttpClientInterception;
@@ -54,6 +56,62 @@ var json = await client.GetStringAsync("http://public.je-apis.com/terms");
5456

5557
`HttpRequestInterceptionBuilder` objects are mutable, so properties can be freely changed once a particular setup has been registered with an instance of `HttpClientInterceptorOptions` as the state is captured at the point of registration. This allows multiple responses and paths to be configured from a single `HttpRequestInterceptionBuilder` instance where multiple registrations against a common hostname.
5658

59+
##### _HTTP Bundle_ Files
60+
61+
HTTP requests to intercept can also be configured in an _"HTTP bundle"_ file, which can be used to store the HTTP requests to intercept and their corresponding responses as JSON.
62+
63+
This functionality is analogous to our [_Shock_](https://github.com/justeat/Shock "Shock") pod for iOS.
64+
65+
###### JSON
66+
67+
Below is an example bundle file, which can return content in formats such as a string, JSON and base64-encoded data.
68+
69+
The full JSON schema for HTTP bundle files can be found [here](https://raw.githubusercontent.com/justeat/httpclient-interception/master/src/HttpClientInterception/Bundles/http-request-bundle-schema.json "JSON Schema for HTTP request interception bundles for use with JustEat.HttpClientInterception.").
70+
71+
```json
72+
{
73+
"$schema": "https://raw.githubusercontent.com/justeat/httpclient-interception/master/src/HttpClientInterception/Bundles/http-request-bundle-schema.json",
74+
"id": "my-bundle",
75+
"comment": "A bundle of HTTP requests",
76+
"items": [
77+
{
78+
"id": "home",
79+
"comment": "Returns the home page",
80+
"uri": "https://www.just-eat.co.uk",
81+
"contentString": "<html><head><title>Just Eat</title></head></html>"
82+
},
83+
{
84+
"id": "terms",
85+
"comment": "Returns the Ts & Cs",
86+
"uri": "https://public.je-apis.com/terms",
87+
"contentFormat": "json",
88+
"contentJson": {
89+
"Id": 1,
90+
"Link": "https://www.just-eat.co.uk/privacy-policy"
91+
}
92+
}
93+
]
94+
}
95+
```
96+
97+
###### Code
98+
99+
```cs
100+
// using JustEat.HttpClientInterception;
101+
102+
var options = new HttpClientInterceptorOptions().RegisterBundle("my-bundle.json");
103+
104+
var client = options.CreateHttpClient();
105+
106+
// The value of html will be "<html><head><title>Just Eat</title></head></html>"
107+
var html = await client.GetStringAsync("https://www.just-eat.co.uk");
108+
109+
// The value of json will be "{\"Id\":1,\"Link\":\"https://www.just-eat.co.uk/privacy-policy\"}"
110+
var json = await client.GetStringAsync("http://public.je-apis.com/terms");
111+
```
112+
113+
Further examples of using HTTP bundles can be found in the [tests](https://github.com/justeat/httpclient-interception/blob/master/tests/HttpClientInterception.Tests/Bundles/BundleExtensionsTests.cs "BundleExtensionsTests.cs"), such as for changing the response code, the HTTP method, and matching to HTTP requests based on the request headers.
114+
57115
#### Fault Injection
58116

59117
Below is a minimal example of intercepting a request to inject an HTTP fault:
@@ -177,23 +235,24 @@ Further examples of using the library can be found by following the links below:
177235

178236
### Benchmarks
179237

180-
Generated with the [Benchmarks project](https://github.com/justeat/httpclient-interception/blob/master/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs "JustEat.HttpClientInterception benchmark code") using [BenchmarkDotNet](https://github.com/dotnet/BenchmarkDotNet "BenchmarkDotNet on GitHub.com") using commit [e189875](https://github.com/justeat/httpclient-interception/commit/e18987518f279ece7ad4631d21c5e986733fdab3 "Benchmark commit") on 14/10/2018.
238+
Generated with the [Benchmarks project](https://github.com/justeat/httpclient-interception/blob/master/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs "JustEat.HttpClientInterception benchmark code") using [BenchmarkDotNet](https://github.com/dotnet/BenchmarkDotNet "BenchmarkDotNet on GitHub.com") using commit [b60b750](https://github.com/justeat/httpclient-interception/commit/b60b750c7b63934b91a3b3e81df4b5506e3668a5 "Benchmark commit") on 24/03/2019.
181239

182240
``` ini
183-
BenchmarkDotNet=v0.11.1, OS=Windows 10.0.17763
241+
BenchmarkDotNet=v0.11.4, OS=Windows 10.0.17763.379 (1809/October2018Update/Redstone5)
184242
Intel Core i7-6700HQ CPU 2.60GHz (Skylake), 1 CPU, 8 logical and 4 physical cores
185-
.NET Core SDK=2.1.403
186-
[Host] : .NET Core 2.1.5 (CoreCLR 4.6.26919.02, CoreFX 4.6.26919.02), 64bit RyuJIT
187-
DefaultJob : .NET Core 2.1.5 (CoreCLR 4.6.26919.02, CoreFX 4.6.26919.02), 64bit RyuJIT
243+
.NET Core SDK=2.2.105
244+
[Host] : .NET Core 2.2.3 (CoreCLR 4.6.27414.05, CoreFX 4.6.27414.05), 64bit RyuJIT
245+
DefaultJob : .NET Core 2.2.3 (CoreCLR 4.6.27414.05, CoreFX 4.6.27414.05), 64bit RyuJIT
188246
```
189247

190-
| Method | Mean | Error | StdDev | Median | Gen 0 | Allocated |
191-
|---------- |----------:|----------:|----------:|----------:|-------:|----------:|
192-
| [`GetBytes`](https://github.com/justeat/httpclient-interception/blob/c09c38bad3ed5db6cfffdbaebeac33c2d286764f/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L73-L77 "Benchmark using a byte array") | 8.675 μs | 0.2513 μs | 0.7330 μs | 8.478 μs | 1.3275 | 4.13 KB |
193-
| [`GetHtml`](https://github.com/justeat/httpclient-interception/blob/c09c38bad3ed5db6cfffdbaebeac33c2d286764f/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L79-L83 "Benchmark using HTML") | 9.406 μs | 0.2480 μs | 0.7313 μs | 9.141 μs | 1.4191 | 4.41 KB |
194-
| [`GetJson`](https://github.com/justeat/httpclient-interception/blob/c09c38bad3ed5db6cfffdbaebeac33c2d286764f/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L85-L90 "Benchmark using JSON") | 17.653 μs | 0.3501 μs | 0.5849 μs | 17.428 μs | 3.0518 | 9.44 KB |
195-
| [`GetStream`](https://github.com/justeat/httpclient-interception/blob/c09c38bad3ed5db6cfffdbaebeac33c2d286764f/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L92-L98 "Benchmark using a stream") | 74.822 μs | 1.4916 μs | 3.7695 μs | 73.784 μs | 1.0986 | 3.43 KB |
196-
| [`Refit`](https://github.com/justeat/httpclient-interception/blob/c09c38bad3ed5db6cfffdbaebeac33c2d286764f/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L100-L104 "Benchmark using Refit") | 43.953 μs | 0.8722 μs | 0.9694 μs | 44.026 μs | 4.8218 | 14.97 KB |
248+
249+
| Method | Mean | Error | StdDev | Median | Gen 0/1k Op | Gen 1/1k Op | Gen 2/1k Op | Allocated Memory/Op |
250+
|---------- |----------:|----------:|----------:|----------:|------------:|------------:|------------:|--------------------:|
251+
| [`GetBytes`](https://github.com/justeat/httpclient-interception/blob/b60b750c7b63934b91a3b3e81df4b5506e3668a5/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L70-L74 "Benchmark using a byte array") | 5.656 μs | 0.1083 μs | 0.1483 μs | 5.647 μs | 1.0071 | - | - | 3.12 KB |
252+
| [`GetHtml`](https://github.com/justeat/httpclient-interception/blob/b60b750c7b63934b91a3b3e81df4b5506e3668a5/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L76-L80 "Benchmark using HTML") | 7.275 μs | 0.1091 μs | 0.1021 μs | 7.293 μs | 1.2054 | - | - | 3.72 KB |
253+
| [`GetJson`](https://github.com/justeat/httpclient-interception/blob/b60b750c7b63934b91a3b3e81df4b5506e3668a5/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L82-L87 "Benchmark using JSON") | 16.918 μs | 0.3353 μs | 0.8473 μs | 16.572 μs | 3.1738 | - | - | 9.77 KB |
254+
| [`GetStream`](https://github.com/justeat/httpclient-interception/blob/b60b750c7b63934b91a3b3e81df4b5506e3668a5/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L89-L95 "Benchmark using a stream") | 62.880 μs | 1.2273 μs | 1.5072 μs | 62.892 μs | 1.0986 | - | - | 3.43 KB |
255+
| [`Refit`](https://github.com/justeat/httpclient-interception/blob/b60b750c7b63934b91a3b3e81df4b5506e3668a5/tests/HttpClientInterception.Benchmarks/InterceptionBenchmarks.cs#L97-L101 "Benchmark using Refit") | 43.055 μs | 0.8330 μs | 0.7792 μs | 42.704 μs | 4.9438 | - | - | 15.33 KB |
197256

198257
## Feedback
199258

‎tests/HttpClientInterception.Tests/Examples.cs

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,11 @@ public static async Task Intercept_Http_Get_For_Json_Object()
2525
{
2626
// Arrange
2727
var options = new HttpClientInterceptorOptions();
28+
var builder = new HttpRequestInterceptionBuilder();
2829

29-
var builder = new HttpRequestInterceptionBuilder()
30-
.Requests().ForGet().ForHttps().ForHost("public.je-apis.com").ForPath("terms")
31-
.Responds().WithJsonContent(new { Id = 1, Link = "https://www.just-eat.co.uk/privacy-policy" })
32-
.RegisterWith(options);
30+
builder.Requests().ForGet().ForHttps().ForHost("public.je-apis.com").ForPath("terms")
31+
.Responds().WithJsonContent(new { Id = 1, Link = "https://www.just-eat.co.uk/privacy-policy" })
32+
.RegisterWith(options);
3333

3434
string json;
3535

@@ -623,5 +623,41 @@ public static async Task Use_Custom_Request_Matching_With_Priorities()
623623
(await client.GetStringAsync("https://www.just-eat.co.uk/")).ShouldContain("Fourth");
624624
}
625625
}
626+
627+
[Fact]
628+
public static async Task Intercept_Http_Requests_Registered_Using_A_Bundle_File()
629+
{
630+
// Arrange
631+
var options = new HttpClientInterceptorOptions()
632+
.RegisterBundle("example-bundle.json")
633+
.ThrowsOnMissingRegistration();
634+
635+
// Act
636+
string content;
637+
638+
using (var client = options.CreateHttpClient())
639+
{
640+
content = await client.GetStringAsync("https://www.just-eat.co.uk/");
641+
}
642+
643+
// Assert
644+
content.ShouldBe("<html><head><title>Just Eat</title></head></html>");
645+
646+
// Act
647+
using (var client = options.CreateHttpClient())
648+
{
649+
client.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
650+
client.DefaultRequestHeaders.Add("Authorization", "bearer my-token");
651+
client.DefaultRequestHeaders.Add("User-Agent", "My-App/1.0.0");
652+
653+
content = await client.GetStringAsync("https://api.github.com/orgs/justeat");
654+
}
655+
656+
// Assert
657+
var organization = JObject.Parse(content);
658+
organization.Value<int>("id").ShouldBe(1516790);
659+
organization.Value<string>("login").ShouldBe("justeat");
660+
organization.Value<string>("url").ShouldBe("https://api.github.com/orgs/justeat");
661+
}
626662
}
627663
}

‎tests/HttpClientInterception.Tests/JustEat.HttpClientInterception.Tests.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
<TargetFrameworks>netcoreapp2.2</TargetFrameworks>
88
</PropertyGroup>
99
<ItemGroup>
10-
<Content Include="xunit.runner.json;Bundles\*.json" CopyToOutputDirectory="PreserveNewest" />
10+
<Content Include="example-bundle.json;xunit.runner.json;Bundles\*.json" CopyToOutputDirectory="PreserveNewest" />
1111
<Content Include="..\..\src\HttpClientInterception\Bundles\http-request-bundle-schema.json" CopyToOutputDirectory="PreserveNewest" />
1212
</ItemGroup>
1313
<ItemGroup>

‎tests/HttpClientInterception.Tests/example-bundle.json

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/justeat/httpclient-interception/master/src/HttpClientInterception/Bundles/http-request-bundle-schema.json",
3+
"id": "example-http-request-bundle",
4+
"comment": "An example bundle of HTTP requests to be intercepted.",
5+
"version": 1,
6+
"items": [
7+
{
8+
"id": "html",
9+
"comment": "An HTTP request that returns an HTML string.",
10+
"uri": "https://www.just-eat.co.uk/",
11+
"contentString": "<html><head><title>Just Eat</title></head></html>"
12+
},
13+
{
14+
"id": "json",
15+
"comment": "An HTTP request that returns JSON.",
16+
"uri": "https://api.github.com/orgs/justeat",
17+
"requestHeaders": {
18+
"Accept": [
19+
"application/vnd.github.v3+json"
20+
],
21+
"Authorization": [
22+
"bearer my-token"
23+
],
24+
"User-Agent": [
25+
"My-App/1.0.0"
26+
]
27+
},
28+
"responseHeaders": {
29+
"X-RateLimit-Limit": [
30+
"60"
31+
]
32+
},
33+
"contentFormat": "json",
34+
"contentJson": {
35+
"id": 1516790,
36+
"login": "justeat",
37+
"url": "https://api.github.com/orgs/justeat"
38+
}
39+
}
40+
]
41+
}

0 commit comments

Comments
 (0)