AppSurface Search
Section API Reference
API Reference Language: C# Component: Auth Audience: developer

Testing

Enum

AppSurfaceTestAuthSchemeMode

Source

Selects how the AppSurface test authentication scheme is registered with ASP.NET Core.

Remarks

These modes exist so a test harness cannot silently change host authentication behavior. Use DefaultScheme for the quickest WebApplicationFactory path, NamedScheme when policies opt in to a specific scheme, and NoDefault when the test host must keep every existing default authentication setting untouched. The numeric values are explicit because this public enum may be persisted, serialized, or bound by applications. New values should be appended without changing the values documented here.

Type

AppSurfaceTestInnerPolicyEvaluator

Source

Holds the host policy evaluator registration that Auth.Testing decorates.

Parameters

  • policyEvaluatorThe evaluator that was registered before AddAppSurfaceTestAuth installed test-only diagnostics.
Property

PolicyEvaluator

IAppSurfaceAspNetCorePolicyEvaluator PolicyEvaluator { get; } Source

Gets the host evaluator that continues to own real policy evaluation and result mapping.

Type

AppSurfaceTestAuthAssertionException

Source

Exception thrown by framework-neutral AppSurface auth testing assertion helpers.

Type

AppSurfaceTestPersonaRegistry

Source

Stores the immutable per-factory persona lookup used by AppSurface test auth helpers.

Remarks

Names use ordinal comparison and must be unique after AppSurfaceTestPersona trimming. Create the registry only after options are fully configured; later option changes are intentionally not observed by an existing registry.

Method

Create

AppSurfaceTestPersonaRegistry Create(AppSurfaceTestAuthOptions options) Source

Creates a registry from configured personas and validates duplicate ordinal names.

Parameters

  • optionsConfigured test auth options.

Returns

An immutable registry snapshot.

Exceptions

  • InvalidOperationExceptionThrown when two personas share the same ordinal name.
Method

Require

AppSurfaceTestPersona Require(string personaName) Source

Gets a registered persona or throws a setup diagnostic for public helper failures.

Parameters

  • personaNameOrdinal persona name. Leading and trailing whitespace is trimmed before lookup.

Returns

The matching persona.

Exceptions

  • ArgumentExceptionThrown when personaName is blank.
  • InvalidOperationExceptionThrown when the persona is not registered.
Method

TryGet

bool TryGet(string? personaName, out AppSurfaceTestPersona persona) Source

Attempts to get a persona by ordinal name without throwing for missing, blank, or null values.

Parameters

  • personaNameOrdinal persona name. Leading and trailing whitespace is trimmed before lookup.
  • personaThe matching persona when found.

Returns

true when the persona exists; otherwise false.

Type

AppSurfaceTestAuthDefaults

Source

Default names used by the AppSurface auth testing harness.

Type

AppSurfaceTestAuthHttpRequestMessageExtensions

Source

Request-level helpers for selecting AppSurface test auth personas.

Method

WithAppSurfaceTestPersona

HttpRequestMessage WithAppSurfaceTestPersona(this HttpRequestMessage request, string personaName) Source

Selects a configured AppSurface test auth persona for a single request.

Parameters

  • requestRequest to update.
  • personaNameConfigured persona name to select.

Returns

The same request for chaining.

Remarks

Prefer CreateAppSurfaceClient(...) for whole-client persona selection. This helper is for tests that need several personas from one client. The harness still treats no selection as anonymous.

Type

AppSurfaceTestPersona

Source

Describes one authenticated persona that the AppSurface auth testing harness can place on a request.

Remarks

Persona names are matched with ordinal comparison. The subject is added with the configured subject claim type, and additional claims are copied into the generated principal. Do not put secrets, bearer tokens, cookies, or provider credentials in persona claims; this type models the already-authenticated principal a real ASP.NET Core handler would have produced.

Property

Name

string Name { get; } Source

Gets the ordinal persona name.

Property

SubjectId

string SubjectId { get; } Source

Gets the subject identifier added to the generated principal.

Property

Claims

IReadOnlyList<Claim> Claims { get; } Source

Gets additional claim snapshots copied into the generated principal.

Type

AppSurfaceTestAuthWebApplicationFactoryExtensions

Source

WebApplicationFactory helpers for AppSurface auth testing.

Method

WithAppSurfaceTestAuth

WebApplicationFactory<TEntryPoint> WithAppSurfaceTestAuth<TEntryPoint>(this WebApplicationFactory<TEntryPoint> factory, Action<AppSurfaceTestAuthOptions>? configure = null) Source

Returns a WebApplicationFactory configured with AppSurface test authentication.

Type Parameters

  • TEntryPointApplication entry point type used by WebApplicationFactory.

Parameters

  • factoryFactory to clone with test auth services.
  • configureOptional test auth options callback.

Returns

A cloned factory with AppSurface test auth registered.

Remarks

The cloned factory uses the Testing environment and then registers the harness through AppSurfaceTestAuthServiceCollectionExtensions.AddAppSurfaceTestAuth.

Method

CreateAppSurfaceClient

HttpClient CreateAppSurfaceClient<TEntryPoint>(this WebApplicationFactory<TEntryPoint> factory, string personaName, WebApplicationFactoryClientOptions? options = null) Source

Creates an HTTP client that selects a configured AppSurface test auth persona for every request.

Type Parameters

  • TEntryPointApplication entry point type used by WebApplicationFactory.

Parameters

  • factoryFactory previously configured with WithAppSurfaceTestAuth{TEntryPoint}.
  • personaNameConfigured persona name to select.
  • optionsOptional WebApplicationFactory client options.

Returns

A client whose default headers select the persona.

Type

AppSurfaceTestAuthOptions

Source

Configures the AppSurface auth testing harness.

Remarks

Defaults are intentionally test-host oriented: the scheme name is stable, WebApplicationFactory quickstarts use the test scheme as the default, and production-like environments are blocked. Subject mapping is not changed unless SubjectClaimType is set.

Method

AddPersona

2 overloads
AppSurfaceTestAuthOptions AddPersona(string name, string subjectId, IEnumerable<Claim>? claims = null) Source

Adds a persona with the supplied subject and claims.

Parameters

  • nameStable ordinal persona name.
  • subjectIdStable host-owned subject identifier.
  • claimsAdditional claims copied into the generated principal.

Returns

The current options instance for chaining.

AppSurfaceTestAuthOptions AddPersona(AppSurfaceTestPersona persona) Source

Adds a persona definition.

Parameters

  • personaPersona to add to the registry.

Returns

The current options instance for chaining.

Property

SchemeName

string SchemeName { get; set; } Source

Gets or sets the ASP.NET Core authentication scheme registered for test personas.

Property

SchemeMode

AppSurfaceTestAuthSchemeMode SchemeMode { get; set; } Source

Gets or sets how the test scheme is applied to the host authentication setup.

Property

SubjectClaimType

string? SubjectClaimType { get; set; } Source

Gets or sets the subject claim type used by generated principals and AppSurface subject mapping.

Remarks

When this value is null, the harness leaves host AppSurface subject mapping alone and emits System.Security.Claims.ClaimTypes.NameIdentifier, matching the first default Auth.AspNetCore subject claim type.

Property

AllowProductionEnvironmentForTestHost

bool AllowProductionEnvironmentForTestHost { get; set; } Source

Gets or sets a value indicating whether the harness may run in a production-like environment.

Remarks

Keep this false for normal tests. Set it only for production-like integration hosts that deliberately use test authentication and never receive real traffic.

Property

Personas

IReadOnlyList<AppSurfaceTestPersona> Personas { get; } Source

Gets the configured immutable persona definitions.

Type

AppSurfaceAuthTestAssert

Source

Framework-neutral assertion helpers for AppSurface auth results and ProblemDetails responses.

Remarks

The helpers throw AppSurfaceTestAuthAssertionException instead of depending on a specific test framework. They are intended for package smoke tests, consumer examples, and teams that want stable AppSurface auth diagnostics without pulling xUnit into production package references.

Method

HasOutcome

AppSurfaceAuthResult HasOutcome(AppSurfaceAuthResult result, AppSurfaceAuthOutcome expectedOutcome, AppSurfaceAuthReason? expectedReason = null) Source

Verifies an AppSurface auth result outcome and optional reason.

Parameters

  • resultAuth result to inspect.
  • expectedOutcomeExpected high-level outcome.
  • expectedReasonOptional expected reason.

Returns

The inspected result for fluent test code.

Method

HasProblemDetails

JsonElement HasProblemDetails(JsonElement problem, AppSurfaceAuthOutcome expectedOutcome, AppSurfaceAuthReason expectedReason, int expectedStatus, string? expectedPolicyName = null) Source

Verifies AppSurface auth ProblemDetails extensions.

Parameters

  • problemProblemDetails JSON element.
  • expectedOutcomeExpected appsurfaceAuthOutcome extension value.
  • expectedReasonExpected appsurfaceAuthReason extension value.
  • expectedStatusExpected HTTP status in the ProblemDetails payload.
  • expectedPolicyNameOptional expected appsurfacePolicyName extension value.

Returns

The inspected JSON element for fluent test code.

Type

AppSurfaceTestAuthDiagnosticCodes

Source

Stable diagnostic codes emitted by the AppSurface auth testing harness.

Remarks

Codes are safe to show in test output, troubleshooting documentation, and CI logs. They identify setup mistakes in the harness rather than production authentication decisions.

Type

AppSurfaceTestAuthServiceCollectionExtensions

Source

Registers AppSurface test authentication services for ASP.NET Core integration tests.

Method

AddAppSurfaceTestAuth

IServiceCollection AddAppSurfaceTestAuth(this IServiceCollection services, Action<AppSurfaceTestAuthOptions>? configure = null) Source

Adds a test-only authentication scheme and immutable persona registry for AppSurface auth tests.

Parameters

  • servicesService collection that receives the test harness.
  • configureOptional test auth options callback.

Returns

The same service collection for chaining.

Remarks

This method composes ForgeTrust.AppSurface.Auth.AspNetCore so normal ASP.NET Core policy evaluation and AppSurface result mapping still run. It does not create production users, identity providers, cookies, tokens, or session freshness checks.

Type

AppSurfaceTestAspNetCorePolicyEvaluator

Source

Decorates the host AppSurface policy evaluator with test-only persona diagnostics.

Remarks

The inner evaluator remains responsible for real ASP.NET Core policy evaluation and AppSurface result mapping. This decorator pre-validates request-level persona selection from the private test transport and also converts late unknown-persona markers set by authentication handlers into setup failures after the inner evaluator runs.