Skip to content

Commit d864935

Browse files
authored
feat(testing): add controllable streams, request capture and a test clock to Refit.Testing (#2337)
- StreamSource releases a response body chunk by chunk (JSON Lines, SSE or JSON array), with Complete, Disconnect and Fail; Reply.Stream, Reply.JsonLines and Reply.ServerSentEvents expose it through the route table. - StubHttp.RequestCapture chooses Full (default), None or Bounded(maxBytes) so a streaming upload can be consumed by the reply code instead of being buffered by the handler. - StubHttp.TimeProvider drives NetworkBehavior delays and VerifyAllCalledAsync timeouts. - Replace every while (true) loop with a loop that has a real condition. - Bump PublicApiSharp.Analyzers to 2.1.0. - Add the testing-streaming documentation example and update the README.
1 parent ceb75e8 commit d864935

38 files changed

Lines changed: 3252 additions & 72 deletions

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Website code blocks can show a subset of a complete example and omit its test se
2121
| --- | --- |
2222
| [Refit](https://www.nuget.org/packages/Refit/) | Generated HTTP clients, request attributes, serializers and response types. Includes the generator, interface analyzers and code fixes. |
2323
| [Refit.HttpClientFactory](https://www.nuget.org/packages/Refit.HttpClientFactory/) | Register clients with dependency injection and `IHttpClientFactory`, including generated-only and keyed registrations. |
24-
| [Refit.Testing](https://www.nuget.org/packages/Refit.Testing/) | Match outgoing requests, supply local replies, verify calls and simulate network faults. |
24+
| [Refit.Testing](https://www.nuget.org/packages/Refit.Testing/) | Match outgoing requests, supply local replies, verify calls and simulate network faults. Release streamed replies chunk by chunk, choose how request bodies are captured, and control simulated time. |
2525
| [Refit.Newtonsoft.Json](https://www.nuget.org/packages/Refit.Newtonsoft.Json/) | Serialize content with Newtonsoft.Json. |
2626
| [Refit.Xml](https://www.nuget.org/packages/Refit.Xml/) | Serialize XML content. |
2727
| [Refit.Reflection](https://www.nuget.org/packages/Refit.Reflection/) | Optional request building through runtime reflection. Use generated clients for trimmed and Native AOT apps. |
@@ -40,8 +40,11 @@ and [AOT guidance](https://www.reactiveui.net/documentation/refit/aot/).
4040
| Serialized bodies, forms, buffering and request compression | [Bodies](https://www.reactiveui.net/documentation/refit/requests/bodies/) |
4141
| `Task<T>`, `ValueTask<T>`, `IObservable<T>` and response wrappers | [Return types](https://www.reactiveui.net/documentation/refit/results/return-types/) and [responses](https://www.reactiveui.net/documentation/refit/results/responses/) |
4242
| Streamed JSON arrays, JSON Lines and server-sent events | [Streaming](https://www.reactiveui.net/documentation/refit/results/streaming/) |
43+
| Lazy paging over cursors, offsets and `Link` headers with `PagedEnumerable<TPage, TItem>` | [Pagination](https://www.reactiveui.net/documentation/refit/results/pagination/) |
44+
| JSON contexts registered at client creation and per-method `JsonTypeInfo<T>` parameters | [JSON](https://www.reactiveui.net/documentation/refit/serialization/json/) |
4345
| HTTP, transport and deserialization failures | [Errors](https://www.reactiveui.net/documentation/refit/results/errors/) |
4446
| Local replies, request verification and simulated faults | [Testing](https://www.reactiveui.net/documentation/refit/testing/) |
47+
| Deterministic tests of streamed replies, stalled or dropped bodies, streaming uploads and simulated time | [Testing streams, uploads and time](https://www.reactiveui.net/documentation/refit/testing/streaming/) |
4548

4649
See [why use Refit](https://www.reactiveui.net/documentation/refit/why-refit/) for equivalent
4750
manual HTTP code and trade-offs. The website records known behavior discrepancies beside
@@ -61,11 +64,14 @@ to find types, overloads, parameters and return values across all topics on one
6164
| Client creation and request builders | Create generated or reflection clients, create owned `HttpClient` instances and supply request builders. | [Client creation](https://www.reactiveui.net/documentation/refit/clients/creation/) and [request builders](https://www.reactiveui.net/documentation/refit/clients/request-builders/) |
6265
| Settings and request metadata | Configure serializers, formatters, exception factories, transport behavior, request options, timeouts, versions and URL resolution. | [Settings](https://www.reactiveui.net/documentation/refit/clients/settings/), [metadata](https://www.reactiveui.net/documentation/refit/advanced/method-metadata/) and [helpers](https://www.reactiveui.net/documentation/refit/advanced/request-helpers/) |
6366
| Return types, responses and adapters | Choose `Task`, `ValueTask`, `IObservable<T>`, `IAsyncEnumerable<T>`, response wrappers and custom return adapters. | [Return types](https://www.reactiveui.net/documentation/refit/results/return-types/), [responses](https://www.reactiveui.net/documentation/refit/results/responses/), [streaming](https://www.reactiveui.net/documentation/refit/results/streaming/) and [adapters](https://www.reactiveui.net/documentation/refit/results/adapters/) |
67+
| Pagination | Return `PagedEnumerable<TPage, TItem>` with `[Paged]` and `[PageToken]`, or build one with `Create`, `FromCursor`, `FromOffset` and `FromLinks`; limit, prefetch or observe pages. | [Pagination](https://www.reactiveui.net/documentation/refit/results/pagination/) |
6468
| Errors and problem details | Read typed error content, create or transform API and transport exceptions, enforce success and redact sensitive details. | [Errors](https://www.reactiveui.net/documentation/refit/results/errors/) |
6569
| Content serializers | Use System.Text.Json, JSON Lines, synchronous or streaming serializer capabilities and custom serializers. | [JSON](https://www.reactiveui.net/documentation/refit/serialization/json/) and [content](https://www.reactiveui.net/documentation/refit/serialization/content/) |
70+
| JSON context registration | Pass a `JsonSerializerContext` to `RestService.ForGenerated<T>`, `AddRefitGeneratedClient<T>` or `RefitSettings.ForJsonContext`, and declare `JsonTypeInfo<T>` method parameters. Reflection-based JSON stays off unless you allow it. | [Register a context](https://www.reactiveui.net/documentation/refit/serialization/json/#register-a-context) and [pass metadata to a method](https://www.reactiveui.net/documentation/refit/serialization/json/#pass-metadata-to-a-method) |
6671
| Alternate serializers | Configure Newtonsoft.Json and XML serializers with their settings. | [Newtonsoft.Json](https://www.reactiveui.net/documentation/refit/serialization/newtonsoft-json/) and [XML](https://www.reactiveui.net/documentation/refit/serialization/xml/) |
6772
| HTTP client factory and dependency injection | Register generated, reflection or keyed clients, settings holders and authorization providers. | [Dependency injection](https://www.reactiveui.net/documentation/refit/clients/dependency-injection/) |
6873
| Testing routes, replies, faults and verification | Match requests, create replies, inject failures or delays, inspect bodies and verify calls. | [Testing](https://www.reactiveui.net/documentation/refit/testing/) |
74+
| Testing streams, uploads and time | Release streamed items with `StreamSource` and `Reply.Stream`, send fixed `Reply.JsonLines` or `Reply.ServerSentEvents` bodies, drop or stall a body, choose `StubHttp.RequestCapture` (`Full`, `None` or `Bounded`) and set `StubHttp.TimeProvider` to a fake clock. | [Testing streams, uploads and time](https://www.reactiveui.net/documentation/refit/testing/streaming/) |
6975
| Advanced generated request helpers | Extend or inspect request construction through query builders, parameter providers and helper contracts. | [Query builder](https://www.reactiveui.net/documentation/refit/advanced/query-builder/) and [request helpers](https://www.reactiveui.net/documentation/refit/advanced/request-helpers/) |
7076

7177
## Build requirements and targets

‎src/Directory.Packages.props‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
<PackageVersion Include="PerformanceSharp.Analyzers" Version="$(SharpAnalyzersVersion)"/>
3030
<PackageVersion Include="SecuritySharp.Analyzers" Version="$(SharpAnalyzersVersion)"/>
3131
<PackageVersion Include="SonarAnalyzer.CSharp" Version="10.34.0.3385"/>
32-
<PackageVersion Include="PublicApiSharp.Analyzers" Version="2.0.1"/>
32+
<PackageVersion Include="PublicApiSharp.Analyzers" Version="2.1.0"/>
3333
</ItemGroup>
3434

3535
<!-- Roslyn toolchain. Versions are intentionally held at their current bands: the source
@@ -49,6 +49,7 @@
4949
<ItemGroup Label="Test Stack">
5050
<PackageVersion Include="TUnit" Version="1.69.0"/>
5151
<PackageVersion Include="Microsoft.Testing.Extensions.CodeCoverage" Version="18.11.2"/>
52+
<PackageVersion Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.10.0"/>
5253
</ItemGroup>
5354

5455
<ItemGroup Label="Benchmarks">
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// Copyright (c) 2019-2026 ReactiveUI and Contributors. All rights reserved.
2+
// ReactiveUI and Contributors licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for full license information.
4+
5+
using System.Collections.Generic;
6+
using System.Text;
7+
8+
namespace Refit.Testing;
9+
10+
/// <summary>The recorded body of one request: complete when fully buffered, or filled as the reply code reads it.</summary>
11+
internal sealed class CapturedRequestBody
12+
{
13+
/// <summary>Guards the recorded bytes and state.</summary>
14+
private readonly Lock _gate = new();
15+
16+
/// <summary>The recorded bytes.</summary>
17+
private readonly List<byte> _bytes = [];
18+
19+
/// <summary>The most bytes to record, or <see langword="null"/> for no limit.</summary>
20+
private readonly int? _limit;
21+
22+
/// <summary>Whether the reader reached the end of the body.</summary>
23+
private bool _completed;
24+
25+
/// <summary>Whether the body exceeded <see cref="_limit"/>.</summary>
26+
private bool _truncated;
27+
28+
/// <summary>Initializes a new instance of the <see cref="CapturedRequestBody"/> class.</summary>
29+
/// <param name="mediaType">The request content media type, if any.</param>
30+
/// <param name="limit">The most bytes to record, or <see langword="null"/> for no limit.</param>
31+
internal CapturedRequestBody(string? mediaType, int? limit)
32+
{
33+
MediaType = mediaType;
34+
_limit = limit;
35+
}
36+
37+
/// <summary>Gets the request content media type, if any.</summary>
38+
internal string? MediaType { get; }
39+
40+
/// <summary>Records bytes as they are read, keeping at most the limit.</summary>
41+
/// <param name="bytes">The bytes that passed through.</param>
42+
internal void Append(ReadOnlySpan<byte> bytes)
43+
{
44+
lock (_gate)
45+
{
46+
var room = _limit is { } limit ? limit - _bytes.Count : bytes.Length;
47+
if (bytes.Length > room)
48+
{
49+
_truncated = true;
50+
bytes = bytes[..room];
51+
}
52+
53+
foreach (var value in bytes)
54+
{
55+
_bytes.Add(value);
56+
}
57+
}
58+
}
59+
60+
/// <summary>Marks the body as read to the end.</summary>
61+
internal void Complete()
62+
{
63+
lock (_gate)
64+
{
65+
_completed = true;
66+
}
67+
}
68+
69+
/// <summary>Returns the recorded text when the whole body was recorded.</summary>
70+
/// <returns>The body text decoded as UTF-8.</returns>
71+
/// <exception cref="InvalidOperationException">The body exceeded the limit or has not been read to the end.</exception>
72+
internal string GetText()
73+
{
74+
lock (_gate)
75+
{
76+
if (_truncated)
77+
{
78+
throw new InvalidOperationException(
79+
$"The request body exceeded the capture limit of {_limit} bytes; raise RequestCapture.Bounded or use RequestCapture.Full.");
80+
}
81+
82+
if (!_completed)
83+
{
84+
throw new InvalidOperationException(
85+
"The request body has not been read to the end; with bounded capture the reply code must consume the body before it can be inspected.");
86+
}
87+
88+
return Encoding.UTF8.GetString(_bytes.ToArray());
89+
}
90+
}
91+
}
Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
// Copyright (c) 2019-2026 ReactiveUI and Contributors. All rights reserved.
2+
// ReactiveUI and Contributors licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for full license information.
4+
5+
using System.IO;
6+
using System.Net;
7+
using System.Net.Http;
8+
using System.Threading;
9+
using System.Threading.Tasks;
10+
11+
namespace Refit.Testing;
12+
13+
/// <summary>
14+
/// Wraps a request body without reading it. Whichever way the reply code consumes the body, as a stream or by copying it
15+
/// out, the bytes pass through to the reader and are recorded up to the capture limit.
16+
/// </summary>
17+
internal sealed class CapturingContent : HttpContent
18+
{
19+
/// <summary>The original request body.</summary>
20+
private readonly HttpContent _inner;
21+
22+
/// <summary>The record filled as the body is read.</summary>
23+
private readonly CapturedRequestBody _capture;
24+
25+
/// <summary>Initializes a new instance of the <see cref="CapturingContent"/> class, copying the original content headers.</summary>
26+
/// <param name="inner">The original request body.</param>
27+
/// <param name="capture">The record filled as the body is read.</param>
28+
internal CapturingContent(HttpContent inner, CapturedRequestBody capture)
29+
{
30+
_inner = inner;
31+
_capture = capture;
32+
foreach (var header in inner.Headers)
33+
{
34+
if (!string.Equals(header.Key, "Content-Length", StringComparison.OrdinalIgnoreCase))
35+
{
36+
_ = Headers.TryAddWithoutValidation(header.Key, header.Value);
37+
}
38+
}
39+
}
40+
41+
/// <inheritdoc/>
42+
protected override async Task SerializeToStreamAsync(Stream stream, TransportContext? context)
43+
{
44+
// The copy target belongs to the caller; the wrapper owns nothing and needs no disposal.
45+
await _inner.CopyToAsync(new CaptureStream(stream, _capture, ownsInner: false)).ConfigureAwait(false);
46+
_capture.Complete();
47+
}
48+
49+
/// <inheritdoc/>
50+
protected override async Task<Stream> CreateContentReadStreamAsync() =>
51+
new CaptureStream(await _inner.ReadAsStreamAsync().ConfigureAwait(false), _capture, ownsInner: true);
52+
53+
/// <inheritdoc/>
54+
protected override bool TryComputeLength(out long length)
55+
{
56+
var known = _inner.Headers.ContentLength;
57+
length = known.GetValueOrDefault();
58+
return known.HasValue;
59+
}
60+
61+
/// <inheritdoc/>
62+
protected override void Dispose(bool disposing)
63+
{
64+
_inner.Dispose();
65+
base.Dispose(disposing);
66+
}
67+
68+
/// <summary>Passes reads or writes through to another stream and records the bytes that pass.</summary>
69+
/// <param name="inner">The stream read from or written to.</param>
70+
/// <param name="capture">The record to fill.</param>
71+
/// <param name="ownsInner">
72+
/// Whether disposing the wrapper disposes <paramref name="inner"/>: true for a body read stream, false for a copy
73+
/// target owned by the caller.
74+
/// </param>
75+
internal sealed class CaptureStream(Stream inner, CapturedRequestBody capture, bool ownsInner) : Stream
76+
{
77+
/// <inheritdoc/>
78+
public override bool CanRead => inner.CanRead;
79+
80+
/// <inheritdoc/>
81+
public override bool CanSeek => false;
82+
83+
/// <inheritdoc/>
84+
public override bool CanWrite => inner.CanWrite;
85+
86+
/// <inheritdoc/>
87+
public override long Length => throw new NotSupportedException();
88+
89+
/// <inheritdoc/>
90+
public override long Position
91+
{
92+
get => throw new NotSupportedException();
93+
set => throw new NotSupportedException();
94+
}
95+
96+
/// <inheritdoc/>
97+
public override void Flush() => inner.Flush();
98+
99+
/// <inheritdoc/>
100+
public override Task FlushAsync(CancellationToken cancellationToken) => inner.FlushAsync(cancellationToken);
101+
102+
/// <inheritdoc/>
103+
public override int Read(byte[] buffer, int offset, int count) => Record(buffer.AsSpan(offset, inner.Read(buffer, offset, count)));
104+
105+
#if NET8_0_OR_GREATER
106+
/// <inheritdoc/>
107+
public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) =>
108+
ReadAsync(buffer.AsMemory(offset, count), cancellationToken).AsTask();
109+
110+
/// <inheritdoc/>
111+
public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
112+
{
113+
var read = await inner.ReadAsync(buffer, cancellationToken).ConfigureAwait(false);
114+
return Record(buffer.Span[..read]);
115+
}
116+
#else
117+
/// <inheritdoc/>
118+
public override async Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) =>
119+
Record(buffer.AsSpan(offset, await inner.ReadAsync(buffer, offset, count, cancellationToken).ConfigureAwait(false)));
120+
#endif
121+
122+
/// <inheritdoc/>
123+
public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
124+
125+
/// <inheritdoc/>
126+
public override void SetLength(long value) => throw new NotSupportedException();
127+
128+
/// <inheritdoc/>
129+
public override void Write(byte[] buffer, int offset, int count)
130+
{
131+
inner.Write(buffer, offset, count);
132+
capture.Append(buffer.AsSpan(offset, count));
133+
}
134+
135+
#if NET8_0_OR_GREATER
136+
/// <inheritdoc/>
137+
public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) =>
138+
WriteAsync(buffer.AsMemory(offset, count), cancellationToken).AsTask();
139+
140+
/// <inheritdoc/>
141+
public override async ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default)
142+
{
143+
await inner.WriteAsync(buffer, cancellationToken).ConfigureAwait(false);
144+
capture.Append(buffer.Span);
145+
}
146+
#else
147+
/// <inheritdoc/>
148+
public override async Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
149+
{
150+
await inner.WriteAsync(buffer, offset, count, cancellationToken).ConfigureAwait(false);
151+
capture.Append(buffer.AsSpan(offset, count));
152+
}
153+
#endif
154+
155+
/// <inheritdoc/>
156+
protected override void Dispose(bool disposing)
157+
{
158+
if (ownsInner)
159+
{
160+
inner.Dispose();
161+
}
162+
163+
base.Dispose(disposing);
164+
}
165+
166+
/// <summary>Records bytes just read, completing the record at the end of the body.</summary>
167+
/// <param name="read">The bytes just read; empty at the end of the body.</param>
168+
/// <returns>The number of bytes read.</returns>
169+
private int Record(ReadOnlySpan<byte> read)
170+
{
171+
if (read.IsEmpty)
172+
{
173+
capture.Complete();
174+
}
175+
else
176+
{
177+
capture.Append(read);
178+
}
179+
180+
return read.Length;
181+
}
182+
}
183+
}

0 commit comments

Comments
 (0)
⌂ 换网址