Class StubHttpMessageHandler

Namespace: XBullet.EasyTesting.Http

Assembly: XBullet.EasyTesting.Http.dll

A fluent, in-memory HTTP handler that returns arranged responses and records outbound requests.

public sealed class StubHttpMessageHandler : HttpMessageHandler, IDisposable, ITestScenarioResource

Inheritance: object

HttpMessageHandler

StubHttpMessageHandler

Implements: IDisposable

ITestScenarioResource

Inherited Members: HttpMessageHandler.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods: StubHttpExchangeSnapshotExtensions.ShouldMatchExchangesSnapshot(StubHttpMessageHandler, StubHttpExchangeSnapshotOptions?, SnapshotSettings?, CancellationToken, string, string)

StubHttpRequestSnapshotExtensions.ShouldMatchRequestsSnapshot(StubHttpMessageHandler, StubHttpRequestSnapshotOptions?, SnapshotSettings?, CancellationToken, string, string)

Remarks

See outbound HTTP testing for request matching, response sequences, failure simulation, and verification.

Properties

CallCount

Gets the number of requests received since construction or the last reset.

public int CallCount { get; }

Property Value

int: The current request count as a thread-safe point-in-time value.

Exchanges

Gets a stable copy of the request/response exchanges observed by this handler.

public IReadOnlyList<StubHttpExchange> Exchanges { get; }

Property Value

IReadOnlyList<StubHttpExchange>: A newly allocated array containing the handler-owned exchange objects in arrival order. Later requests and resets do not change the array, but an exchange's response body state may update when the HTTP caller subsequently consumes its content.

Requests

Gets a stable copy of the requests received by this handler.

public IReadOnlyList<StubHttpRequest> Requests { get; }

Property Value

IReadOnlyList<StubHttpRequest>: A newly allocated array containing the recorded request objects in arrival order. Later requests and resets do not change the array. The handler owns the records and their nested header values; callers must not mutate them. Values are not redacted.

Methods

CaptureDiagnosticsAsync(CancellationToken)

Captures recorded requests for scenario-failure diagnostics.

public ValueTask<object?> CaptureDiagnosticsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: Cancels capture before a snapshot is created. The default token does not request cancellation.

Returns

ValueTask<object>: An already-completed value task containing a newly allocated serializable snapshot with the call count and requests. Recognized sensitive query values are redacted from request URIs; captured headers and bodies are included unchanged and can contain sensitive data.

Dispose(bool)

Keeps this in-memory handler reusable when a scenario-specific service provider disposes its HTTP pipeline. The handler owns no operating-system resources; call Reset() to clear it.

protected override void Dispose(bool disposing)

Parameters

disposing bool: Ignored. Both explicit disposal and finalization leave the in-memory handler usable and do not clear its rules or recordings.

Reset()

Removes all arranged responses and recorded requests.

public StubHttpMessageHandler Reset()

Returns

StubHttpMessageHandler: This handler for reuse. Requests or rules added concurrently after the reset lock is released are retained.

ResetAsync(CancellationToken)

Removes all arranged responses and recorded exchanges.

public ValueTask ResetAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: Cancels the reset before any state is changed. Once cancellation is checked, reset completes synchronously. The default token does not request cancellation.

Returns

ValueTask: A value task that is already complete after the reset finishes.

SendAsync(HttpRequestMessage, CancellationToken)

Send an HTTP request as an asynchronous operation.

protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)

Parameters

request HttpRequestMessage: The HTTP request message to send.
cancellationToken CancellationToken: The cancellation token to cancel operation.

Returns

Task<HttpResponseMessage>: The task object representing the asynchronous operation.

Exceptions

ArgumentNullException: The request was null.
OperationCanceledException: The cancellation token was canceled. This exception is stored into the returned task.

Verify(Func<StubHttpRequest, bool>, int, string?)

Verifies the number of recorded requests accepted by a custom predicate.

public StubHttpMessageHandler Verify(Func<StubHttpRequest, bool> predicate, int expectedCount, string? description = null)

Parameters

predicate Func<StubHttpRequest, bool>: The non-null predicate invoked once, sequentially, for each request in a point-in-time snapshot. The handler owns each supplied request; the predicate must not mutate it. Exceptions from the predicate are propagated unchanged.
expectedCount int: The non-negative number of accepted requests required.
description string: Text used in a failed verification message. When null, empty, or whitespace, the request predicate is used. Do not include secrets in this value.

Returns

StubHttpMessageHandler: This handler so additional verification calls can be chained.

Exceptions

StubHttpVerificationException: The point-in-time accepted count does not equal expectedCount.

VerifyCalled(HttpMethod, string, int)

Verifies that an exact method-and-URI request was recorded the expected number of times.

public StubHttpMessageHandler VerifyCalled(HttpMethod method, string requestUri, int expectedCount = 1)

Parameters

method HttpMethod: The non-null HTTP method to match. The handler reads but does not own or mutate it.
requestUri string: The non-empty URI text compared using the same exact absolute-or-relative rules as When(HttpMethod, string) before additional matchers are applied.
expectedCount int: The non-negative number of matching requests required. The default is one.

Returns

StubHttpMessageHandler: This handler so additional verification calls can be chained.

Exceptions

StubHttpVerificationException: The point-in-time count does not equal expectedCount. Recognized sensitive query values are redacted from the exception message.

VerifyNotCalled(HttpMethod, string)

Verifies that an exact method-and-URI request was not recorded.

public StubHttpMessageHandler VerifyNotCalled(HttpMethod method, string requestUri)

Parameters

method HttpMethod: The non-null HTTP method to match. The handler reads but does not own or mutate it.
requestUri string: The non-empty URI text compared using the same exact absolute-or-relative rules as When(HttpMethod, string) before additional matchers are applied.

Returns

StubHttpMessageHandler: This handler so additional verification calls can be chained.

Exceptions

StubHttpVerificationException: A matching request was recorded.

When(HttpMethod, string)

Starts an exact method-and-URI response rule.

public StubHttpResponseBuilder When(HttpMethod method, string requestUri)

Parameters

method HttpMethod: The non-null HTTP method to match. The handler reads but does not own or mutate it.
requestUri string: The non-empty URI text to match. HTTP and HTTPS absolute URIs match the full absolute URI; other values match a relative request's original text or an absolute request's path and query. Adding a query-parameter matcher later changes comparison to the path only.

Returns

StubHttpResponseBuilder: A new mutable response builder associated with this handler.