Testing .NET Aspire projects

In this article, you'll learn how to create a test project, write, and run tests for your .NET Aspire projects. The tests in this article are not unit tests, but rather functional or integration tests. .NET Aspire include an xUnit testing project template that you can use to test your .NET Aspire projects. The testing project template is based on the xUnit testing framework and includes a sample test that you can use as a starting point for your tests.

Create a test project

The easiest way to create a .NET Aspire test project is to use the testing project template. If you're starting a new .NET Aspire project and want to include test projects, the Visual Studio tooling supports that option. If you're adding a test project to an existing .NET Aspire project, you can use the dotnet new command to create a test project:

dotnet new aspire-xunit

Explore the test project

The following example test project was created as part of the .NET Aspire Starter Application template. If you're unfamiliar with it, see Quickstart: Build your first .NET Aspire project. The .NET Aspire test project takes a project reference dependency on the target app host. Consider the template project:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.Testing" Version="8.0.1" />
    <PackageReference Include="coverlet.collector" Version="6.0.2" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
    <PackageReference Include="xunit" Version="2.8.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireApp1.AppHost\AspireApp1.AppHost.csproj" />
  </ItemGroup>

  <ItemGroup>
    <Using Include="Aspire.Hosting.Testing" />
    <Using Include="Xunit" />
  </ItemGroup>

</Project>

The preceding project file is fairly standard. There's a PackageReference to the Aspire.Hosting.Testing NuGet package, which includes the required types to write tests for .NET Aspire projects.

The template test project includes a WebTests class with a single test fact. The test fact verifies the following scenario:

• The app host is successfully created and started.
• An HTTP request can be made to the webfrontend resource and returns a successful response.

Consider the following test class:

using System.Net;

namespace AspireApp1.Tests;

public class WebTests
{
    [Fact]
    public async Task GetWebResourceRootReturnsOkStatusCode()
    {
        // Arrange
        var appHost =
            await DistributedApplicationTestingBuilder.CreateAsync<Projects.AspireApp1_AppHost>();

        await using var app = await appHost.BuildAsync();
        await app.StartAsync();

        // Act
        var httpClient = app.CreateHttpClient("webfrontend");
        var response = await httpClient.GetAsync("/");

        // Assert
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
    }
}

The preceding code:

• Relies on the DistributedApplicationTestingBuilder to asynchronously create the app host.
  • The appHost is an instance of IDistributedApplicationTestingBuilder that represents the app host.
• The appHost has its BuildAsync method invoked, which returns the DistributedApplication instance as the app.
• The app is started asynchronously.
• An HttpClient is created for the webfrontend resource.
• A simple GET request is made to the root of the webfrontend resource.
• The test asserts that the response status code is OK.

Summary

By using the .NET Aspire testing project template, you can easily create test projects for your .NET Aspire projects. The template project includes a sample test that you can use as a starting point for your tests. The DistributedApplicationTestingBuilder follows a familiar pattern to the WebApplicationFactory in ASP.NET Core. It allows you to create a test host for your distributed application and run tests against it.