faysilalshareef/integration-testing

Integration Testing — WebApplicationFactory & TestContainers

Core Principles

• WebApplicationFactory<Program> creates an in-process test server
• IClassFixture<T> shares expensive resources across tests
• TestContainers spin up real databases in Docker for realistic tests
• Respawn resets database state between tests (fast, preserves schema)
• Override services in ConfigureTestServices for test-specific behavior
• Integration tests verify the full pipeline: HTTP/gRPC -> Handler -> DB

Key Patterns

Custom WebApplicationFactory

namespace {Company}.{Domain}.Tests.Integration;

public sealed class TestWebAppFactory : WebApplicationFactory<Program>
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureTestServices(services =>
        {
            // Replace real DB with in-memory
            services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
            services.AddDbContext<ApplicationDbContext>(options =>
                options.UseInMemoryDatabase("TestDb_" + Guid.NewGuid()));

            // Replace external services with fakes
            services.RemoveAll<IServiceBusPublisher>();
            services.AddSingleton<IServiceBusPublisher, FakeServiceBusPublisher>();
        });

        builder.UseEnvironment("Testing");
    }
}

Test with Fixture

namespace {Company}.{Domain}.Tests.Integration;

public sealed class OrderIntegrationTests(TestWebAppFactory factory)
    : IClassFixture<TestWebAppFactory>
{
    [Fact]
    public async Task CreateOrder_ShouldPersistAndReturnId()
    {
        // Arrange
        using var scope = factory.Services.CreateScope();
        var mediator = scope.ServiceProvider.GetRequiredService<IMediator>();

        var command = new CreateOrderCommand("Test Customer", 100m, []);

        // Act
        var result = await mediator.Send(command);

        // Assert
        result.Id.Should().NotBeEmpty();

        var db = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
        var events = await db.Set<Event<OrderEventData>>()
            .Where(e => e.AggregateId == result.Id)
            .ToListAsync();
        events.Should().HaveCount(1);
    }
}

TestContainers for Real Database

namespace {Company}.{Domain}.Tests.Integration;

public sealed class SqlServerFixture : IAsyncLifetime
{
    private readonly MsSqlContainer _container = new MsSqlBuilder()
        .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
        .Build();

    public string ConnectionString => _container.GetConnectionString();

    public async Task InitializeAsync()
    {
        await _container.StartAsync();
    }

    public async Task DisposeAsync()
    {
        await _container.DisposeAsync();
    }
}

public sealed class RealDbWebAppFactory(SqlServerFixture sqlFixture)
    : WebApplicationFactory<Program>, IClassFixture<SqlServerFixture>
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureTestServices(services =>
        {
            services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
            services.AddDbContext<ApplicationDbContext>(options =>
                options.UseSqlServer(sqlFixture.ConnectionString));
        });
    }
}

Database Reset with Respawn

public sealed class DatabaseResetFixture : IAsyncLifetime
{
    private Respawner _respawner = null!;
    private string _connectionString = null!;

    public async Task InitializeAsync()
    {
        _respawner = await Respawner.CreateAsync(_connectionString, new RespawnerOptions
        {
            TablesToIgnore = ["__EFMigrationsHistory"],
            WithReseed = true
        });
    }

    public async Task ResetAsync()
    {
        await _respawner.ResetAsync(_connectionString);
    }

    public Task DisposeAsync() => Task.CompletedTask;
}

gRPC Integration Test

[Fact]
public async Task CreateOrder_ViaGrpc_ShouldSucceed()
{
    // Arrange
    using var channel = GrpcChannel.ForAddress(
        factory.Server.BaseAddress!,
        new GrpcChannelOptions { HttpHandler = factory.Server.CreateHandler() });

    var client = new OrderCommands.OrderCommandsClient(channel);

    // Act
    var response = await client.CreateOrderAsync(new CreateOrderRequest
    {
        CustomerName = "Test",
        Total = 100.0
    });

    // Assert
    response.OrderId.Should().NotBeNullOrEmpty();
    response.Sequence.Should().Be(1);
}

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Shared mutable database state | Use Respawn or unique DB per test | | Real external services in tests | Replace with fakes via ConfigureTestServices | | Testing only happy paths | Include error cases and edge cases | | Slow test startup | Use IClassFixture for shared resources |

Detect Existing Patterns

# Find WebApplicationFactory
grep -r "WebApplicationFactory" --include="*.cs" tests/

# Find TestContainers
grep -r "TestcontainersBuilder\|MsSqlContainer" --include="*.cs" tests/

# Find IClassFixture
grep -r "IClassFixture" --include="*.cs" tests/

# Find Respawn
grep -r "Respawner\|Respawn" --include="*.cs" tests/

Adding to Existing Project

1. Use existing TestWebAppFactory — extend rather than creating new
2. Follow fixture sharing patterns with IClassFixture<T>
3. Match database strategy — in-memory vs TestContainers
4. Add test helpers for common operations (create, query, assert)
5. Run integration tests separately from unit tests (test categories)