A while ago, I published an article about ASP.NET Core Integration Testing Best Practices. WebApplicationFactory, TestContainers, and Respawn simplifies integration testing in .NET Core applications.

But .NET Aspire simplifies the process further for distributed applications.

.NET Aspire replaces both WebApplicationFactory and TestContainers with a single tool: DistributedApplicationTestingBuilder. You no longer need to set up Docker containers manually or override environment variables. Aspire handles service discovery, container orchestration, and connection strings for you.

In this post, I will share the best practices I discovered while writing integration tests for a distributed Aspire application with multiple APIs, PostgreSQL, and Redis.

In this post, we will explore:

• The System We Will Be Testing
• Best Practice 1: Use DistributedApplicationTestingBuilder Instead of WebApplicationFactory
• Best Practice 2: Share the App Instance Across Tests with ICollectionFixture
• Best Practice 3: Wait for Resources to Be Healthy
• Best Practice 4: Wait for Services to Start before Running Tests
• Best Practice 5: Cleanup Database Between Tests
• Best Practice 6: Test your API Contracts
• Best Practice 7: Test Error Responses and Cross-Service Communication

Let's dive in.

I have built a distributed system with two APIs orchestrated by .NET Aspire:

• Products API: manages products, supports CRUD operations and purchasing. Uses PostgreSQL and Redis for caching. Calls the Stocks API to check and update stock levels during purchases.
• Stocks API: manages stock inventory for products. Uses PostgreSQL.

Both APIs share the same PostgreSQL server but use separate database schemas.

Here is the Aspire AppHost that defines the architecture:

csharp
1var builder = DistributedApplication.CreateBuilder(args);
2
3var postgres = builder.AddPostgres("postgres")
4    .WithDataVolume(isReadOnly: false);
5
6var redis = builder.AddRedis("cache");
7
8var stocksApi = builder.AddProject<Projects.Stocks_Api>("stocks-api")
9    .WithReference(postgres)
10    .WaitFor(postgres)
11    .WithExternalHttpEndpoints();
12
13builder.AddProject<Projects.Products_Api>("products-api")
14    .WithReference(stocksApi)
15    .WaitFor(stocksApi)
16    .WithReference(postgres)
17    .WaitFor(postgres)
18    .WithReference(redis)
19    .WaitFor(redis)
20    .WithExternalHttpEndpoints();
21
22builder.Build().Run();

The Products API depends on the Stocks API for inter-service communication. When a user purchases a product, the Products API calls the Stocks API via HTTP to verify stock availability and update the count.

Both APIs use EF Core with PostgreSQL and run database migrations on startup.

Now let's explore how to write integration tests for this system.

In my previous article, I used WebApplicationFactory together with TestContainers to spin up Docker containers for PostgreSQL and RabbitMQ.

With .NET Aspire, you don't need either of these. Aspire provides DistributedApplicationTestingBuilder, which replaces both tools with a single, unified approach.

With the traditional approach, your test project references the API project directly:

xml
1<ProjectReference Include="..\Products.Api\Products.Api.csproj" />

With Aspire, your test project references the Aspire AppHost project instead:

xml
1<ProjectReference Include="..\AspireNetConf.AppHost\AspireNetConf.AppHost.csproj" />

This means you test the entire distributed application, not just a single API in isolation.

To create a test project, you can use the ready Aspire Test Project template:

You can install the Aspire project templates by running the following command:

bash
1dotnet new install Aspire.ProjectTemplates

You will also need to install the Aspire CLI:

bash
1dotnet tool install --global aspire.cli

The testing project installs the Aspire.Hosting.Testing NuGet package.

This one package replaces multiple packages from the traditional approach:

• Microsoft.AspNetCore.Mvc.Testing (WebApplicationFactory)
• Testcontainers.PostgreSql (TestContainers for PostgreSQL)
• Testcontainers.RabbitMq (or other container packages)

To create the distributed application in your tests, use DistributedApplicationTestingBuilder:

csharp
1var appHost = await DistributedApplicationTestingBuilder
2    .CreateAsync<Projects.AspireTests_AppHost>();
3
4var app = await appHost.BuildAsync();
5await app.StartAsync();

This starts the entire Aspire application, including all containers and services.

To create HTTP clients for your APIs, use CreateHttpClient with the resource name from your AppHost:

csharp
1var productsClient = app.CreateHttpClient("products-api");
2var stocksClient = app.CreateHttpClient("stocks-api");

No need to configure base URLs or connection strings. Aspire handles service discovery automatically.

Starting a distributed application with Docker containers is expensive. It takes several seconds to pull images, start containers, and wait for services to become healthy.

You should not rebuild the distributed application for every test (like in the Aspire Test project template). Instead, build it once and share it across all test classes.

In xUnit, you can achieve this with ICollectionFixture and IAsyncLifetime.

First, create a fixture that manages the application lifecycle:

csharp
1public class DistributedAppFixture : IAsyncLifetime
2{
3    private static readonly TimeSpan StartupTimeout = TimeSpan.FromSeconds(120);
4
5    private DistributedApplication _app = null!;
6    private DbConnection _dbConnection = null!;
7
8    public HttpClient ProductsApiClient { get; private set; } = null!;
9    public HttpClient StocksApiClient { get; private set; } = null!;
10
11    public async Task InitializeAsync()
12    {
13        var appHost = await DistributedApplicationTestingBuilder
14            .CreateAsync<Projects.AspireTests_AppHost>();
15
16        appHost.Services.ConfigureHttpClientDefaults(clientBuilder =>
17        {
18            clientBuilder.AddStandardResilienceHandler();
19        });
20
21        _app = await appHost.BuildAsync();
22        await _app.StartAsync();
23
24        // Wait for all services to be healthy
25        await _app.ResourceNotifications
26            .WaitForResourceHealthyAsync("products-api")
27            .WaitAsync(StartupTimeout);
28
29        await _app.ResourceNotifications
30            .WaitForResourceHealthyAsync("stocks-api")
31            .WaitAsync(StartupTimeout);
32
33        // Create HTTP clients for both APIs
34        ProductsApiClient = _app.CreateHttpClient("products-api");
35        StocksApiClient = _app.CreateHttpClient("stocks-api");
36
37        await InitializeDatabaseConnectionAsync();
38    }
39
40    public async Task DisposeAsync()
41    {
42        ProductsApiClient.Dispose();
43        StocksApiClient.Dispose();
44        await _dbConnection.DisposeAsync();
45        await _app.DisposeAsync();
46    }
47
48    // ... database methods shown later
49}

I also added AddStandardResilienceHandler to handle transient HTTP errors during test execution.

Next, define a shared test collection:

csharp
1[CollectionDefinition("AspireTests")]
2public class SharedTestCollection : ICollectionFixture<DistributedAppFixture>;

Now every test class can share the same fixture instance:

csharp
1[Collection("AspireTests")]
2public class GetAllProductsTests(DistributedAppFixture fixture) : IAsyncLifetime
3{
4    public Task InitializeAsync() => Task.CompletedTask;
5
6    public async Task DisposeAsync() => await fixture.ResetDatabaseAsync();
7
8    [Fact]
9    public async Task GetAllProducts_ShouldReturnEmptyList_WhenNoProductsExist()
10    {
11        // Act
12        var response = await fixture.ProductsApiClient.GetAsync("/products");
13        var products = await response.Content.ReadFromJsonAsync<List<ProductResponse>>();
14
15        // Assert
16        response.StatusCode.Should().Be(HttpStatusCode.OK);
17        products.Should().BeEmpty();
18    }
19}

The [Collection("AspireTests")] attribute tells xUnit to share the DistributedAppFixture across all test classes that use this collection. The fixture is created once, and all test classes receive the same instance.

Each test class implements IAsyncLifetime and calls ResetDatabaseAsync() in DisposeAsync to ensure a clean database state after each test.

When testing with Aspire, your application starts Docker containers for PostgreSQL, Redis, and your API services. These containers need time to become ready.

Aspire provides a built-in mechanism for waiting: WaitForResourceHealthyAsync.

We need wait for services to become healthy in DistributedAppFixture.InitializeAsync before executing tests:

csharp
1await _app.ResourceNotifications
2    .WaitForResourceHealthyAsync("products-api")
3    .WaitAsync(StartupTimeout);
4
5await _app.ResourceNotifications
6    .WaitForResourceHealthyAsync("stocks-api")
7    .WaitAsync(StartupTimeout);

This method subscribes to resource health notifications from the Aspire orchestrator. It waits until the specified resource reports a healthy status.

I always wrap this call with .WaitAsync(StartupTimeout) to avoid hanging forever if something goes wrong. I use a 120-second timeout, which is more than enough for containers to start and APIs to become healthy.

For health checks to work, your APIs must have health-check endpoints configured. If you use the Aspire ServiceDefaults project, health checks are configured automatically.

By default, Aspire starts all resources in parallel. This means your API can start before PostgreSQL is ready to accept connections.

When this happens, EF Core migrations fail silently (when executed from code at startup), and the API crashes. The tricky part is that WaitForResourceHealthyAsync might still succeed briefly before all the initialization has completed.

The fix is to use .WaitFor() in your Aspire AppHost to enforce startup ordering:

csharp
1// Bad: APIs may start before PostgreSQL is ready
2var stocksApi = builder.AddProject<Projects.Stocks_Api>("stocks-api")
3    .WithReference(postgres)
4    .WithExternalHttpEndpoints();
5
6// Good: APIs wait for their dependencies
7var stocksApi = builder.AddProject<Projects.Stocks_Api>("stocks-api")
8    .WithReference(postgres)
9    .WaitFor(postgres)
10    .WithExternalHttpEndpoints();
11
12builder.AddProject<Projects.Products_Api>("products-api")
13    .WithReference(stocksApi)
14    .WaitFor(stocksApi)
15    .WithReference(postgres)
16    .WaitFor(postgres)
17    .WithReference(redis)
18    .WaitFor(redis)
19    .WithExternalHttpEndpoints();

Always add .WaitFor() for every resource dependency. Without it, your tests may fail.

Also, when it takes longer to spin up an external resource (a database Docker container), even our applications can crash during startup. So it's safer to run our services after all external dependencies are ready.

After each test, the database contains leftover data that can affect other tests. That's why you need to clean up the database after each test.

I recommend using the Respawn library for database cleanup.

As stated on the library's GitHub:

Respawn examines the SQL metadata intelligently to build a deterministic order of tables to delete based on foreign key relationships between tables. It navigates these relationships to build a DELETE script starting with the tables with no relationships and moving inwards until all tables are accounted for.

First, install the following NuGet package:

csharp
1dotnet add package Respawn

Next, update your DistributedAppFixture to use a Respawner:

csharp
1public class DistributedAppFixture : IAsyncLifetime
2{
3    private DistributedApplication _app = null!;
4    private DbConnection _dbConnection = null!;
5    private Respawner _respawner = null!;
6
7    // ...
8
9    public async Task InitializeAsync()
10    {
11        // ... app startup and health checks ...
12
13        await InitializeDatabaseConnectionAsync();
14    }
15
16    public async Task ResetDatabaseAsync()
17    {
18        await _respawner.ResetAsync(_dbConnection);
19    }
20
21    public async Task DisposeAsync()
22    {
23        await _dbConnection.DisposeAsync();
24        await _app.DisposeAsync();
25    }
26
27    private async Task InitializeDatabaseConnectionAsync()
28    {
29        var connectionString = await _app.GetConnectionStringAsync("postgres");
30
31        var csBuilder = new NpgsqlConnectionStringBuilder(connectionString);
32        if (string.IsNullOrEmpty(csBuilder.Database))
33        {
34            csBuilder.Database = "postgres";
35        }
36
37        _dbConnection = new NpgsqlConnection(csBuilder.ConnectionString);
38        await _dbConnection.OpenAsync();
39
40        await InitializeRespawnerAsync();
41    }
42
43    private async Task InitializeRespawnerAsync()
44    {
45        _respawner = await Respawner.CreateAsync(_dbConnection, new RespawnerOptions
46        {
47            SchemasToInclude = [ "products", "stocks" ],
48            DbAdapter = DbAdapter.Postgres
49        });
50    }
51}

Notice how _app.GetConnectionStringAsync("postgres") retrieves the connection string directly from Aspire — no environment variables, no hardcoded strings.

The Respawner is initialized with RespawnerOptions specifying the schemas to include (products and stocks) and the database adapter (DbAdapter.Postgres). Respawn will intelligently determine the correct order to delete rows based on foreign key relationships within those schemas.

InitializeDatabaseConnectionAsync is called at the end of InitializeAsync, after the application has fully started and all resources are healthy. This is important because the database schemas are created by EF Core migrations that run on startup — Respawn needs them to already exist when it scans the metadata.

Finally, call ResetDatabaseAsync in each test class's DisposeAsync to ensure every test ends with a clean database:

csharp
1[Collection("AspireTests")]
2public class CreateProductTests(DistributedAppFixture fixture) : IAsyncLifetime
3{
4    public Task InitializeAsync() => Task.CompletedTask;
5
6    public async Task DisposeAsync() => await fixture.ResetDatabaseAsync();
7
8    // ... test methods
9}

This best practice comes from my personal experience.

Instead of referencing request and response models from the API project, duplicate them in the test project:

csharp
1namespace AspireTests.Models;
2
3public record ProductRequest(string Name, decimal Price);
4
5public record ProductResponse(int Id, string Name, decimal Price);
6
7public record PurchaseProductRequest(int Quantity);
8
9public record PurchaseProductResponse(int ProductId, int Quantity, decimal TotalPrice);

csharp
1namespace AspireTests.Models;
2
3public record StockResponse(int Id, int ProductId, int Count);
4
5public record UpdateStockCountRequest(int ProductId, int CountChange);

Why duplicate them?

If someone renames a property in the API project (for example, renames Name to ProductName), tests will fail. You catch the breaking API contract change before it reaches production.

Here is the test for the PurchaseProduct endpoint that uses the models from the Aspire Testing project:

csharp
1[Fact]
2public async Task PurchaseProduct_ShouldReturnOk_WhenProductExistsAndHasStock()
3{
4    // Arrange
5    var productRequest = new ProductRequest("Laptop", 999.99m);
6    var createResponse = await fixture.ProductsApiClient.PostAsJsonAsync("/products", productRequest);
7    var createdProduct = await createResponse.Content.ReadFromJsonAsync<ProductResponse>();
8
9    var stockRequest = new UpdateStockCountRequest(createdProduct!.Id, 10);
10    await fixture.StocksApiClient.PutAsJsonAsync("/stocks/update-count", stockRequest);
11
12    var purchaseRequest = new PurchaseProductRequest(2);
13
14    // Act
15    var response = await fixture.ProductsApiClient.PostAsJsonAsync(
16        $"/products/{createdProduct.Id}/purchase", purchaseRequest);
17    var purchaseResponse = await response.Content.ReadFromJsonAsync<PurchaseProductResponse>();
18
19    // Assert
20    response.StatusCode.Should().Be(HttpStatusCode.OK);
21    purchaseResponse.Should().BeEquivalentTo(new PurchaseProductResponse(
22        createdProduct.Id, 2, 999.99m * 2));
23}

If you reference the shared models, the rename compiles successfully everywhere (even in tests), and the broken API contract goes undetected until a consumer reports the issue.

Many developers only write happy-path tests. But testing error responses is just as important.

For every endpoint, test all HTTP status codes that it can return. This includes 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, and 409 Conflict.

Here is an example of a simple CRUD test:

csharp
1[Fact]
2public async Task CreateProduct_ShouldReturnCreated_WhenRequestIsValid()
3{
4    // Arrange
5    var request = new ProductRequest("Monitor", 349.99m);
6
7    // Act
8    var response = await fixture.ProductsApiClient.PostAsJsonAsync("/products", request);
9
10    // Assert
11    response.StatusCode.Should().Be(HttpStatusCode.Created);
12    response.Headers.Location.Should().NotBeNull();
13}

Now, the most interesting part of Aspire testing: cross-service integration tests.

With Aspire, you can test how multiple services work together in a single test. This is something that WebApplicationFactory cannot do out of the box.

Here are the tests for the PurchaseProduct endpoint, which calls the Stocks API internally:

csharp
1[Collection("AspireTests")]
2public class PurchaseProductTests(DistributedAppFixture fixture) : IAsyncLifetime
3{
4    public async Task InitializeAsync() => await fixture.ResetDatabaseAsync();
5
6    public Task DisposeAsync() => Task.CompletedTask;
7
8    [Fact]
9    public async Task PurchaseProduct_ShouldReturnOk_WhenProductExistsAndHasStock()
10    {
11        // Arrange: create a product via the Products API
12        var productRequest = new ProductRequest("Laptop", 999.99m);
13        var createResponse = await fixture.ProductsApiClient
14            .PostAsJsonAsync("/products", productRequest);
15        var createdProduct = await createResponse.Content
16            .ReadFromJsonAsync<ProductResponse>();
17
18        // Arrange: add stock via Stocks API
19        var stockRequest = new UpdateStockCountRequest(createdProduct!.Id, 10);
20        await fixture.StocksApiClient
21            .PutAsJsonAsync("/stocks/update-count", stockRequest);
22
23        var purchaseRequest = new PurchaseProductRequest(2);
24
25        // Act: purchase via Products API (which internally calls Stocks API)
26        var response = await fixture.ProductsApiClient.PostAsJsonAsync(
27            $"/products/{createdProduct.Id}/purchase", purchaseRequest);
28        var purchaseResponse = await response.Content
29            .ReadFromJsonAsync<PurchaseProductResponse>();
30
31        // Assert
32        response.StatusCode.Should().Be(HttpStatusCode.OK);
33        purchaseResponse.Should().BeEquivalentTo(
34            new PurchaseProductResponse(createdProduct.Id, 2, 999.99m * 2));
35    }
36
37    [Fact]
38    public async Task PurchaseProduct_ShouldReturnNotFound_WhenProductDoesNotExist()
39    {
40        // Arrange
41        var purchaseRequest = new PurchaseProductRequest(1);
42
43        // Act
44        var response = await fixture.ProductsApiClient.PostAsJsonAsync(
45            "/products/999999/purchase", purchaseRequest);
46
47        // Assert
48        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
49    }
50
51    [Fact]
52    public async Task PurchaseProduct_ShouldReturnConflict_WhenNotEnoughStock()
53    {
54        // Arrange
55        var productRequest = new ProductRequest("Tablet", 449.99m);
56        var createResponse = await fixture.ProductsApiClient
57            .PostAsJsonAsync("/products", productRequest);
58        var createdProduct = await createResponse.Content
59            .ReadFromJsonAsync<ProductResponse>();
60
61        var stockRequest = new UpdateStockCountRequest(createdProduct!.Id, 3);
62        await fixture.StocksApiClient
63            .PutAsJsonAsync("/stocks/update-count", stockRequest);
64
65        var purchaseRequest = new PurchaseProductRequest(5);
66
67        // Act
68        var response = await fixture.ProductsApiClient.PostAsJsonAsync(
69            $"/products/{createdProduct.Id}/purchase", purchaseRequest);
70
71        // Assert
72        response.StatusCode.Should().Be(HttpStatusCode.Conflict);
73    }
74}

In the Arrange phase, I use two different API clients:

• fixture.ProductsApiClient to create a product
• fixture.StocksApiClient to add stock for that product

In the Act phase, the Products API internally calls the Stocks API to check stock availability and update the count.

This test validates the entire chain: Products API -> Stocks API -> PostgreSQL and back. With WebApplicationFactory, you would need to mock the Stocks API or set up a separate test server. With Aspire, it just works.

Let's recap the key takeaways:

• Use DistributedApplicationTestingBuilder instead of WebApplicationFactory and TestContainers.
• Share the app instance across all tests with ICollectionFixture. Starting Docker containers is expensive - do it once.
• Wait for resources using WaitForResourceHealthyAsync with a timeout.
• Add .WaitFor() in your AppHost to enforce startup ordering. Without it, APIs crash because they start before their dependencies are ready.
• Use Respawn for database cleanup.
• Duplicate models in the test project to catch breaking API contract changes.
• Test cross-service communication end-to-end. This is the biggest advantage of Aspire testing over WebApplicationFactory.

Hope you find this newsletter useful. See you next time.