aspire-integration-testing

Aaronontheweb/dotnet-skillsDeveloper ToolsReview advisedSnapshot b7d2271b775e

Installs: 0

Summary

Write integration tests using .NET Aspire's testing facilities with xUnit. Covers test fixtures, distributed application setup, endpoint discovery, and patterns for testing ASP.NET Core apps with real dependencies.

SKILL.md

Integration Testing with .NET Aspire + xUnit

When to Use This Skill

Use this skill when:

Writing integration tests for .NET Aspire applications
Testing ASP.NET Core apps with real database connections
Verifying service-to-service communication in distributed applications
Testing with actual infrastructure (SQL Server, Redis, message queues) in containers
Combining Playwright UI tests with Aspire-orchestrated services
Testing microservices with proper service discovery and networking

Reference Files

advanced-patterns.md: Endpoint discovery, database testing, Playwright, conditional config, Respawn, service communication, message queues
ci-and-tooling.md: CI/CD integration, custom resource waiters, Aspire CLI with MCP

Core Principles

Real Dependencies - Use actual infrastructure (databases, caches) via Aspire, not mocks
Dynamic Port Binding - Let Aspire assign ports dynamically (127.0.0.1:0) to avoid conflicts
Fixture Lifecycle - Use IAsyncLifetime for proper test fixture setup and teardown
Endpoint Discovery - Never hard-code URLs; discover endpoints from Aspire at runtime
Parallel Isolation - Use xUnit collections to control test parallelization
Health Checks - Always wait for services to be healthy before running tests

High-Level Testing Architecture

┌─────────────────┐                    ┌──────────────────────┐
│ xUnit test file │──uses────────────►│  AspireFixture       │
└─────────────────┘                    │  (IAsyncLifetime)    │
                                       └──────────────────────┘
                                               │
                                               │ starts
                                               ▼
                                    ┌───────────────────────────┐
                                    │  DistributedApplication   │
                                    │  (from AppHost)           │
                                    └───────────────────────────┘
                                               │ exposes
                                               ▼
                                  ┌──────────────────────────────┐
                                  │   Dynamic HTTP Endpoints     │
                                  └──────────────────────────────┘
                                               │ consumed by
                                               ▼
                                   ┌─────────────────────────┐
                                   │  HttpClient / Playwright│
                                   └─────────────────────────┘

<ItemGroup>
  <PackageReference Include="Aspire.Hosting.Testing" Version="$(AspireVersion)" />
  <PackageReference Include="xunit" Version="*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="*" />
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />
</ItemGroup>

// TestEnvironmentInitializer.cs
using System.Runtime.CompilerServices;

namespace YourApp.Tests;

internal static class TestEnvironmentInitializer
{
    [ModuleInitializer]
    internal static void Initialize()
    {
        // Disable config file watching in test hosts
        // Prevents file descriptor exhaustion (inotify watch limit) on Linux
        Environment.SetEnvironmentVariable("DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE", "false");
    }
}

using Aspire.Hosting;
using Aspire.Hosting.Testing;

public sealed class AspireAppFixture : IAsyncLifetime
{
    private DistributedApplication? _app;

    public DistributedApplication App => _app
        ?? throw new InvalidOperationException("App not initialized");

    public async Task InitializeAsync()
    {
        var builder = await DistributedApplicationTestingBuilder
            .CreateAsync<Projects.YourApp_AppHost>([
                "YourApp:UseVolumes=false",
                "YourApp:Environment=IntegrationTest",
                "YourApp:Replicas=1"
            ]);

        _app = await builder.BuildAsync();

        using var startupCts = new CancellationTokenSource(TimeSpan.FromMinutes(10));
        await _app.StartAsync(startupCts.Token);

        using var healthCts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
        await _app.ResourceNotifications.WaitForResourceHealthyAsync("api", healthCts.Token);
    }

    public Uri GetEndpoint(string resourceName, string scheme = "https")
    {
        return _app?.GetEndpoint(resourceName, scheme)
            ?? throw new InvalidOperationException($"Endpoint for '{resourceName}' not found");
    }

    public async Task DisposeAsync()
    {
        if (_app is not null)
        {
            await _app.DisposeAsync();
        }
    }
}

[CollectionDefinition("Aspire collection")]
public class AspireCollection : ICollectionFixture<AspireAppFixture> { }

[Collection("Aspire collection")]
public class IntegrationTests
{
    private readonly AspireAppFixture _fixture;

    public IntegrationTests(AspireAppFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public async Task Application_ShouldStart()
    {
        var httpClient = _fixture.App.CreateHttpClient("yourapp");
        var response = await httpClient.GetAsync("/");
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
    }
}

Pattern	Use Case
Basic Fixture	Simple HTTP endpoint testing
Endpoint Discovery	Avoid hard-coded URLs
Database Testing	Verify data access layer
Playwright Integration	Full UI testing with real backend
Configuration Override	Test-specific settings
Health Checks	Ensure services are ready
Service Communication	Test distributed system interactions
Message Queue Testing	Verify async messaging

Problem	Solution
Tests timeout immediately	Call `await _app.StartAsync()` and wait for services to be healthy
Port conflicts between tests	Use xUnit `CollectionDefinition` to share fixtures
Flaky tests due to timing	Implement proper health check polling instead of `Task.Delay()`
Can't connect to SQL Server	Retrieve connection string dynamically via `GetConnectionStringAsync()`
Parallel tests interfere	Use `[Collection]` attribute to run related tests sequentially
Aspire dashboard conflicts	Only one dashboard can run at a time; tests reuse the same instance

aspire-integration-testing

Summary

SKILL.md

Integration Testing with .NET Aspire + xUnit

When to Use This Skill

Reference Files

Core Principles

High-Level Testing Architecture

Required NuGet Packages

CRITICAL: File Watcher Fix for Integration Tests

Pattern 1: Basic Aspire Test Fixture (Modern API)

Pattern 2: Using the Fixture in Tests

Common Patterns Summary

Tricky / Non-Obvious Tips

Best Practices

Debugging Tips

Related skills