{"id":53826,"date":"2024-09-25T10:05:00","date_gmt":"2024-09-25T17:05:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=53826"},"modified":"2025-11-17T14:42:21","modified_gmt":"2025-11-17T22:42:21","slug":"getting-started-with-testing-and-dotnet-aspire","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/getting-started-with-testing-and-dotnet-aspire\/","title":{"rendered":"Getting started with testing and Aspire"},"content":{"rendered":"

Automated testing is an important part of software development, helping ensure that bugs are caught early and regression issues are prevented. In this blog post, we will explore how to get started with testing in Aspire, allowing us to test scenarios across our distributed applications.<\/p>\n

Testing Distributed Applications<\/h2>\n

Distributed applications are inherently complex, you need to ensure components such as databases, caches, etc. are available and in the correct state. Then your application may have multiple services that need to be tested together. Aspire is a great tool to help us define the environment for our application, connecting together all the services and resources, making it easy to launch our environment.<\/p>\n

And this is equally true when it comes to end-to-end, or integration, testing of an application. We need to ensure that the database is in an expected state for a test, avoid having other tests interfere with our test, and ensure that the application is running in the correct configuration. This is something that Aspire can help us with.<\/p>\n

Thankfully, we have the Aspire Aspire.Hosting.Testing<\/code> NuGet package<\/a> which can help us with this. Let’s take a look at how we can use this package to write tests.<\/p>\n

Getting Started<\/h2>\n

To get started, we’re going to create a new Aspire Starter App project. This will create a new Aspire application with the AppHost, Service Defaults, an API backend and a Blazor web frontend.<\/p>\n

Ensure you have the Aspire workload installed:<\/p>\n

dotnet workload update\ndotnet workload install aspire<\/code><\/pre>\n
Then create a new project using the aspire-starter<\/code> template:<\/p>\n
dotnet new aspire-starter --name AspireWithTesting<\/code><\/pre>\n
Next, we need to add a test project, and we can choose from one of three testing frameworks, MSTest, xUnit or Nunit. For this example, we’ll use MSTest. This can be created using the aspire-mstest<\/code> template:<\/p>\n
dotnet new aspire-mstest --name AspireWithTesting.Tests\ndotnet sln add AspireWithTesting.Tests<\/code><\/pre>\n
\n
Note: You can have the test project included when creating with the aspire-starter<\/code> template by adding the --test-framework MSTest<\/code> (or other framework) flag.<\/p>\n<\/blockquote>\n
The template already references the Aspire.Hosting.Testing<\/code> NuGet package, as well as the chosen testing framework (MSTest in this case), so the last thing we need to do is add a reference to the AppHost<\/strong> project in our Test project:<\/p>\n
dotnet add AspireWithTesting.Tests reference AspireWithTesting.AppHost<\/code><\/pre>\n
Writing Tests<\/h2>\n
We’ll find there is already a stub test file, IntegrationTest1.cs<\/code> in our test project that describes the steps above and provides an example of tests that can be written, but let’s start from scratch so we can understand what’s going on. Create a new file called FrontEndTests.cs<\/code> and add the following code:<\/p>\n
namespace AspireWithTesting.Tests;\n\n[TestClass]\npublic class FrontEndTests\n{\n    [TestMethod]\n    public async Task CanGetIndexPage()\n    {\n        var appHost =\n            await DistributedApplicationTestingBuilder\n                    .CreateAsync<Projects.AspireWithTesting_AppHost>();\n        appHost.Services.ConfigureHttpClientDefaults(clientBuilder =>\n        {\n            clientBuilder.AddStandardResilienceHandler();\n        });\n\n        await using var app = await appHost.BuildAsync();\n        await app.StartAsync();\n\n        var resourceNotificationService =\n            app.Services.GetRequiredService<ResourceNotificationService>();\n        await resourceNotificationService\n            .WaitForResourceAsync(\"webfrontend\", KnownResourceStates.Running)\n            .WaitAsync(TimeSpan.FromSeconds(30));\n\n        var httpClient = app.CreateHttpClient(\"webfrontend\");\n        var response = await httpClient.GetAsync(\"\/\");\n\n        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);\n    }\n}<\/code><\/pre>\n
Awesome, the test is written, let’s run it:<\/p>\n
dotnet test<\/code><\/pre>\n
And if everything goes to plan, we should see output such as:<\/p>\n
Test summary: total: 1, failed: 0, succeeded: 1, skipped: 0, duration: 0.9s<\/code><\/pre>\n
Understanding the Test<\/h2>\n
Let’s break down what’s happening in the test:<\/p>\n
var appHost =\n    await DistributedApplicationTestingBuilder\n            .CreateAsync<Projects.AspireWithTesting_AppHost>();\nappHost.Services.ConfigureHttpClientDefaults(clientBuilder =>\n{\n    clientBuilder.AddStandardResilienceHandler();\n});\n\nawait using var app = await appHost.BuildAsync();\nawait app.StartAsync();<\/code><\/pre>\n
This first section of the test is using the AppHost<\/strong> project that defines all our resources, services, and their relationships, and then starts it up, as if we did a dotnet run<\/code> against the project, but in a test environment which we can control some additional aspects. For example, we’re injecting the StandardResilienceHandler<\/code> into the HttpClient<\/code> that the tests are going to use to interact with the services in the AppHost. Once the testing AppHost is configured, we can build the application, ready to be started.<\/p>\n
var resourceNotificationService =\n    app.Services.GetRequiredService<ResourceNotificationService>();\nawait resourceNotificationService\n    .WaitForResourceAsync(\"webfrontend\", KnownResourceStates.Running)\n    .WaitAsync(TimeSpan.FromSeconds(30));<\/code><\/pre>\n
Because the AppHost will be starting several different resources and services, we need to ensure that they are available to us before we try to run tests against them. After all, if the web application hasn’t started and we try to resolve it, we’re going to get an error. The ResourceNotificationService<\/code> is a service that allows us to wait for a resource to be in a particular state, in this case, we’re waiting for the webfrontend<\/code> (the name we set in the AppHost) to be in the Running<\/code> state, and we’re giving it 30 seconds to do so. This pattern would need to be repeated for any other services that we’re going to interact with, whether directly or indirectly.<\/p>\n
var httpClient = app.CreateHttpClient(\"webfrontend\");\nvar response = await httpClient.GetAsync(\"\/\");\n\nAssert.AreEqual(HttpStatusCode.OK, response.StatusCode);<\/code><\/pre>\n
Finally, we can request an instance of HttpClient<\/code> from the app that has been started and provide the name of the service we want to interact with. This uses the same service discovery as the rest of the application, so we don’t need to worry about the URL or port that the service is running on. We can then make a request to the service, in this case, the root of the web frontend, and check that we get a 200 OK<\/code> response, confirming that the service is running and responding as expected.<\/p>\n
Testing the API<\/h2>\n
Testing the API service is a very similar approach to the frontend service, but since it’s returning data, we can take it a step further and assert against the data that is returned:<\/p>\n
using System.Net.Http.Json;\n\nnamespace AspireWithTesting.Tests;\n\n[TestClass]\npublic class ApiTests\n{\n    [TestMethod]\n    public async Task CanGetWeatherForecast()\n    {\n        var appHost =\n            await DistributedApplicationTestingBuilder.CreateAsync<Projects.AspireWithTesting_AppHost>();\n        appHost.Services.ConfigureHttpClientDefaults(clientBuilder =>\n        {\n            clientBuilder.AddStandardResilienceHandler();\n        });\n\n        await using var app = await appHost.BuildAsync();\n        await app.StartAsync();\n\n        var resourceNotificationService =\n            app.Services.GetRequiredService<ResourceNotificationService>();\n        await resourceNotificationService\n                .WaitForResourceAsync(\"apiservice\", KnownResourceStates.Running)\n                .WaitAsync(TimeSpan.FromSeconds(30));\n\n        var httpClient = app.CreateHttpClient(\"apiservice\");\n        var response = await httpClient.GetAsync(\"\/weatherforecast\");\n\n        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);\n\n        var forecasts = await response.Content.ReadFromJsonAsync<IEnumerable<WeatherForecast>>();\n        Assert.IsNotNull(forecasts);\n        Assert.AreEqual(5, forecasts.Count());\n    }\n\n    record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary);\n}<\/code><\/pre>\n
<\/i>Note<\/strong><\/p>Since the WeatherForecast<\/code> record<\/code> is private in the API project, we need to define it in the test project to be able to deserialize the JSON response.<\/div><\/p>\n
Once we’ve asserts that the API endpoint returned a 200 OK<\/code> response, we can then deserialize the JSON response into a collection of WeatherForecast<\/code> objects and assert against the data. In this case, the data we have for our API is randomly generated so we’re only asserting on the number of records returned, but if we had a database that the data came from, the test could assert against the expected data.<\/p>\n
Video<\/h2>\n