Class EntityFrameworkWebApplicationFactory<TEntryPoint, TDbContext>

Namespace: XBullet.EasyTesting.EntityFrameworkCore

Assembly: XBullet.EasyTesting.EntityFrameworkCore.dll

An authenticated application factory with scoped, serialized actions for an EF Core test database.

public abstract class EntityFrameworkWebApplicationFactory<TEntryPoint, TDbContext> : AuthenticatedWebApplicationFactory<TEntryPoint>, IDisposable, IAsyncDisposable where TEntryPoint : class where TDbContext : DbContext

Type Parameters

TEntryPoint: The application entry-point type hosted by the test factory.
TDbContext: The EF Core context type replaced and resolved for database operations.

Inheritance: object

WebApplicationFactory<TEntryPoint>

AuthenticatedWebApplicationFactory<TEntryPoint>

EntityFrameworkWebApplicationFactory<TEntryPoint, TDbContext>

Implements: IDisposable

IAsyncDisposable

Derived: InMemoryEntityFrameworkWebApplicationFactory<TEntryPoint, TDbContext>

StartupEntityFrameworkWebApplicationFactory<TStartup, TDbContext>

Inherited Members: AuthenticatedWebApplicationFactory<TEntryPoint>.Create(Action<IServiceCollection>, Action<IConfigurationBuilder>, Action<TestAuthenticationSchemeBuilder>)

AuthenticatedWebApplicationFactory<TEntryPoint>.CreateWithHostSettings(Action<IDictionary<string, string>>, Action<IServiceCollection>, Action<IConfigurationBuilder>, Action<TestAuthenticationSchemeBuilder>)

AuthenticatedWebApplicationFactory<TEntryPoint>.ConfigureWebHost(IWebHostBuilder)

AuthenticatedWebApplicationFactory<TEntryPoint>.ConfigureTestConfiguration(IConfigurationBuilder)

AuthenticatedWebApplicationFactory<TEntryPoint>.ConfigureTestHostSettings(IDictionary<string, string>)

AuthenticatedWebApplicationFactory<TEntryPoint>.ConfigureTestAuthentication(TestAuthenticationSchemeBuilder)

AuthenticatedWebApplicationFactory<TEntryPoint>.CreateAnonymousClient(WebApplicationFactoryClientOptions)

AuthenticatedWebApplicationFactory<TEntryPoint>.CreateAuthenticatedClient(TestUser, WebApplicationFactoryClientOptions)

AuthenticatedWebApplicationFactory<TEntryPoint>.Client()

AuthenticatedWebApplicationFactory<TEntryPoint>.Scenario()

AuthenticatedWebApplicationFactory<TEntryPoint>.JwtAuthority(string)

AuthenticatedWebApplicationFactory<TEntryPoint>.AuthenticationEvents

AuthenticatedWebApplicationFactory<TEntryPoint>.CreateTestScenarioScopeAsync(Action<TestScenarioScopeBuilder>, CancellationToken)

AuthenticatedWebApplicationFactory<TEntryPoint>.RunInTestScenarioScopeAsync(Func<TestScenarioScope<TEntryPoint>, CancellationToken, Task>, Action<TestScenarioScopeBuilder>, CancellationToken)

AuthenticatedWebApplicationFactory<TEntryPoint>.RunInTestScenarioScopeAsync<TResult>(Func<TestScenarioScope<TEntryPoint>, CancellationToken, Task<TResult>>, Action<TestScenarioScopeBuilder>, CancellationToken)

AuthenticatedWebApplicationFactory<TEntryPoint>.RegisterScenarioResource(string, Action, Func<object>)

AuthenticatedWebApplicationFactory<TEntryPoint>.RegisterScenarioResource(string, ITestScenarioResource)

AuthenticatedWebApplicationFactory<TEntryPoint>.ConfigureScenarioEnvironment(TestScenarioEnvironmentBuilder)

WebApplicationFactory<TEntryPoint>.WithWebHostBuilder(Action<IWebHostBuilder>)

WebApplicationFactory<TEntryPoint>.UseKestrel()

WebApplicationFactory<TEntryPoint>.UseKestrel(int)

WebApplicationFactory<TEntryPoint>.UseKestrel(Action<KestrelServerOptions>)

WebApplicationFactory<TEntryPoint>.StartServer()

WebApplicationFactory<TEntryPoint>.GetTestAssemblies()

WebApplicationFactory<TEntryPoint>.CreateHostBuilder()

WebApplicationFactory<TEntryPoint>.CreateWebHostBuilder()

WebApplicationFactory<TEntryPoint>.CreateServer(IWebHostBuilder)

WebApplicationFactory<TEntryPoint>.CreateServer(IServiceProvider)

WebApplicationFactory<TEntryPoint>.CreateHost(IHostBuilder)

WebApplicationFactory<TEntryPoint>.CreateClient()

WebApplicationFactory<TEntryPoint>.CreateClient(WebApplicationFactoryClientOptions)

WebApplicationFactory<TEntryPoint>.CreateDefaultClient(params DelegatingHandler[])

WebApplicationFactory<TEntryPoint>.ConfigureClient(HttpClient)

WebApplicationFactory<TEntryPoint>.CreateDefaultClient(Uri, params DelegatingHandler[])

WebApplicationFactory<TEntryPoint>.Dispose()

WebApplicationFactory<TEntryPoint>.DisposeAsync()

WebApplicationFactory<TEntryPoint>.Server

WebApplicationFactory<TEntryPoint>.Services

WebApplicationFactory<TEntryPoint>.Factories

WebApplicationFactory<TEntryPoint>.ClientOptions

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

See database-backed application tests.

Methods

CaptureScenarioDiagnosticsAsync(TestScenarioScope<TEntryPoint>, CancellationToken)

Captures factory-specific state before a failed scenario is cleaned up.

protected override ValueTask<object?> CaptureScenarioDiagnosticsAsync(TestScenarioScope<TEntryPoint> scope, CancellationToken cancellationToken)

Parameters

scope TestScenarioScope<TEntryPoint>: The failed, factory-owned scenario scope. An override may inspect it but must not dispose it.
cancellationToken CancellationToken: Cancels diagnostic capture. The built-in failure path passes a non-cancelable token so diagnostics can be attempted even when the test token was canceled.

Returns

ValueTask<object>: A serializable diagnostic value, or null when the factory has no additional state. Exceptions are converted to a diagnostic-capture failure record.

CleanupScenarioAsync(TestScenarioScope<TEntryPoint>, CancellationToken)

Cleans factory-specific state before the isolated scenario host is disposed.

protected override Task CleanupScenarioAsync(TestScenarioScope<TEntryPoint> scope, CancellationToken cancellationToken)

Parameters

scope TestScenarioScope<TEntryPoint>: The factory-owned scenario scope being cleaned up. An override may inspect it but must not dispose it.
cancellationToken CancellationToken: Cancels factory-specific cleanup when a caller supplies a cancelable token. Normal scope disposal passes a non-cancelable token so remaining cleanup operations can still run.

Returns

Task: A task that completes when factory-specific cleanup has finished.

CleanupScenarioDatabaseAsync(TDbContext, CancellationToken)

Cleans up a scenario database. The default implementation retries SQLite file cleanup and attaches SqliteDatabaseCleanupDiagnostics to terminal cleanup failures. Override this when the application owns database disposal or cleanup.

protected virtual Task CleanupScenarioDatabaseAsync(TDbContext database, CancellationToken cancellationToken)

Parameters

database TDbContext: The scenario-owned scoped context. Use it only for this callback and do not retain or dispose it.
cancellationToken CancellationToken: A token that cancels deletion and transient SQLite retry delays.

Returns

Task: A task that completes after cleanup. The default deletes the database; for SQLite it clears connection pools and retries transient file-lock failures before attaching terminal diagnostics.

ConfigureAdditionalServicesForScenario(IServiceCollection, TestScenarioContext)

Allows derived factories to add services that exist only in scenario hosts.

protected virtual void ConfigureAdditionalServicesForScenario(IServiceCollection services, TestScenarioContext context)

Parameters

services IServiceCollection: The mutable scenario-host service collection to update in place after database registration.
context TestScenarioContext: The scenario configuration context. It may be used to register scenario-owned resources and must not be retained after configuration.

ConfigureAdditionalServicesForTests(IServiceCollection)

Allows derived factories to replace services unrelated to the database.

protected virtual void ConfigureAdditionalServicesForTests(IServiceCollection services)

Parameters

services IServiceCollection: The mutable factory-host service collection to update in place after database registration. The host owns the collection and all registered services.

ConfigureDatabaseServices(IServiceCollection)

Registers TDbContext with the chosen test provider and connection.

protected abstract void ConfigureDatabaseServices(IServiceCollection services)

Parameters

services IServiceCollection: The mutable test-host service collection to update in place. The host owns the collection and all registered services.

ConfigureScenarioDatabaseServices(IServiceCollection, TestScenarioContext)

Registers the database used by one scenario. Override this to allocate a distinct database, schema, or connection and register its cleanup through context.

protected virtual void ConfigureScenarioDatabaseServices(IServiceCollection services, TestScenarioContext context)

Parameters

services IServiceCollection: The mutable scenario-host service collection to update in place. Existing registrations for TDbContext have already been removed.
context TestScenarioContext: The scenario configuration context. Use it to identify the scenario and register resources whose ownership is transferred to the scenario for cleanup; do not retain the context.

ConfigureServicesForScenario(IServiceCollection, TestScenarioContext)

Adds or replaces services that exist only for one scenario host.

protected override sealed void ConfigureServicesForScenario(IServiceCollection services, TestScenarioContext context)

Parameters

services IServiceCollection: The scenario host's service collection to mutate after environment resources have contributed services. An override must not retain or dispose it.
context TestScenarioContext: The scenario context used to register scenario-owned cleanup and inspect the stable scenario identifier. The factory retains ownership of the context.

ConfigureServicesForTests(IServiceCollection)

Replaces the application's concrete context registration and delegates provider configuration to ConfigureDatabaseServices(IServiceCollection).

protected override sealed void ConfigureServicesForTests(IServiceCollection services)

Parameters

services IServiceCollection: The mutable test-host service collection. Existing context, context-factory, and options registrations for TDbContext are removed before replacements are added.

Database()

Starts a fluent database scenario definition.

public DatabaseScenarioBuilder<TEntryPoint, TDbContext> Database()

Returns

DatabaseScenarioBuilder<TEntryPoint, TDbContext>: A new mutable, single-use builder targeting the factory database.

Database(TestScenarioScope<TEntryPoint>)

Starts a fluent database scenario against a test scenario's isolated database.

public DatabaseScenarioBuilder<TEntryPoint, TDbContext> Database(TestScenarioScope<TEntryPoint> scope)

Parameters

scope TestScenarioScope<TEntryPoint>: The non-null, active scenario scope whose service provider supplies the context. The caller retains ownership of the scope.

Returns

DatabaseScenarioBuilder<TEntryPoint, TDbContext>: A new mutable, single-use builder targeting the scope's isolated database.

Dispose(bool)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

protected override void Dispose(bool disposing)

Parameters

disposing bool: true to release both managed and unmanaged resources; false to release only unmanaged resources.

ExecuteDatabaseAsync(Func<TDbContext, CancellationToken, Task>, CancellationToken)

Executes a scoped database action and persists its tracked changes.

public Task ExecuteDatabaseAsync(Func<TDbContext, CancellationToken, Task> action, CancellationToken cancellationToken = default)

Parameters

action Func<TDbContext, CancellationToken, Task>: A non-null asynchronous callback invoked once with a fresh factory-owned context and the supplied token. It must not retain or dispose the context. The factory saves tracked changes after the callback succeeds.
cancellationToken CancellationToken: A token that cancels waiting for serialized access and is passed to the callback and save. The default token does not request cancellation.

Returns

Task: A task that completes after the callback, save, and scoped-context disposal.

ExecuteDatabaseAsync(TestScenarioScope<TEntryPoint>, Func<TDbContext, CancellationToken, Task>, CancellationToken)

Executes an action and saves changes in a scenario's isolated database.

public Task ExecuteDatabaseAsync(TestScenarioScope<TEntryPoint> scope, Func<TDbContext, CancellationToken, Task> action, CancellationToken cancellationToken = default)

Parameters

scope TestScenarioScope<TEntryPoint>: The non-null, active scenario scope whose service provider supplies the context. The caller retains ownership of the scope.
action Func<TDbContext, CancellationToken, Task>: A non-null asynchronous callback invoked once with a scenario-owned scoped context and the supplied token. It must not retain or dispose the context. Tracked changes are saved after it succeeds.
cancellationToken CancellationToken: A token passed to the callback and save operation. The default token does not request cancellation.

Returns

Task: A task that completes after the callback, save, and scoped-context disposal.

ExecuteInTransactionAsync(Func<TDbContext, CancellationToken, Task>, CancellationToken)

Executes an action in a database transaction, saves tracked changes, and commits on success.

public Task ExecuteInTransactionAsync(Func<TDbContext, CancellationToken, Task> action, CancellationToken cancellationToken = default)

Parameters

action Func<TDbContext, CancellationToken, Task>: A non-null asynchronous callback invoked once inside the transaction with a fresh factory-owned context and the supplied token. It must not retain or dispose the context.
cancellationToken CancellationToken: A token that cancels waiting for serialized access and is passed to transaction, callback, save, and commit operations. The default token does not request cancellation.

Returns

Task: A task that completes after the transaction commits and owned resources are disposed.

Remarks

The configured provider must support transactions. Failure before commit causes rollback on disposal.

InitializeDatabaseAsync(CancellationToken)

Creates the test database schema if it does not already exist.

public Task InitializeDatabaseAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: A token that cancels waiting for serialized access and schema creation. The default token does not request cancellation.

Returns

Task: A task that completes after EF Core has ensured the factory database exists.

InitializeScenarioAsync(TestScenarioScope<TEntryPoint>, CancellationToken)

Initializes state after the isolated scenario host has started.

protected override Task InitializeScenarioAsync(TestScenarioScope<TEntryPoint> scope, CancellationToken cancellationToken)

Parameters

scope TestScenarioScope<TEntryPoint>: The newly started, factory-owned scenario scope. An override may use it but must not dispose it.
cancellationToken CancellationToken: Cancels scenario initialization. When cancellation or another failure occurs, the scope is still cleaned up. The token is the one supplied to scope creation.

Returns

Task: A task that completes when scenario-specific initialization has finished.

InitializeScenarioDatabaseAsync(TDbContext, CancellationToken)

Initializes a scenario database. Override this to run application migrations, invoke a schema verifier, restore a template, or apply another application-specific lifecycle.

protected virtual Task InitializeScenarioDatabaseAsync(TDbContext database, CancellationToken cancellationToken)

Parameters

database TDbContext: The scenario-owned scoped context. Use it only for this callback and do not retain or dispose it.
cancellationToken CancellationToken: A token that cancels initialization operations.

Returns

Task: A task that completes after initialization. The default implementation deletes and recreates the complete isolated scenario database.

QueryDatabaseAsync<TResult>(Func<TDbContext, CancellationToken, Task<TResult>>, CancellationToken)

Executes a read operation in a fresh dependency-injection scope.

public Task<TResult> QueryDatabaseAsync<TResult>(Func<TDbContext, CancellationToken, Task<TResult>> query, CancellationToken cancellationToken = default)

Parameters

query Func<TDbContext, CancellationToken, Task<TResult>>: A non-null asynchronous callback invoked once with a fresh factory-owned context and the supplied token. It must fully materialize its result and must not retain or dispose the context.
cancellationToken CancellationToken: A token that cancels waiting for serialized access and is passed to the query. The default token does not request cancellation.

Returns

Task<TResult>: A task whose result is the materialized value produced by query. The caller owns the value; it must not require the disposed context for later enumeration or loading.

Type Parameters

TResult: The materialized result type returned by the query.

QueryDatabaseAsync<TResult>(TestScenarioScope<TEntryPoint>, Func<TDbContext, CancellationToken, Task<TResult>>, CancellationToken)

Executes a query in a scenario's isolated database.

public Task<TResult> QueryDatabaseAsync<TResult>(TestScenarioScope<TEntryPoint> scope, Func<TDbContext, CancellationToken, Task<TResult>> query, CancellationToken cancellationToken = default)

Parameters

scope TestScenarioScope<TEntryPoint>: The non-null, active scenario scope whose service provider supplies the context. The caller retains ownership of the scope.
query Func<TDbContext, CancellationToken, Task<TResult>>: A non-null asynchronous callback invoked once with a scenario-owned scoped context and the supplied token. It must fully materialize its result and must not retain or dispose the context.
cancellationToken CancellationToken: A token passed to the query. The default token does not request cancellation.

Returns

Task<TResult>: A task whose result is the materialized value produced by query. The caller owns the value; it must not depend on the disposed context.

Type Parameters

TResult: The materialized result type returned by the query.

RecreateDatabaseAsync(CancellationToken)

Deletes and recreates the complete test database. Only use this with an isolated test database.

public Task RecreateDatabaseAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: A token that cancels waiting for serialized access, deletion, or creation. The default token does not request cancellation.

Returns

Task: A task that completes after the factory database has been deleted and recreated.

SeedDatabaseAsync<TEntity>(IEnumerable<TEntity>, CancellationToken)

Adds entities to the test database and persists them.

public Task SeedDatabaseAsync<TEntity>(IEnumerable<TEntity> entities, CancellationToken cancellationToken = default) where TEntity : class

Parameters

entities IEnumerable<TEntity>: A non-null sequence of entities accepted by EF Core. The sequence is enumerated immediately and its elements are retained until the database operation completes.
cancellationToken CancellationToken: A token that cancels waiting for serialized access, adding entities, or saving changes. The default token does not request cancellation.

Returns

Task: A task that completes after all entities have been added and tracked changes saved.

Type Parameters

TEntity: The mapped reference-entity type to add.

WithDbContextAsync(Func<TDbContext, CancellationToken, Task>, CancellationToken)

Runs an action against a fresh scoped context without automatically saving tracked changes.

public Task WithDbContextAsync(Func<TDbContext, CancellationToken, Task> action, CancellationToken cancellationToken = default)

Parameters

action Func<TDbContext, CancellationToken, Task>: A non-null asynchronous callback invoked once with a fresh factory-owned context and the supplied token. It must not retain or dispose the context.
cancellationToken CancellationToken: A token that cancels waiting for serialized access and is passed unchanged to the callback. The default token does not request cancellation.

Returns

Task: A task that completes after the callback and scoped-context disposal.

WithDbContextAsync<TResult>(Func<TDbContext, CancellationToken, Task<TResult>>, CancellationToken)

Runs a function against a fresh scoped context without automatically saving tracked changes.

public Task<TResult> WithDbContextAsync<TResult>(Func<TDbContext, CancellationToken, Task<TResult>> action, CancellationToken cancellationToken = default)

Parameters

action Func<TDbContext, CancellationToken, Task<TResult>>: A non-null asynchronous callback invoked once with a fresh factory-owned context and the supplied token. It must fully materialize its result and must not retain or dispose the context.
cancellationToken CancellationToken: A token that cancels waiting for serialized access and is passed unchanged to the callback. The default token does not request cancellation.

Returns

Task<TResult>: A task whose result is the materialized value produced by action. The caller owns the value; it must not depend on the disposed context.

Type Parameters

TResult: The materialized result type returned by the callback.

WithScenarioDbContextAsync(TestScenarioScope<TEntryPoint>, Func<TDbContext, CancellationToken, Task>, CancellationToken)

Executes a scoped database action against a scenario's isolated context.

public Task WithScenarioDbContextAsync(TestScenarioScope<TEntryPoint> scope, Func<TDbContext, CancellationToken, Task> action, CancellationToken cancellationToken = default)

Parameters

scope TestScenarioScope<TEntryPoint>: The non-null, active scenario scope whose service provider supplies the context. The caller retains ownership of the scope.
action Func<TDbContext, CancellationToken, Task>: A non-null asynchronous callback invoked once with a scenario-owned scoped context and the supplied token. It must not retain or dispose the context. Changes are not saved automatically.
cancellationToken CancellationToken: A token passed unchanged to the callback. The default token does not request cancellation; the callback decides which operations observe it.

Returns

Task: A task that completes after the callback and scoped-context disposal.

WithScenarioDbContextAsync<TResult>(TestScenarioScope<TEntryPoint>, Func<TDbContext, CancellationToken, Task<TResult>>, CancellationToken)

Executes a scoped database query against a scenario's isolated context.

public Task<TResult> WithScenarioDbContextAsync<TResult>(TestScenarioScope<TEntryPoint> scope, Func<TDbContext, CancellationToken, Task<TResult>> action, CancellationToken cancellationToken = default)

Parameters

scope TestScenarioScope<TEntryPoint>: The non-null, active scenario scope whose service provider supplies the context. The caller retains ownership of the scope.
action Func<TDbContext, CancellationToken, Task<TResult>>: A non-null asynchronous callback invoked once with a scenario-owned scoped context and the supplied token. It must fully materialize its result and must not retain or dispose the context. Changes are not saved automatically.
cancellationToken CancellationToken: A token passed unchanged to the callback. The default token does not request cancellation.

Returns

Task<TResult>: A task whose result is the materialized value produced by action. The caller owns the value; it must not depend on the disposed context.

Type Parameters

TResult: The materialized result type returned by the callback.