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
| Component | Responsibility | Benefits |
|---|---|---|
| SqlServerFixture | Manages lifecycle of ephemeral SQL Server container per test class | Realistic DB environment, starts/stops once per class for speed |
| TestWebAppFactory | Hosts the full ASP.NET Core app with overridden DbContext to point to container | Exercises full middleware, routing, validation, DI |
| Integration Test | Sends HTTP requests through in-memory TestServer client, verifies responses | Tests 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 JSONFigure 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)
| Metric | Description | Target / SLO |
|---|---|---|
| Request Rate | Number of HTTP requests handled | SLO: No drop below expected baseline |
| Request Duration | Time taken for HTTP requests | P95 under 200ms |
| Error Rate | Percentage of failed HTTP requests | < 1% in tests to detect regressions |
| Container CPU Usage | Container CPU consumed | Should stay within limits |
| Container Memory Usage | Container memory consumption | No 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
| Approach | Pros | Cons |
|---|---|---|
| WebApplicationFactory + Testcontainers | Realistic 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 Instance | Real DB engine behavior No Docker | Setup complexity Stateful, must reset DB between tests |
| Mocking DbContext or Repository | Fast, 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:
WebApplicationFactoryinternally creates aTestServerhosting the ASP.NET Core pipeline without opening network sockets. - Startup Execution: It calls the same startup program entry point as production (
Program.Mainor 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-edgeis beneficial in CI for fast startup and small footprint.
How Migration and Seeding Fit In
- EF Core migrations applied via
Database.EnsureCreated()orDatabase.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
InMemoryproviders 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 responseThis 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
EnsureCreatedfor 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
Informationlevel 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)
| Metric | Description | Collection Method | Observability Value |
|---|---|---|---|
| Request Rate | HTTP requests executed | HttpClient middleware | Detects test runs, throttling or stalls |
| Request Duration | Latency of HTTP requests | Timing wrappers | Identify slowest test scenarios |
| Error Rate | Failed HTTP or DB operations | Exception handlers | Flag regressions or flaky tests |
| SQL Query Duration | DB query execution time | EF Core logging | Pinpoint slow queries, indexes issues |
| Container CPU & Memory | Docker container resource usage | Docker stats API | Diagnose 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:
| Criterion | Recommended 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 required | Maybe → Unit/in-memory mocks suffice |
| Simple CRUD APIs with no complex SQL | Maybe → In-memory provider can suffice |
| Limited Docker support or Windows-only CI runners | No → Use LocalDB or SQL Server installed |
| Need to run many parallel test suites | No → 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-memorywith customizable services. - Testcontainers spins up real Dockerized SQL Server databases providing unmatched production parity.
- Customize
ConfigureWebHostto 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
IAsyncLifetimeand xUnit fixtures to start containers once per class, boosting test speed. - Configure and override the
DbContextto 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.