Class StubHttpResponseBuilder

Namespace

XBullet.EasyTesting.Http

Assembly

XBullet.EasyTesting.Http.dll

Defines matchers and responses for one outbound HTTP request rule.

public sealed class StubHttpResponseBuilder

Inheritance

object

StubHttpResponseBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This mutable builder is not thread-safe. Matcher values are snapshotted when a terminal response method adds the rule to the handler; stored predicates and factories may subsequently be invoked concurrently by matching requests.

Methods

Cancel()

Cancels the arranged response immediately.

public StubHttpMessageHandler Cancel()

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

CancelAfter(TimeSpan)

Cancels the arranged response after the supplied delay.

public StubHttpMessageHandler CancelAfter(TimeSpan delay)

Parameters

delay TimeSpan

The non-negative delay before arranged cancellation. Zero cancels without waiting. InfiniteTimeSpan is not accepted. Request cancellation can end the delay earlier.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

Respond(Func<StubHttpRequest, HttpResponseMessage>)

Adds a response created from the captured request.

public StubHttpMessageHandler Respond(Func<StubHttpRequest, HttpResponseMessage> responseFactory)

Parameters

responseFactory Func<StubHttpRequest, HttpResponseMessage>

The non-null factory invoked once per matching request with the handler-owned captured request. It may run more than once and concurrently and must return a non-null response, normally a new instance whose ownership passes to the HTTP caller.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

Respond(HttpStatusCode)

Adds a response containing no body.

public StubHttpMessageHandler Respond(HttpStatusCode statusCode)

Parameters

statusCode HttpStatusCode

The HTTP status code returned for every matching request.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

RespondAsync(Func<StubHttpRequest, CancellationToken, Task<HttpResponseMessage>>)

Adds an asynchronous response created from the captured request.

public StubHttpMessageHandler RespondAsync(Func<StubHttpRequest, CancellationToken, Task<HttpResponseMessage>> responseFactory)

Parameters

responseFactory Func<StubHttpRequest, CancellationToken, Task<HttpResponseMessage>>

The non-null factory invoked once per matching request with the handler-owned captured request and that send operation's cancellation token. It may run more than once and concurrently and must return a task producing a non-null response whose ownership passes to the HTTP caller. Cancellation or other failures are recorded and propagated.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

RespondJson<T>(T, HttpStatusCode, JsonSerializerOptions?)

Adds a JSON response.

public StubHttpMessageHandler RespondJson<T>(T value, HttpStatusCode statusCode = HttpStatusCode.OK, JsonSerializerOptions? serializerOptions = null)

Parameters

value T

The response value captured for use by each matching request. The handler does not own or dispose it; callers must not mutate it concurrently with response serialization.

statusCode HttpStatusCode

The HTTP status code for each response. The default is OK.

serializerOptions JsonSerializerOptions

Options passed to each new JSON content instance, or null to use the framework's web defaults. The handler retains but does not own or mutate non-null options.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

Type Parameters

T

The type serialized as the JSON response body.

RespondMalformedJson(string, HttpStatusCode)

Returns intentionally invalid JSON with a JSON content type.

public StubHttpMessageHandler RespondMalformedJson(string content = "{\"incomplete\":", HttpStatusCode statusCode = HttpStatusCode.OK)

Parameters

content string

The non-null invalid JSON text returned as UTF-8 application/json. The default is {"incomplete":. Valid JSON is rejected when the rule is configured.

statusCode HttpStatusCode

The HTTP status code for each response. The default is OK.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

RespondSequence(Action<StubHttpResponseSequenceBuilder>)

Adds an ordered set of responses for consecutive matching requests.

public StubHttpMessageHandler RespondSequence(Action<StubHttpResponseSequenceBuilder> configure)

Parameters

configure Action<StubHttpResponseSequenceBuilder>

The non-null callback invoked synchronously once with a new sequence builder. It must add at least one response and may not leave a delay without a following response. The callback is not retained or invoked concurrently; the built response delegates may run concurrently.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

RespondText(string, HttpStatusCode, string)

Adds a UTF-8 text response.

public StubHttpMessageHandler RespondText(string value, HttpStatusCode statusCode = HttpStatusCode.OK, string mediaType = "text/plain")

Parameters

value string

The non-null text returned for every matching request.

statusCode HttpStatusCode

The HTTP status code for each response. The default is OK.

mediaType string

The non-empty response media type. The default is text/plain; UTF-8 is always used.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

RespondTruncated(string, HttpStatusCode, string)

Returns content that throws an I/O exception while it is being consumed.

public StubHttpMessageHandler RespondTruncated(string partialContent, HttpStatusCode statusCode = HttpStatusCode.OK, string mediaType = "application/octet-stream")

Parameters

partialContent string

The non-null text made available before content consumption fails. An empty value is accepted.

statusCode HttpStatusCode

The HTTP status code for each response. The default is OK.

mediaType string

The non-empty content media type. The default is application/octet-stream.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

Throw(Func<StubHttpRequest, Exception>)

Throws an exception when this rule matches.

public StubHttpMessageHandler Throw(Func<StubHttpRequest, Exception> exceptionFactory)

Parameters

exceptionFactory Func<StubHttpRequest, Exception>

The non-null factory invoked once per matching request with the handler-owned captured request. It may run more than once and concurrently and must return a non-null exception. The exception is recorded and then propagated to the HTTP caller.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

Timeout()

Waits until the request is cancelled or its HttpClient times out.

public StubHttpMessageHandler Timeout()

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

TimeoutAfter(TimeSpan)

Throws TimeoutException after the supplied delay.

public StubHttpMessageHandler TimeoutAfter(TimeSpan delay)

Parameters

delay TimeSpan

The non-negative delay before the exception is thrown. Zero throws without waiting. InfiniteTimeSpan is not accepted. Request cancellation can end the delay earlier instead.

Returns

StubHttpMessageHandler

The owning handler so more rules or verifications can be configured.

WithDelay(TimeSpan)

Delays the arranged response while observing request cancellation.

public StubHttpResponseBuilder WithDelay(TimeSpan delay)

Parameters

delay TimeSpan

The non-negative delay applied before the configured response factory runs. Zero disables the delay. InfiniteTimeSpan is not accepted.

Returns

StubHttpResponseBuilder

This builder so a terminal response can be configured.

WithJsonPath(string, Func<JsonElement, bool>)

Requires a JSON path to satisfy a predicate. Dot-separated properties and zero-based array indexes are supported, for example $.items[0].quantity.

public StubHttpResponseBuilder WithJsonPath(string path, Func<JsonElement, bool> predicate)

Parameters

path string

The non-empty, case-sensitive path to a property or non-negative array index. A leading $ is optional. Invalid syntax is rejected when the rule is configured.

predicate Func<JsonElement, bool>

The non-null predicate invoked with the selected JSON element for each request that reaches this matcher. It may run more than once and concurrently. Exceptions are reported as rule mismatches. The element is valid only during the callback and must not be retained.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

WithJsonPath<T>(string, T, JsonSerializerOptions?)

Requires a JSON path to structurally match the supplied value. Dot-separated properties and zero-based array indexes are supported, for example $.items[0].sku.

public StubHttpResponseBuilder WithJsonPath<T>(string path, T expectedValue, JsonSerializerOptions? serializerOptions = null)

Parameters

path string

The non-empty, case-sensitive path to a property or non-negative array index. A leading $ is optional. Invalid syntax is rejected when the rule is configured.

expectedValue T

The value serialized immediately and compared structurally with the selected JSON element. The builder does not retain or own the supplied value.

serializerOptions JsonSerializerOptions

Options used for the immediate serialization, or null to use web JSON defaults. The options are read but not retained, owned, or mutated.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

Type Parameters

T

The type of value serialized into the expected JSON tree.

WithJsonProperty(string, Func<JsonElement, bool>)

Requires a root JSON property to satisfy a predicate.

public StubHttpResponseBuilder WithJsonProperty(string propertyName, Func<JsonElement, bool> predicate)

Parameters

propertyName string

The non-empty, case-sensitive root property name.

predicate Func<JsonElement, bool>

The non-null predicate invoked with the selected JSON element for each request that reaches this matcher. It may run more than once and concurrently. Exceptions are reported as rule mismatches. The element is valid only during the callback and must not be retained.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

WithJsonProperty<T>(string, T, JsonSerializerOptions?)

Requires a root JSON property to structurally match the supplied value.

public StubHttpResponseBuilder WithJsonProperty<T>(string propertyName, T expectedValue, JsonSerializerOptions? serializerOptions = null)

Parameters

propertyName string

The non-empty, case-sensitive root property name. Nested paths are not interpreted here; use WithJsonPath<T>(string, T, JsonSerializerOptions?) for nested values.

expectedValue T

The value serialized immediately and compared structurally with the selected property. The builder does not retain or own the supplied value.

serializerOptions JsonSerializerOptions

Options used for the immediate serialization, or null to use web JSON defaults. The options are read but not retained, owned, or mutated.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

Type Parameters

T

The type of value serialized into the expected JSON tree.

WithJsonRequestBody<T>(T, JsonSerializerOptions?)

Requires the request JSON body to structurally match the supplied value.

public StubHttpResponseBuilder WithJsonRequestBody<T>(T value, JsonSerializerOptions? serializerOptions = null)

Parameters

value T

The value serialized immediately and compared structurally with the request JSON. The builder does not retain or own the supplied value.

serializerOptions JsonSerializerOptions

Options used for the immediate serialization, or null to use web JSON defaults. The options are read but not retained, owned, or mutated.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

Type Parameters

T

The type of value serialized into the expected JSON tree.

WithQueryParameter(string, Func<IReadOnlyList<string>, bool>)

Requires the values of a request query parameter to satisfy a predicate.

public StubHttpResponseBuilder WithQueryParameter(string name, Func<IReadOnlyList<string>, bool> predicate)

Parameters

name string

The non-empty, case-sensitive decoded query-parameter name. Adding a query matcher changes the rule's URI comparison to ignore the query string itself.

predicate Func<IReadOnlyList<string>, bool>

The non-null predicate invoked for each request that reaches this matcher with all decoded values in request order, or an empty list when the parameter is absent. It may run more than once and concurrently. Exceptions are reported as rule mismatches. Do not retain the list.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

WithQueryParameter(string, string)

Requires the request query string to contain an exact parameter value.

public StubHttpResponseBuilder WithQueryParameter(string name, string value)

Parameters

name string

The non-empty, case-sensitive decoded query-parameter name. Adding a query matcher changes the rule's URI comparison to ignore the query string itself.

value string

The non-null decoded value to match using ordinal, case-sensitive comparison. An empty value is accepted. Values of recognized sensitive parameters are redacted from diagnostics.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

WithRequest(Func<StubHttpRequest, bool>, string?)

Adds a custom request predicate to this response rule.

public StubHttpResponseBuilder WithRequest(Func<StubHttpRequest, bool> predicate, string? description = null)

Parameters

predicate Func<StubHttpRequest, bool>

The non-null predicate invoked with the captured request after method and URI matching. It may run more than once and concurrently. Returning false or throwing an exception makes the rule a mismatch. The handler owns the captured request object.

description string

Text used in mismatch diagnostics. When null, empty, or whitespace, the custom request predicate is used. Do not include secrets in this text.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

WithRequestBody(string)

Requires the request body to exactly match the supplied text.

public StubHttpResponseBuilder WithRequestBody(string body)

Parameters

body string

The non-null expected body compared using ordinal, case-sensitive comparison. An empty body is accepted.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.

WithRequestHeader(string, string)

Requires the request to contain an exact header value.

public StubHttpResponseBuilder WithRequestHeader(string name, string value)

Parameters

name string

The non-empty, case-insensitive HTTP header name to inspect.

value string

The non-null header value to match using ordinal, case-sensitive comparison. An empty value is accepted.

Returns

StubHttpResponseBuilder

This builder so additional request matchers can be configured.