Class TestScenarioBuilder<TEntryPoint>

Namespace: XBullet.EasyTesting.Hosting

Assembly: XBullet.EasyTesting.dll

Fluently arranges state, configures a client, and sends one HTTP request.

public sealed class TestScenarioBuilder<TEntryPoint> where TEntryPoint : class

Type Parameters

TEntryPoint: The application entry-point type used by the factory that creates the scenario client.

Inheritance: object

TestScenarioBuilder<TEntryPoint>

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A builder is single-use. After ExecuteAsync(CancellationToken) begins, configuration methods and subsequent execution attempts throw InvalidOperationException. The mutable builder is not thread-safe and must be configured and executed from one execution flow.

Methods

Arrange(Func<CancellationToken, Task>)

Adds an asynchronous arrangement executed before the client is created.

public TestScenarioBuilder<TEntryPoint> Arrange(Func<CancellationToken, Task> arrangement)

Parameters

arrangement Func<CancellationToken, Task>: The callback invoked once during execution with the execution cancellation token. Arrangements run sequentially in registration order and are not invoked concurrently by this builder.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsAnonymous()

Configures the scenario client to be anonymous.

public TestScenarioBuilder<TEntryPoint> AsAnonymous()

Returns

TestScenarioBuilder<TEntryPoint>: This builder. Any selected simulated identity or bearer token is removed; other configured credentials and headers remain unchanged.

AsApiKey(Action<TestApiKeyBuilder>)

Configures the client with an API-key-shaped test identity.

public TestScenarioBuilder<TEntryPoint> AsApiKey(Action<TestApiKeyBuilder> configure)

Parameters

configure Action<TestApiKeyBuilder>: The callback invoked synchronously once with a new API-key identity builder. It configures simulated claims, not a real API-key secret.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsAzureAdUser(Action<TestAzureAdUserBuilder>)

Configures the client with an Azure AD-shaped test identity.

public TestScenarioBuilder<TEntryPoint> AsAzureAdUser(Action<TestAzureAdUserBuilder> configure)

Parameters

configure Action<TestAzureAdUserBuilder>: The callback invoked synchronously once with a new Azure AD user builder targeting the configured simulated scheme.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsExpiredJwt(Action<TestJwtBuilder>?)

Uses an expired locally signed token.

public TestScenarioBuilder<TEntryPoint> AsExpiredJwt(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures claims after the expired lifetime is applied and before signing. When null, the expired defaults remain unchanged; the callback can replace the configured lifetime.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsFederatedUser(Action<TestFederatedUserBuilder>)

Configures the client with Federation and API-user test identities.

public TestScenarioBuilder<TEntryPoint> AsFederatedUser(Action<TestFederatedUserBuilder> configure)

Parameters

configure Action<TestFederatedUserBuilder>: The callback invoked synchronously once with a new Federation user builder targeting the configured simulated scheme.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwt(Action<TestJwtBuilder>?)

Uses a locally signed token with the application's real JWT bearer handler.

public TestScenarioBuilder<TEntryPoint> AsJwt(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures token claims synchronously before signing. When null, the local authority's default valid token is used. The callback runs once and is not retained.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwt(string, Action<TestJwtBuilder>?)

Uses a locally signed token from a named JWT authority.

public TestScenarioBuilder<TEntryPoint> AsJwt(string authenticationScheme, Action<TestJwtBuilder>? configure = null)

Parameters

authenticationScheme string: The non-empty registered JWT authentication scheme whose local authority signs the token.
configure Action<TestJwtBuilder>: Configures token claims synchronously before signing. When null, the selected authority's default valid token is used.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwtNotYetValid(Action<TestJwtBuilder>?)

Uses a token whose not-before time is in the future.

public TestScenarioBuilder<TEntryPoint> AsJwtNotYetValid(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures claims after the future lifetime is applied and before signing. When null, the future not-before time remains unchanged; the callback can replace the configured lifetime.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwtWithInvalidSignature(Action<TestJwtBuilder>?)

Uses a token with an invalid signature.

public TestScenarioBuilder<TEntryPoint> AsJwtWithInvalidSignature(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures claims before signing with an untrusted key whose identifier matches the current trusted key. When null, default claims are used. The callback cannot replace the untrusted signing key.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwtWithUnknownKey(Action<TestJwtBuilder>?)

Uses a token with a key identifier absent from JWKS.

public TestScenarioBuilder<TEntryPoint> AsJwtWithUnknownKey(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures claims before signing with an untrusted key whose identifier is absent from JWKS. When null, default claims are used. The callback cannot replace the untrusted signing key.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwtWithWrongAudience(Action<TestJwtBuilder>?)

Uses a locally signed token with an invalid audience.

public TestScenarioBuilder<TEntryPoint> AsJwtWithWrongAudience(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures claims after the invalid audience is applied and before signing. When null, the invalid audience remains unchanged; the callback can replace it.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsJwtWithWrongIssuer(Action<TestJwtBuilder>?)

Uses a locally signed token with an invalid issuer.

public TestScenarioBuilder<TEntryPoint> AsJwtWithWrongIssuer(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures claims after the invalid issuer is applied and before signing. When null, the invalid issuer remains unchanged; the callback can replace it.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsMalformedJwt(string)

Uses a deliberately malformed bearer token.

public TestScenarioBuilder<TEntryPoint> AsMalformedJwt(string value = "not-a-valid-jwt")

Parameters

value string: The non-empty raw bearer-token value. When omitted, not-a-valid-jwt is used.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsUnsignedJwt(Action<TestJwtBuilder>?)

Uses an unsigned token.

public TestScenarioBuilder<TEntryPoint> AsUnsignedJwt(Action<TestJwtBuilder>? configure = null)

Parameters

configure Action<TestJwtBuilder>: Configures token claims synchronously before serialization. When null, the local authority's default claims are used. No signing key is applied.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsUser(Action<TestUserBuilder>)

Builds and configures the test user used by the client.

public TestScenarioBuilder<TEntryPoint> AsUser(Action<TestUserBuilder> configure)

Parameters

configure Action<TestUserBuilder>: The callback invoked synchronously once with a new test-user builder. It is not retained or invoked concurrently.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsUser(Action<TestUserBuilder>, string)

Builds a test identity that targets a named simulated scheme.

public TestScenarioBuilder<TEntryPoint> AsUser(Action<TestUserBuilder> configure, string authenticationScheme)

Parameters

configure Action<TestUserBuilder>: The callback invoked synchronously once with a new test-user builder initialized for authenticationScheme.
authenticationScheme string: The non-empty application authentication-scheme name written to the transported identity.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

AsUser(TestUser)

Configures the client with a test user.

public TestScenarioBuilder<TEntryPoint> AsUser(TestUser user)

Parameters

user TestUser: The non-null simulated identity sent by the scenario client. The immutable value is retained but not owned, and it replaces any configured bearer token.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

Delete(string)

Defines a DELETE request for this scenario.

public TestScenarioBuilder<TEntryPoint> Delete(string requestUri)

Parameters

requestUri string: The non-empty relative or absolute request URI passed to DeleteAsync(string, CancellationToken).

Returns

TestScenarioBuilder<TEntryPoint>: This builder with its single HTTP request configured.

ExecuteAsync(CancellationToken)

Runs the arrangements and sends the configured request once.

public Task<TestScenarioResult> ExecuteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: Cancels the registered arrangements and request callback. On cancellation or any other failure, the created client is disposed. The default token does not request cancellation.

Returns

Task<TestScenarioResult>: A task whose result owns the created client and non-null response. Dispose the result to dispose both. The builder cannot be executed or modified again, including after failure.

Exceptions

InvalidOperationException: No request is configured, the request callback returns null, or this builder has already begun execution.

Get(string)

Defines a GET request for this scenario.

public TestScenarioBuilder<TEntryPoint> Get(string requestUri)

Parameters

requestUri string: The non-empty relative or absolute request URI passed to GetAsync(string, CancellationToken).

Returns

TestScenarioBuilder<TEntryPoint>: This builder with its single HTTP request configured.

PostJson<T>(string, T)

Defines a POST request with a JSON body for this scenario.

public TestScenarioBuilder<TEntryPoint> PostJson<T>(string requestUri, T body)

Parameters

requestUri string: The non-empty relative or absolute request URI.
body T: The value serialized with the web-default JSON options used by PostAsJsonAsync<TValue>(HttpClient, string, TValue, CancellationToken).

Returns

TestScenarioBuilder<TEntryPoint>: This builder with its single HTTP request configured.

Type Parameters

T: The type serialized as the JSON request body.

PutJson<T>(string, T)

Defines a PUT request with a JSON body for this scenario.

public TestScenarioBuilder<TEntryPoint> PutJson<T>(string requestUri, T body)

Parameters

requestUri string: The non-empty relative or absolute request URI.
body T: The value serialized with the web-default JSON options used by PutAsJsonAsync<TValue>(HttpClient, string, TValue, CancellationToken).

Returns

TestScenarioBuilder<TEntryPoint>: This builder with its single HTTP request configured.

Type Parameters

T: The type serialized as the JSON request body.

Send(Func<HttpClient, CancellationToken, Task<HttpResponseMessage>>)

Defines a custom HTTP request operation for this scenario.

public TestScenarioBuilder<TEntryPoint> Send(Func<HttpClient, CancellationToken, Task<HttpResponseMessage>> send)

Parameters

send Func<HttpClient, CancellationToken, Task<HttpResponseMessage>>: The callback invoked once after all arrangements complete and the scenario client is created. It receives the result-owned client and execution cancellation token, must return a non-null response, and is not invoked concurrently by this builder. On failure, the client is disposed before the exception is propagated.

Returns

TestScenarioBuilder<TEntryPoint>: This builder with its single HTTP request configured.

WithApiKeyHeader(string, string?)

Injects a real API key into every request header.

public TestScenarioBuilder<TEntryPoint> WithApiKeyHeader(string value, string? headerName = null)

Parameters

value string: The non-empty API-key secret sent without validation. Use test-only credentials and prevent the value from appearing in logs or diagnostics.
headerName string: The header name to use. When null, the name configured for end-to-end API-key authentication is used.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithApiKeyQuery(string, string?)

Injects a real API key into every request query string.

public TestScenarioBuilder<TEntryPoint> WithApiKeyQuery(string value, string? parameterName = null)

Parameters

value string: The non-empty API-key secret appended without validation. Query strings can be logged by applications and infrastructure, so use test-only credentials.
parameterName string: The query-parameter name to use. When null, the configured end-to-end API-key parameter name is used.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithBaseAddress(Uri)

Sets the base address used by relative requests.

public TestScenarioBuilder<TEntryPoint> WithBaseAddress(Uri baseAddress)

Parameters

baseAddress Uri: The non-null base URI passed unchanged to the client factory. The scenario retains the immutable URI but does not own it.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithBearerToken(string)

Sends an existing bearer token through the application's configured handler.

public TestScenarioBuilder<TEntryPoint> WithBearerToken(string token)

Parameters

token string: The non-empty raw bearer token sent without validation. Use test credentials and prevent the token from appearing in logs or diagnostics. It replaces any simulated identity.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithClientCertificate(Action<TestClientCertificateBuilder>?)

Creates and transports a client certificate to the real certificate handler.

public TestScenarioBuilder<TEntryPoint> WithClientCertificate(Action<TestClientCertificateBuilder>? configure = null)

Parameters

configure Action<TestClientCertificateBuilder>: Configures a new self-signed certificate synchronously before export. When null, certificate-builder defaults are used. The callback runs once and is not retained.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithClientCertificate(X509Certificate2)

Transports an existing client certificate to the real certificate handler.

public TestScenarioBuilder<TEntryPoint> WithClientCertificate(X509Certificate2 certificate)

Parameters

certificate X509Certificate2: The certificate exported immediately into the internal transport header. The scenario does not retain, own, or dispose it.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithClientCertificate(string, Action<TestClientCertificateBuilder>?)

Creates a client certificate for a named authentication scheme.

public TestScenarioBuilder<TEntryPoint> WithClientCertificate(string authenticationScheme, Action<TestClientCertificateBuilder>? configure = null)

Parameters

authenticationScheme string: The non-empty registered certificate authentication scheme that accepts the transported certificate.
configure Action<TestClientCertificateBuilder>: Configures a new self-signed certificate synchronously before export. When null, certificate-builder defaults are used.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithClientCertificate(string, X509Certificate2)

Transports an existing client certificate for a named authentication scheme.

public TestScenarioBuilder<TEntryPoint> WithClientCertificate(string authenticationScheme, X509Certificate2 certificate)

Parameters

authenticationScheme string: The non-empty registered certificate authentication scheme that accepts the transported certificate.
certificate X509Certificate2: The certificate exported immediately into the internal transport header. The scenario does not retain, own, or dispose it.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithHeader(string, string)

Adds or replaces a default request header.

public TestScenarioBuilder<TEntryPoint> WithHeader(string name, string value)

Parameters

name string: The non-empty header name. Matching existing configured names is case-insensitive.
value string: The non-null header value. HTTP header validation occurs when the client is created.

Returns

TestScenarioBuilder<TEntryPoint>: This builder so additional scenario steps can be configured.

WithoutCookies()

Prevents automatic cookie persistence.

public TestScenarioBuilder<TEntryPoint> WithoutCookies()

Returns

TestScenarioBuilder<TEntryPoint>: This builder with automatic cookie handling disabled for the scenario client.

WithoutRedirects()

Prevents automatic HTTP redirect handling.

public TestScenarioBuilder<TEntryPoint> WithoutRedirects()

Returns

TestScenarioBuilder<TEntryPoint>: This builder with automatic redirects disabled for the scenario client.