.NET Aspire testing overview

.NET Aspire supports automated testing of your application through the 📦 Aspire.Hosting.Testing NuGet package. This package provides the DistributedApplicationTestingBuilder class, which is used to create a test host for your application. The testing builder launches your app host project in a background thread and manages its lifecycle, allowing you to control and manipulate the application and its resources through DistributedApplicationTestingBuilder or DistributedApplication instances.

By default, the testing builder disables the dashboard and randomizes the ports of proxied resources to enable multiple instances of your application to run concurrently. Once your test completes, disposing of the application or testing builder cleans up your app resources.

To get started writing your first integration test with .NET Aspire, see the Write your first .NET Aspire test article.

Testing .NET Aspire solutions

.NET Aspire's testing capabilities are designed specifically for closed-box integration testing of your entire distributed application. Unlike unit tests or open-box integration tests, which typically run individual components in isolation, .NET Aspire tests launch your complete solution (the app host and all its resources) as separate processes, closely simulating real-world scenarios.

Consider the following diagram that shows how the .NET Aspire testing project starts the app host, which then starts the application and its resources:

1. The test project starts the app host.
2. The app host process starts.
3. The app host runs the Database, API, and Frontend applications.
4. The test project sends an HTTP request to the Frontend application.

The diagram illustrates that the test project starts the app host, which then orchestrates the all dependent app resources—regardless of their type. The test project is able to send an HTTP request to the Frontend app, which depends on an API app, and the API app depends on a Database. A successful request confirms that the Frontend app can communicate with the API app, and that the API app can successfully get data from the Database. For more information on seeing this approach in action, see the Write your first .NET Aspire test article.

Use .NET Aspire testing when you want to:

• Verify end-to-end functionality of your distributed application.
• Ensure interactions between multiple services and resources (such as databases) behave correctly in realistic conditions.
• Confirm data persistence and integration with real external dependencies, like a PostgreSQL database.

If your goal is to test a single project in isolation, run components in-memory, or mock external dependencies, consider using WebApplicationFactory<TEntryPoint> instead.

Disable port randomization

By default, .NET Aspire uses random ports to allow multiple instances of your application to run concurrently without interference. It uses .NET Aspire's service discovery to ensure applications can locate each other's endpoints. To disable port randomization, pass "DcpPublisher:RandomizePorts=false" when constructing your testing builder, as shown in the following snippet:

var builder = await DistributedApplicationTestingBuilder
    .CreateAsync<Projects.MyAppHost>(
        [
            "DcpPublisher:RandomizePorts=false"
        ]);

Enable the dashboard

The testing builder disables the .NET Aspire dashboard by default. To enable it, you can set the DisableDashboard property to false, when creating your testing builder as shown in the following snippet:

var builder = await DistributedApplicationTestingBuilder
    .CreateAsync<Projects.MyAppHost>(
        args: [],
        configureBuilder: (appOptions, hostSettings) =>
        {
            appOptions.DisableDashboard = false;
        });

See also

• Write your first .NET Aspire test
• Managing the app host in .NET Aspire tests
• Access resources in .NET Aspire tests