Namespace Codebelt.Extensions.Xunit.Hosting.AspNetCore

Exercise an ASP.NET Core application's real entry point, dependency-injection graph, middleware pipeline, and endpoints through an in-memory TestServer. The Codebelt.Extensions.Xunit.Hosting.AspNetCore namespace can bootstrap modern minimal hosting and conventional Startup applications, apply test-only web-host configuration, and return either an owned test context or a reusable xUnit fixture.

For a focused endpoint or service-override test, start with WebApplicationTestFactory.Create<TEntryPoint> or its one-request RunAsync<TEntryPoint> convenience. Use WebApplicationTest<TEntryPoint, TFixture> with BlockingManagedWebApplicationFixture<TEntryPoint> when several tests should share the bootstrapped application. Reach for WebHostTestFactory or MinimalWebHostTestFactory when the test defines its own pipeline instead of loading an existing application.

Availability: .NET 10 and .NET 9

Complements: ASP.NET Core integration tests · WebApplicationFactory · Microsoft.AspNetCore.TestHost namespace 🔗

Choose an ASP.NET Core Testing Path

When you need to	Start with	Why
Bootstrap an existing ASP.NET Core application for one focused test	`WebApplicationTestFactory.Create<TEntryPoint>`	Returns an owned `IHostTest` whose host exposes the application's `TestServer`, services, configuration, and environment.
Send one request to an existing application	`WebApplicationTestFactory.RunAsync<TEntryPoint>`	Combines application startup, `HttpClient` creation, request execution, and cleanup in one call.
Share an existing application across an xUnit test class	`WebApplicationTest<TEntryPoint, TFixture>` with `BlockingManagedWebApplicationFixture<TEntryPoint>`	Uses xUnit fixture lifetime while keeping the real application entry point and `TestServer`.
Define services and middleware entirely inside the test	`WebHostTestFactory` or `MinimalWebHostTestFactory`	Builds a purpose-specific in-memory pipeline without loading an application project.
Attach observers or change state before startup	A `SelfManaged` web fixture	Builds the host and pipeline but leaves startup to the test.

Compared with WebApplicationFactory

WebApplicationTestFactory is an alternative integration-test entry point, not a drop-in replacement for Microsoft.AspNetCore.Mvc.Testing.WebApplicationFactory<TEntryPoint>.

Concern	`WebApplicationTestFactory`	Microsoft `WebApplicationFactory<TEntryPoint>`
Acquisition	Static `Create<TEntryPoint>` or `RunAsync<TEntryPoint>` returns a Codebelt test context.	Instantiate or inject a factory, then call `CreateClient`.
Customization	Pass an `IWebHostBuilder` callback at the call site.	Subclass and override `ConfigureWebHost`, or compose with `WithWebHostBuilder`.
Sharing	Use Codebelt's `WebApplicationTest` and fixture types when tests should share a context.	Commonly shared directly through xUnit `IClassFixture<WebApplicationFactory<TEntryPoint>>`.
Lifecycle	The caller disposes the returned context, or delegates ownership to a Codebelt fixture.	The factory owns its `TestServer` and clients and is disposed by the caller or xUnit fixture lifecycle.
Scope	Matches Codebelt's equivalent entry-point pattern for console, worker, and Generic Host applications.	Purpose-built for ASP.NET Core applications and includes MVC-testing conventions such as client options and content-root discovery.

Fixture Naming Convention

ASP.NET Core host fixtures follow the same lifecycle naming convention as the hosting package:

Prefix	Convention
`Managed`	The fixture owns host creation, configuration, startup and disposal using the default host runner.
`SelfManaged`	The fixture owns host creation and configuration, but leaves host startup to the test.
`BlockingManaged`	The fixture owns the host lifecycle and starts the host synchronously before returning control to the test.

Application-entry-point fixtures use the BlockingManaged prefix by default. ASP.NET Core application tests expose a TestServer, and callers receive a started server after fixture initialization. Use BlockingManagedWebApplicationFixture<TEntryPoint> when testing an existing ASP.NET Core application entry point with TestServer.

BlockingManagedWebHostFixture remains the opt-in blocking variant for the lower-level web host fixture family. The application-entry-point fixture is named BlockingManagedWebApplicationFixture<TEntryPoint> directly because this API is blocking by convention from its first release.

Extension Members

Type	Ext	Methods
HttpClient	⬇️	`ToHttpResponseMessageAsync`
IHostApplicationBuilder	⬇️	`ToHostBuilder`
IServiceCollection	⬇️	`AddFakeHttpContextAccessor`
IWebApplicationFixture<TEntryPoint>	⬇️	`HasValidState<TEntryPoint>`
IWebHostFixture	⬇️	`HasValidState`
IWebMinimalHostFixture	⬇️	`HasValidState`

Classes

BlockingManagedWebApplicationFixture<TEntryPoint>: Provides a blocking managed implementation of the IWebApplicationFixture<TEntryPoint> interface.

BlockingManagedWebHostFixture: Extends the default implementation of the IWebHostFixture interface to be synchronous e.g., blocking where exceptions can be captured.

HostBuilderApplicationExtensions: Provides extension methods for IHostApplicationBuilder.

HttpClientExtensions: Provides extension methods for the HttpClient class.

ManagedWebHostFixture: Provides a default implementation of the IWebHostFixture interface.

ManagedWebMinimalHostFixture: Provides a default implementation of the IWebMinimalHostFixture interface.

MinimalWebHostTestFactory: Provides a set of static methods for ASP.NET Core (including, but not limited to MVC, Razor and related) unit testing (minimal style).

MinimalWebHostTest<T>: Represents a base class from which all implementations of unit testing, that uses Microsoft Dependency Injection and depends on ASP.NET Core (minimal style), should derive.

SelfManagedWebHostFixture: Represents a self-managed implementation of the ManagedWebHostFixture class.

SelfManagedWebMinimalHostFixture: Represents a self-managed implementation of the ManagedMinimalHostFixture class.

ServiceCollectionExtensions: Extension methods for the IServiceCollection interface.

WebApplicationFixtureExtensions: Extension methods for the IWebApplicationFixture<TEntryPoint> interface.

WebApplicationTestFactory: Provides a set of static methods for ASP.NET Core testing that bootstraps an existing application entry point.

WebApplicationTest<TEntryPoint, T>: Represents a base class from which all implementations of unit testing, that uses Microsoft Dependency Injection and depends on an existing ASP.NET Core application entry point, should derive.

WebHostFixtureExtensions: Extension methods for the IWebHostFixture interface.

WebHostTestFactory: Provides a set of static methods for ASP.NET Core (including, but not limited to MVC, Razor and related) unit testing.

WebHostTest<T>: Represents a base class from which all implementations of unit testing, that uses Microsoft Dependency Injection and depends on ASP.NET Core, should derive.

WebMinimalHostFixtureExtensions: Extension methods for the IWebMinimalHostFixture interface.

Interfaces

IPipelineTest: Represents the members needed for ASP.NET Core pipeline testing.

IWebApplicationFixture<TEntryPoint>: Provides a way to use Microsoft Dependency Injection in tests that bootstrap an existing ASP.NET Core application entry point.

IWebHostFixture: Provides a way to use Microsoft Dependency Injection in unit tests tailored for ASP.NET Core.

IWebHostTest: Represents the members needed for ASP.NET Core (including but not limited to MVC, Razor and related) testing.

IWebMinimalHostFixture: Provides a way to use Microsoft Dependency Injection in unit tests (minimal style).