Skip to content

C# Interview Guide: Integration Testing with WebApplicationFactory and Testcontainers

Q25 — Integration Testing with WebApplicationFactory and Testcontainers Level: Senior | Topic: Testing Why Integration Tests? Unit tests verify logic in isolation. Integration tests verify the full ASP.NET Core pipeline ...

Ekanatha Reddy Urivakili12 min2,103 words

Q25 — Integration Testing with WebApplicationFactory and Testcontainers

Level: Senior | Topic: Testing

Why Integration Tests?

Unit tests excel at verifying isolated logic—methods, classes, and small components—but they miss how these components behave together.

Integration tests cover the full application pipeline, including:

  • Routing: Ensuring HTTP requests reach the correct controller actions.
  • Middleware: Verifying behavior like authentication, authorization, error handling, and logging.
  • Model Binding and Validation: Checking if request payloads deserialize and validate correctly.
  • Database Access: Confirming Entity Framework Core (EF Core) queries execute as expected against a database.

Integration testing ASP.NET Core apps becomes challenging when dealing with stateful dependencies like databases. Running tests against an in-memory or mocked database differs significantly from production’s SQL Server behavior.

This is where:

  • WebApplicationFactory<TEntryPoint> shines: it spins up the whole ASP.NET Core application in memory without network calls.
  • Testcontainers provides real, throwaway Docker containers for databases and other dependencies, reproducing production-like runtime conditions.

Combining these tools lets you perform end-to-end HTTP testing against a realistic environment, ensuring tests detect issues other layers miss.


Architecture Overview

High-Level Design

flowchart TD
    A[Start Test Run] --> B[SqlServerFixture Start Container]
    B --> C[TestWebAppFactory ConfigureWebHost]
    C --> D[Override DbContext Connection String]
    D --> E[Apply Migrations and Seed Data]
    E --> F[Create HttpClient]
    F --> G[Test Executes HTTP Requests]
    G --> H[App handles via Full ASP.NET Core Pipeline]
    H --> I[EF Core Queries to Test SQL Server Container]
    I --> J[Test Validates HTTP Response]
    J --> K[End Test]
    K --> L[SqlServerFixture Dispose Container]

Figure 1: Integration test lifecycle using WebApplicationFactory and Testcontainers

Key Components Explained

ComponentResponsibilityBenefits
SqlServerFixtureManages lifecycle of ephemeral SQL Server container per test classRealistic DB environment, starts/stops once per class for speed
TestWebAppFactoryHosts the full ASP.NET Core app with overridden DbContext to point to containerExercises full middleware, routing, validation, DI
Integration TestSends HTTP requests through in-memory TestServer client, verifies responsesTests full app pipeline, verifies end-to-end workflows

Sequence Diagram for Integration Test Execution

sequenceDiagram
    participant TestClass as Integration Test Class
    participant Factory as TestWebAppFactory
    participant Server as ASP.NET Core App
    participant Db as SQL Server Container

    TestClass->>Factory: CreateClient()
    Factory->>Server: Host ASP.NET Core app with test services
    TestClass->>Server: HTTP GET /api/orders
    Server->>Db: EF Core SQL query
    Db-->>Server: Query result
    Server-->>TestClass: HTTP 200 + Orders JSON

Figure 2: Sequence of HTTP integration test against SQL Server container


Detailed Implementation

1. Container Fixture — Starting SQL Server Once per Test Class

Use IAsyncLifetime to asynchronously start and stop the container:

using System.Threading.Tasks;
using Testcontainers.SqlEdge;
using Xunit;

public class SqlServerFixture : IAsyncLifetime
{
    private readonly SqlEdgeContainer _container = new SqlEdgeBuilder()
        .WithImage("mcr.microsoft.com/azure-sql-edge:latest")
        .Build();

    public string ConnectionString => _container.GetConnectionString();

    public async Task InitializeAsync()
        => await _container.StartAsync();

    public async Task DisposeAsync()
        => await _container.DisposeAsync().AsTask();
}

2. Custom WebApplicationFactory — Overriding EF Core DbContext

Override ConfigureWebHost to replace the production DbContext registration with one pointing to the test SQL container, then seed data:

using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;

public class TestWebAppFactory : WebApplicationFactory<Program>
{
    private readonly string _connectionString;

    public TestWebAppFactory(string connectionString)
        => _connectionString = connectionString;

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureServices(services =>
        {
            services.RemoveAll<DbContextOptions<AppDbContext>>();
            services.RemoveAll<AppDbContext>();

            services.AddDbContext<AppDbContext>(opts =>
                opts.UseSqlServer(_connectionString));

            // Build service provider to apply migrations and seed DB
            var sp = services.BuildServiceProvider();

            using var scope = sp.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

            db.Database.EnsureCreated();

            // Seed deterministic test data here
            db.Orders.Add(new Order { Id = Guid.NewGuid(), CustomerId = "seed-cust", Total = 100 });
            db.SaveChanges();
        });
    }
}

3. Integration Test Class — Run Full HTTP Pipeline Tests

Using IClassFixture<SqlServerFixture>, start the container once per class, then create HTTP clients to send real HTTP requests:

using System;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;
using FluentAssertions;
using Xunit;

[Collection("SqlServer")]
public class OrdersApiTests : IClassFixture<SqlServerFixture>
{
    private readonly HttpClient _client;

    public OrdersApiTests(SqlServerFixture fixture)
        => _client = new TestWebAppFactory(fixture.ConnectionString).CreateClient();

    [Fact]
    public async Task GetOrders_ReturnsOk_WithSeededData()
    {
        var response = await _client.GetAsync("/api/orders");

        response.StatusCode.Should().Be(HttpStatusCode.OK);

        var orders = await response.Content.ReadFromJsonAsync<List<OrderDto>>();
        orders.Should().NotBeNullOrEmpty();
        orders.Should().Contain(o => o.CustomerId == "seed-cust");
    }

    [Fact]
    public async Task CreateOrder_WithValidPayload_Returns201WithLocation()
    {
        var payload = new { CustomerId = "int-test-cust", Total = 149.99m };
        var response = await _client.PostAsJsonAsync("/api/orders", payload);

        response.StatusCode.Should().Be(HttpStatusCode.Created);
        response.Headers.Location.Should().NotBeNull();

        var created = await response.Content.ReadFromJsonAsync<OrderDto>();
        created!.Total.Should().Be(149.99m);
    }

    [Fact]
    public async Task GetOrder_WithNonExistentId_Returns404WithProblemDetails()
    {
        var response = await _client.GetAsync($"/api/orders/{Guid.NewGuid()}");

        response.StatusCode.Should().Be(HttpStatusCode.NotFound);

        var problem = await response.Content.ReadFromJsonAsync<ProblemDetails>();
        problem!.Title.Should().Be("Order not found");
    }
}

Observability: What to Log and Monitor in Integration Tests

Integration test failures can be tricky to debug without proper observability. Here’s what to capture and how to instrument.

Structured Logging to Capture

  • Test Start/End: Track test name, execution timestamps.
  • Container State: Logs for container startup success/failure.
  • EF Core Queries: Enable logging of SQL statements generated during tests.
  • HTTP Requests & Responses: Status codes, request paths, bodies for critical tests.
  • Exceptions: Full stack traces with correlation IDs.

Example structured log snippet (JSON):

{
  "timestamp": "2024-05-01T15:22:11Z",
  "level": "Information",
  "event": "TestStart",
  "testName": "CreateOrder_WithValidPayload_Returns201WithLocation"
}

Key Metrics to Collect (RED & USE)

MetricDescriptionTarget / SLO
Request RateNumber of HTTP requests handledSLO: No drop below expected baseline
Request DurationTime taken for HTTP requestsP95 under 200ms
Error RatePercentage of failed HTTP requests< 1% in tests to detect regressions
Container CPU UsageContainer CPU consumedShould stay within limits
Container Memory UsageContainer memory consumptionNo leaks or spikes

Distributed Tracing with OpenTelemetry

Instrument the WebApplicationFactory host with OpenTelemetry for tracing integration tests:

builder.ConfigureServices(services =>
{
    services.AddOpenTelemetryTracing(tracing =>
    {
        tracing.AddAspNetCoreInstrumentation()
               .AddHttpClientInstrumentation()
               .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("IntegrationTests"))
               .AddConsoleExporter();
    });
});

The above adds useful spans for HTTP request lifecycle and EF Core DB calls, helping debug performance issues or failures.


Trade-offs: WebApplicationFactory + Testcontainers vs. Alternatives

ApproachProsCons
WebApplicationFactory + TestcontainersRealistic end-to-end tests with real DB
Close to prod
More complex setup
Longer test execution
Docker dependency
In-memory Database (e.g. InMemory EF provider)Fast, simple setup
No Docker required
Different SQL semantics
No real SQL Server features
SQL Server LocalDB or Shared InstanceReal DB engine behavior
No Docker
Setup complexity
Stateful, must reset DB between tests
Mocking DbContext or RepositoryFast, unit-test style
No dependencies
Misses integration issues
Prone to divergent test/production behaviors

Expanded Realistic Code Example: Test with Resetting DB State Between Tests

Sometimes you want each test isolated with a clean database state:

public class OrdersApiIsolatedTests : IClassFixture<SqlServerFixture>, IDisposable
{
    private readonly TestWebAppFactory _factory;
    private readonly HttpClient _client;
    private readonly SqlServerFixture _fixture;

    public OrdersApiIsolatedTests(SqlServerFixture fixture)
    {
        _fixture = fixture;
        _factory = new TestWebAppFactory(fixture.ConnectionString);
        _client = _factory.CreateClient();

        ResetDatabaseAsync().GetAwaiter().GetResult();
    }

    private async Task ResetDatabaseAsync()
    {
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        await db.Database.EnsureDeletedAsync();
        await db.Database.EnsureCreatedAsync();
        // Seed
        db.Orders.Add(new Order { Id = Guid.NewGuid(), CustomerId = "reset-cust", Total = 200 });
        await db.SaveChangesAsync();
    }

    public void Dispose()
    {
        _client.Dispose();
        _factory.Dispose();
    }

    [Fact]
    public async Task GetOrders_ShouldReturnSeededData()
    {
        var resp = await _client.GetAsync("/api/orders");

        resp.StatusCode.Should().Be(HttpStatusCode.OK);
        var orders = await resp.Content.ReadFromJsonAsync<List<OrderDto>>();
        orders.Should().ContainSingle(o => o.CustomerId == "reset-cust");
    }
}

Notice how database is fully reset and seeded per test class, ensuring no cross-test contamination.


Best Practices for CI

  • Use test containers on CI runners with Docker installed (most GitHub Actions, Azure Pipelines).
  • Likely add a Docker layer cache step to speed up container image pulls.
  • Fail integration tests fast on container startup issues.
  • Parameterize container images and tags for easy upgrade and debugging.
  • Combine with integration environment variables (e.g., ASPNETCORE_ENVIRONMENT=IntegrationTests) for config isolation.

Internal Mechanics of WebApplicationFactory and Testcontainers Integration

Understanding what happens under the hood when combining WebApplicationFactory<TEntryPoint> with Testcontainers enlightens both debugging and advanced customization.

WebApplicationFactory Hosting Lifecycle

  • In-memory TestServer: WebApplicationFactory internally creates a TestServer hosting the ASP.NET Core pipeline without opening network sockets.
  • Startup Execution: It calls the same startup program entry point as production (Program.Main or Startup class), running middleware, DI configuration, routing maps.
  • ServiceProvider Isolation: Each test instance or factory invocation builds a scoped IServiceProvider; hence services are isolated per factory.
  • ConfigureWebHost Override: By overriding ConfigureWebHost, you can intercept and alter DI registrations, inject test overrides, or tweak configuration without changing production code.

Key point: This allows swapping the production database context with a connection string to your SQL container, seamlessly redirecting all EF Core calls to a real database.

Testcontainers SQL Server Container Lifecycle

  • Docker Container API: Testcontainers uses Docker Remote API to programmatically create and run containers on localhost Docker daemon.
  • Ephemeral Lifecycle: Containers are created fresh with a clean file system on test startup and destroyed afterward – guaranteeing test isolation.
  • Port Binding and Networking: Testcontainers maps SQL Server container ports to localhost ephemeral ports, providing connection details via the GetConnectionString() method.
  • Image Selection: Using mcr.microsoft.com/azure-sql-edge is beneficial in CI for fast startup and small footprint.

How Migration and Seeding Fit In

  • EF Core migrations applied via Database.EnsureCreated() or Database.Migrate() run against the SQL container, creating schema on the fly.
  • Seeding is done synchronously or asynchronously right after migrations, injecting deterministic data into the clean database state.
  • Because the database is real, this avoids subtle bugs that occur in InMemory providers where queries behave differently.

Interaction Flow Recap

sequenceDiagram
    participant Test as Test Code
    participant Factory as WebApplicationFactory
    participant TestServer as ASP.NET Core TestServer
    participant SQLContainer as Dockerized SQL Server

    Test->>Factory: CreateClient()
    Factory->>TestServer: Starts ASP.NET Core pipeline in memory
    TestServer->>SQLContainer: Establish SQL connection using DB context
    Test->>TestServer: HTTP request via HttpClient
    TestServer->>SQLContainer: Execute EF Core SQL statements
    SQLContainer-->>TestServer: Return records
    TestServer-->>Test: Send HTTP response

This flow illustrates how the entire stack—HTTP pipeline, middleware, routing, DB access—is exercised fully, all within test memory and Docker container boundaries.


Edge Cases, Failure Modes, and How to Mitigate Them

1. Container Startup Failures

Common when:

  • Docker daemon is not running or inaccessible.
  • Image pull fails due to network issues.
  • Insufficient system resources cause container startup to fail.

Mitigation:

  • Fail fast in SqlServerFixture.InitializeAsync() with clear error messages.
  • Retry container start with exponential backoff (optional).
  • Validate Docker availability in CI pre-checks.
public async Task InitializeAsync()
{
    try
    {
        await _container.StartAsync();
    }
    catch (Exception ex)
    {
        // Log detailed failure
        throw new InvalidOperationException("Failed to start SQL container", ex);
    }
}

2. Port Conflicts and Parallelism

When running tests in parallel:

  • Multiple test suites trying to start containers bind to same port or share connection strings.
  • Could yield flaky connection errors or data leakage.

Mitigation:

  • Use Testcontainers configured with random port bindings.
  • Isolate tests at class or process level.
  • Use container network aliases or distinct schema names to isolate DB state.

3. Migration and Seeding Race Conditions

  • Simultaneous migration & seeding runs cause conflicts or deadlocks in SQL Server.
  • Happens when multiple tests run migrations simultaneously against the same DB instance.

Mitigation:

  • Run one container per test class, not globally shared.
  • Prefer EnsureCreated for simple test schema without migrations.
  • Alternatively, execute migrations and seeding before tests and reuse read-only container snapshots if your platform supports it.

4. State Persistence Between Tests

If container lifecycle extends across multiple tests:

  • Data created in one test pollutes subsequent ones.
  • Leads to flaky or inconsistent test results.

Mitigation:

  • Reset the database schema between tests using either:
    • EnsureDeleted + EnsureCreated.
    • Clean SQL scripts or DB snapshots.
  • Prefer isolated container-per-test or fixture-per-class model depending on test runtime cost constraints.

5. EF Core Provider Differences

Even with SQL Server container, subtle differences can arise:

  • SQL Server Edge vs. full SQL Server Enterprise.
  • Differences in collation, compatibility levels, or unsupported features.

Mitigation:

  • Use production like configurations when defining container image and arguments.
  • Test critical queries against real production DB when possible to verify correctness.
  • Keep testing container image consistent with deployed production version.

Performance and Observability in Integration Tests: A Deep Dive

While integration tests naturally run slower than unit tests, expanding observability helps optimize and diagnose them effectively.

Performance Considerations

  • Starting a SQL container can take 5-30 seconds (depends on cached images).
  • Running migrations adds seconds depending on schema complexity.
  • Test execution time is dominated by HTTP + DB round trips – optimize queries.

Improving Test Run Performance

  • Reuse container per test class: Avoid startup cost per test.
  • Parallelize test classes: Only if container instances are isolated.
  • Cache Docker image layers in CI to reduce pull time.
  • Minimize migration complexity: Keep migrations fast and incremental.
  • Seed only essential data: Avoid large datasets which slow queries and test runtime.

Observability Recommendations for Tests

1. Logs

  • Enable EF Core logging at Information level to capture SQL queries.
  • Log HTTP request/response bodies for failed tests only to minimize noise.
  • Add correlation IDs in logs linking HTTP requests to database query spans.
  • Capture container lifecycle events (start, stop, dispose) with timestamps.

Sample ILogger config snippet for EF Core logging:

services.AddDbContext<AppDbContext>(opts =>
    opts.UseSqlServer(_connectionString)
        .EnableSensitiveDataLogging()
        .LogTo(Console.WriteLine, LogLevel.Information));

2. Metrics (RED & USE principles for tests)

MetricDescriptionCollection MethodObservability Value
Request RateHTTP requests executedHttpClient middlewareDetects test runs, throttling or stalls
Request DurationLatency of HTTP requestsTiming wrappersIdentify slowest test scenarios
Error RateFailed HTTP or DB operationsException handlersFlag regressions or flaky tests
SQL Query DurationDB query execution timeEF Core loggingPinpoint slow queries, indexes issues
Container CPU & MemoryDocker container resource usageDocker stats APIDiagnose resource exhaustion on test machine

3. Distributed Tracing

Leverage OpenTelemetry to trace flows cross HTTP + EF Core + test boundaries:

  • Instrument ASP.NET Core pipeline.
  • Instrument outgoing HTTP calls (if any).
  • Instrument EF Core queries.
  • Export to console or lightweight backends in test environment.

Minimal example:

builder.ConfigureServices(services =>
{
    services.AddOpenTelemetryTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddEntityFrameworkCoreInstrumentation()
            .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("IntegrationTestApp"))
            .AddConsoleExporter();
    });
});

Traces reveal where slowdowns occur, e.g., authentication middleware vs. DB queries.


Decision Checklist: Should You Use WebApplicationFactory + Testcontainers?

Before adopting this architecture, consider your project context carefully:

CriterionRecommended Approach
Need near-production parity in DB behavior?Yes → WebApplicationFactory + Testcontainers
Run tests on CI environment with Docker?Yes → Feasible
Large existing legacy DB schema or migration?Yes → Real DB container testing essential
Very fast test feedback requiredMaybe → Unit/in-memory mocks suffice
Simple CRUD APIs with no complex SQLMaybe → In-memory provider can suffice
Limited Docker support or Windows-only CI runnersNo → Use LocalDB or SQL Server installed
Need to run many parallel test suitesNo → Container costs may rise, isolate carefully

This checklist helps balance test fidelity against complexity and execution speed.


Practical Extendable Minimal Example: Adding a Custom Health Check

Integration tests often need endpoint health verification which can be extended easily.

// In your ASP.NET Core Program.cs or Startup.cs
builder.Services.AddHealthChecks()
    .AddSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"));

// In your TestWebAppFactory ConfigureWebHost override
builder.ConfigureServices(services =>
{
    // Existing DB override here...

    services.AddHealthChecks()
        .AddSqlServer(_connectionString);
});

// Integration test example
[Fact]
public async Task HealthCheck_ReturnsHealthy()
{
    var response = await _client.GetAsync("/health");
    response.StatusCode.Should().Be(HttpStatusCode.OK);

    var content = await response.Content.ReadAsStringAsync();
    content.Should().Contain("Healthy");
}

Notice how seamlessly you can extend your test host with health checks or other services and test them end-to-end.


Summary: Key Takeaways for Advanced Integration Testing

  • WebApplicationFactory runs your entire ASP.NET Core pipeline in-memory with customizable services.
  • Testcontainers spins up real Dockerized SQL Server databases providing unmatched production parity.
  • Customize ConfigureWebHost to override DI registrations to point EF Core to ephemeral test DB.
  • Manage container lifecycle smartly using xUnit fixtures and async initialization for performance.
  • Anticipate and mitigate container startup, concurrency, and state persistence issues in parallel runs.
  • Implement structured logging, RED/USE metrics, and OpenTelemetry tracing for test observability.
  • Balance realism with test speed and CI constraints using a clear decision matrix.
  • Extend tests by adding features like health checks easily on the test host.
  • This setup delivers confidence by exercising real HTTP requests and SQL queries while keeping tests isolated and reproducible.

For senior engineers, mastering this combo is critical for critical-path test coverage in sophisticated ASP.NET Core architectures.

Summary

  • Integration testing ASP.NET Core apps requires full pipeline coverage and reliable DB backends.
  • WebApplicationFactory<TEntryPoint> runs a real ASP.NET Core app in-memory, letting tests send HTTP requests without a live server port.
  • Testcontainers start real, isolated SQL Server containers on-demand, matching production DB behavior exactly.
  • Use IAsyncLifetime and xUnit fixtures to start containers once per class, boosting test speed.
  • Configure and override the DbContext to point to the ephemeral container, run migrations, and seed test data.
  • Write tests that do real HTTP requests, asserting on status codes and JSON payloads.
  • Add logging, metrics, and distributed tracing for observability into test failures and performance.
  • Be mindful of tradeoffs versus mocks and in-memory providers; the integration approach increases test confidence at the cost of complexity and runtime.
  • This strategy represents a best practice for senior C# engineers aiming for robust, performant, and realistic automated tests.

For more about WebApplicationFactory, see the official docs at https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests
For Testcontainers.NET, visit https://dotnet.testcontainers.org/
For EF Core testing guidance, see https://learn.microsoft.com/en-us/ef/core/testing/


This guide empowers you to design and implement integration tests that reliably mirror production behavior—allowing you to catch subtle bugs early and sleep well at night.