Class TestClientBuilder<TEntryPoint>

Namespace: XBullet.EasyTesting.Hosting

Assembly: XBullet.EasyTesting.dll

Fluently configures a client created by an authenticated application factory.

public sealed class TestClientBuilder<TEntryPoint> where TEntryPoint : class

Type Parameters

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

Inheritance: object

TestClientBuilder<TEntryPoint>

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. Configure and build a client from one execution flow. Authentication-selection methods replace only the simulated identity or bearer token unless their documentation states otherwise; explicitly configured headers and handlers remain.

Methods

AsAnonymous()

Configures the client to send no test identity.

public TestClientBuilder<TEntryPoint> AsAnonymous()

Returns

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

AsApiKey(Action<TestApiKeyBuilder>)

Builds an API-key-shaped identity for this client.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsAzureAdUser(Action<TestAzureAdUserBuilder>)

Builds an Azure AD-shaped identity for this client.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsExpiredJwt(Action<TestJwtBuilder>?)

Sends an expired locally signed bearer token.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsFederatedUser(Action<TestFederatedUserBuilder>)

Builds a Federation identity with an additional API-user identity.

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

Parameters

configure Action<TestFederatedUserBuilder>: The callback invoked synchronously once with a new Federation user builder targeting the configured Federation scheme. It is not retained or invoked concurrently.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwt(Action<TestJwtBuilder>?)

Creates and sends a locally signed bearer token through the application's real JWT handler.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwt(string, Action<TestJwtBuilder>?)

Creates a token for a named local authority and sends it through the real JWT handler.

public TestClientBuilder<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. The callback runs once and is not retained.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwtNotYetValid(Action<TestJwtBuilder>?)

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

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

Parameters

configure Action<TestJwtBuilder>: Configures token claims synchronously 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

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwtWithInvalidSignature(Action<TestJwtBuilder>?)

Sends a token whose signature is invalid for a known key identifier.

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

Parameters

configure Action<TestJwtBuilder>: Configures token claims synchronously 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

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwtWithUnknownKey(Action<TestJwtBuilder>?)

Sends a token whose key identifier is absent from JWKS.

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

Parameters

configure Action<TestJwtBuilder>: Configures token claims synchronously 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

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwtWithWrongAudience(Action<TestJwtBuilder>?)

Sends a locally signed bearer token with an invalid audience.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsJwtWithWrongIssuer(Action<TestJwtBuilder>?)

Sends a locally signed bearer token with an invalid issuer.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsMalformedJwt(string)

Sends a deliberately malformed bearer token.

public TestClientBuilder<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

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsUnsignedJwt(Action<TestJwtBuilder>?)

Sends an unsigned JWT.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsUser(Action<TestUserBuilder>)

Builds and configures the test identity used by this client.

public TestClientBuilder<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. The resulting identity replaces any configured bearer token.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsUser(Action<TestUserBuilder>, string)

Builds a test identity that targets a named simulated scheme.

public TestClientBuilder<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. It is not retained or invoked concurrently.
authenticationScheme string: The non-empty application authentication-scheme name written to the transported identity. The application must have a corresponding simulated scheme registration.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

AsUser(TestUser)

Configures the client to send the supplied test identity.

public TestClientBuilder<TEntryPoint> AsUser(TestUser user)

Parameters

user TestUser: The non-null simulated identity to serialize into the test-authentication request header. The builder retains the immutable value but does not own it. This selection replaces any previously configured bearer token.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

Build()

Creates the configured client.

public HttpClient Build()

Returns

HttpClient: A new client owned by the caller. Dispose it to release its handlers and connection resources. The client does not own the application factory.

WithApiKeyHeader(string, string?)

Injects a real API key into every request header.

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

Parameters

value string: The non-empty API-key secret sent without validation. The caller is responsible for using test-only credentials and preventing 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

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithApiKeyQuery(string, string?)

Injects a real API key into every request query string.

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

Parameters

value string: The non-empty API-key secret appended to every request 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 name configured for end-to-end API-key authentication is used.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithBaseAddress(Uri)

Sets the base address used by relative requests.

public TestClientBuilder<TEntryPoint> WithBaseAddress(Uri baseAddress)

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithBearerToken(string)

Sends an existing bearer token through the application's configured authentication handler. This can be used with tokens returned by ASP.NET Core Identity API endpoints.

public TestClientBuilder<TEntryPoint> WithBearerToken(string token)

Parameters

token string: The non-empty raw bearer token sent without validation. The caller is responsible for using test credentials and preventing the token from appearing in logs or diagnostics. This value replaces any configured simulated identity.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithClientCertificate(Action<TestClientCertificateBuilder>?)

Creates and transports a self-signed client certificate to the real certificate handler.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithClientCertificate(X509Certificate2)

Transports an existing client certificate to the real certificate handler.

public TestClientBuilder<TEntryPoint> WithClientCertificate(X509Certificate2 certificate)

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithClientCertificate(string, Action<TestClientCertificateBuilder>?)

Creates a client certificate for a named certificate authentication scheme.

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

Parameters

authenticationScheme string: The non-empty registered certificate authentication scheme that must accept the transported certificate.
configure Action<TestClientCertificateBuilder>: Configures a new self-signed certificate synchronously before it is exported. When null, certificate-builder defaults are used. The callback runs once and is not retained.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithClientCertificate(string, X509Certificate2)

Transports an existing client certificate for a named authentication scheme.

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

Parameters

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

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithHandler(DelegatingHandler)

Adds a delegating handler to the test client's HTTP pipeline.

public TestClientBuilder<TEntryPoint> WithHandler(DelegatingHandler handler)

Parameters

handler DelegatingHandler: The handler added after built-in redirect and cookie handlers, in registration order. Its InnerHandler must be null. Ownership transfers to the client created by Build(), which disposes it with the pipeline.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithHeader(string, string)

Adds or replaces a default request header.

public TestClientBuilder<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 built; an empty value is passed through to that validation.

Returns

TestClientBuilder<TEntryPoint>: This builder so additional client behavior can be configured.

WithoutCookies()

Prevents automatic cookie persistence.

public TestClientBuilder<TEntryPoint> WithoutCookies()

Returns

TestClientBuilder<TEntryPoint>: This builder with automatic cookie handling disabled for the created client.

WithoutRedirects()

Prevents automatic HTTP redirect handling.

public TestClientBuilder<TEntryPoint> WithoutRedirects()

Returns

TestClientBuilder<TEntryPoint>: This builder with automatic redirects disabled for the created client.