Integration Testing in ASP.NET Core: The Complete Advanced Guide

// CustomWebApplicationFactory.cs
// This factory is the heart of your integration test setup.
// It replaces the real SQL Server database with SQLite so tests
// run fast, in-memory, and without needing a live DB connection.

using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using OrderApi.Data; // Your real DbContext namespace

namespace OrderApi.IntegrationTests;

// TEntryPoint must be your Program class (or Startup).
// If Program is internal, add: public partial class Program { }
// to your web project's Program.cs.
public class OrderApiFactory : WebApplicationFactory<Program>
{
    // Override this to customise the host BEFORE it is built.
    // This runs once per factory instance, not once per test.
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureServices(services =>
        {
            // Step 1: Remove the real DbContext registration that
            // Program.cs added (it points at SQL Server).
            services.RemoveAll<DbContextOptions<OrderDbContext>>();
            services.RemoveAll<OrderDbContext>();

            // Step 2: Register a SQLite in-memory database instead.
            // Using a named connection string keeps the same DB across
            // the lifetime of this factory instance — critical for
            // tests that seed data in one call and read it in another.
            services.AddDbContext<OrderDbContext>(options =>
            {
                options.UseSqlite("Data Source=:memory:");
            });

            // Step 3: Build the schema once the container is ready.
            // We resolve a scope manually so EnsureCreated() runs
            // against the in-memory database before any test touches it.
            var serviceProvider = services.BuildServiceProvider();
            using var scope = serviceProvider.CreateScope();
            var dbContext = scope.ServiceProvider
                                 .GetRequiredService<OrderDbContext>();

            // EnsureCreated() is fine for tests; never use it in production.
            // It creates tables from your EF model without running migrations.
            dbContext.Database.EnsureCreated();
        });

        // Suppress noisy logs during test runs — errors still show.
        builder.UseEnvironment("Testing");
    }
}

// OrderEndpointTests.cs
// Demonstrates the full pattern:
//   1. IClassFixture shares one factory across all tests in the class
//   2. IAsyncLifetime resets the DB before each test
//   3. Each test creates its own HttpClient (cheap)
//   4. Tests are fully independent of each other

using System.Net;
using System.Net.Http.Json;
using Microsoft.Extensions.DependencyInjection;
using OrderApi.Data;
using OrderApi.Models;
using Xunit;

namespace OrderApi.IntegrationTests;

// IClassFixture<OrderApiFactory>: xUnit creates one OrderApiFactory
// for the whole class, not one per test. Host boots once.
public class OrderEndpointTests :
    IClassFixture<OrderApiFactory>,
    IAsyncLifetime  // Gives us InitializeAsync / DisposeAsync per test
{
    private readonly OrderApiFactory _factory;
    private readonly HttpClient _httpClient;

    public OrderEndpointTests(OrderApiFactory factory)
    {
        _factory = factory;
        // CreateClient() is cheap — it just creates a new HttpClient
        // connected to the already-booted TestServer.
        _httpClient = factory.CreateClient();
    }

    // Runs BEFORE each test method — use this to seed clean data.
    public async Task InitializeAsync()
    {
        // Get a scoped service directly from the factory's DI container
        // to reset state without going through HTTP.
        using var scope = _factory.Services.CreateScope();
        var dbContext = scope.ServiceProvider
                             .GetRequiredService<OrderDbContext>();

        // Clear all orders so each test starts from a known empty state.
        dbContext.Orders.RemoveRange(dbContext.Orders);
        await dbContext.SaveChangesAsync();
    }

    // Runs AFTER each test method — clean up if needed.
    public Task DisposeAsync() => Task.CompletedTask;

    [Fact]
    public async Task GetOrders_WhenNoOrdersExist_ReturnsEmptyArray()
    {
        // Act — fire a real HTTP GET through the full middleware pipeline
        var response = await _httpClient.GetAsync("/api/orders");

        // Assert on the HTTP status code first
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);

        // Deserialize the real JSON body — this catches serialization bugs
        // that unit tests on the service layer would never catch
        var orders = await response.Content
                                   .ReadFromJsonAsync<List<OrderDto>>();
        Assert.NotNull(orders);
        Assert.Empty(orders);
    }

    [Fact]
    public async Task CreateOrder_WithValidPayload_Returns201AndLocationHeader()
    {
        // Arrange — build a realistic request payload
        var newOrder = new CreateOrderRequest
        {
            CustomerEmail = "alice@example.com",
            ProductSku    = "WIDGET-42",
            Quantity      = 3
        };

        // Act — POST through the real routing + validation pipeline
        var response = await _httpClient.PostAsJsonAsync("/api/orders", newOrder);

        // Assert — 201 Created with a Location header pointing at the new resource
        Assert.Equal(HttpStatusCode.Created, response.StatusCode);
        Assert.NotNull(response.Headers.Location);

        // Verify the resource actually exists by following the Location header
        var getResponse = await _httpClient.GetAsync(response.Headers.Location);
        Assert.Equal(HttpStatusCode.OK, getResponse.StatusCode);

        var createdOrder = await getResponse.Content
                                            .ReadFromJsonAsync<OrderDto>();
        Assert.Equal("alice@example.com", createdOrder!.CustomerEmail);
    }

    [Fact]
    public async Task CreateOrder_WithInvalidQuantity_Returns400WithProblemDetails()
    {
        // Arrange — quantity of 0 should fail model validation
        var invalidOrder = new CreateOrderRequest
        {
            CustomerEmail = "bob@example.com",
            ProductSku    = "WIDGET-42",
            Quantity      = 0  // Invalid: must be >= 1
        };

        // Act
        var response = await _httpClient.PostAsJsonAsync("/api/orders", invalidOrder);

        // Assert — model validation returns 400 with RFC 7807 ProblemDetails
        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);

        // Check the Content-Type is application/problem+json, not application/json
        // This is a real content-negotiation detail only integration tests catch
        Assert.Equal(
            "application/problem+json",
            response.Content.Headers.ContentType?.MediaType);
    }
}

// TestAuthHandler.cs
// A custom AuthenticationHandler that lets tests bypass real JWT validation.
// Only active when EnvironmentName == "Testing".

using System.Security.Claims;
using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Authentication;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

namespace OrderApi.IntegrationTests;

// The options class carries no state — we just need it to satisfy
// the AuthenticationHandler<TOptions> generic constraint.
public class TestAuthHandlerOptions : AuthenticationSchemeOptions { }

public class TestAuthHandler
    : AuthenticationHandler<TestAuthHandlerOptions>
{
    // The header name that tests use to pass claim data.
    // Format: "sub=alice@example.com,role=OrderManager,role=Admin"
    public const string AuthHeaderName = "X-Integration-Test-Auth";
    public const string SchemeName    = "TestAuth";

    public TestAuthHandler(
        IOptionsMonitor<TestAuthHandlerOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder)
        : base(options, logger, encoder) { }

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // If the test didn't send the auth header, fail authentication
        // gracefully — this lets tests for unauthenticated scenarios work.
        if (!Request.Headers.TryGetValue(AuthHeaderName, out var headerValue))
        {
            return Task.FromResult(AuthenticateResult.NoResult());
        }

        // Parse comma-separated "key=value" pairs into claims.
        // Example header: "sub=alice@example.com,role=OrderManager"
        var claims = headerValue.ToString()
            .Split(',', StringSplitOptions.RemoveEmptyEntries)
            .Select(pair =>
            {
                var parts = pair.Split('=', 2);
                return new Claim(parts[0].Trim(), parts[1].Trim());
            })
            .ToList();

        // Always include a name identifier so standard
        // User.Identity.IsAuthenticated returns true.
        if (!claims.Any(c => c.Type == ClaimTypes.NameIdentifier))
        {
            var subClaim = claims.FirstOrDefault(c => c.Type == "sub");
            if (subClaim is not null)
            {
                claims.Add(new Claim(
                    ClaimTypes.NameIdentifier,
                    subClaim.Value));
            }
        }

        var identity  = new ClaimsIdentity(claims, SchemeName);
        var principal = new ClaimsPrincipal(identity);
        var ticket    = new AuthenticationTicket(principal, SchemeName);

        return Task.FromResult(AuthenticateResult.Success(ticket));
    }
}

// -----------------------------------------------------------------
// Extension to register this handler inside OrderApiFactory
// -----------------------------------------------------------------
// Add this inside your OrderApiFactory.ConfigureWebHost:
//
//   services.AddAuthentication(TestAuthHandler.SchemeName)
//           .AddScheme<TestAuthHandlerOptions, TestAuthHandler>(
//               TestAuthHandler.SchemeName, _ => { });
//
// -----------------------------------------------------------------
// HttpClientExtensions.cs — ergonomic helpers for test methods
// -----------------------------------------------------------------

namespace OrderApi.IntegrationTests;

public static class HttpClientExtensions
{
    // Call this to make any request look like it came from
    // the specified user with the specified roles.
    public static HttpClient AsUser(
        this HttpClient client,
        string email,
        params string[] roles)
    {
        // Build the header value: "sub=alice@example.com,role=OrderManager"
        var rolePairs   = roles.Select(r => $"role={r}");
        var claimString = string.Join(',', new[] { $"sub={email}" }.Concat(rolePairs));

        // Remove any previously set auth header so we can switch users
        // between calls on the same client instance.
        client.DefaultRequestHeaders.Remove(
            TestAuthHandler.AuthHeaderName);

        client.DefaultRequestHeaders.Add(
            TestAuthHandler.AuthHeaderName,
            claimString);

        return client; // Fluent — lets you chain: client.AsUser(...).GetAsync(...)
    }
}

// -----------------------------------------------------------------
// Usage in a test:
// -----------------------------------------------------------------
//
//   [Fact]
//   public async Task DeleteOrder_AsOrderManager_Returns204()
//   {
//       _httpClient.AsUser("alice@example.com", "OrderManager");
//       var response = await _httpClient.DeleteAsync("/api/orders/1");
//       Assert.Equal(HttpStatusCode.NoContent, response.StatusCode);
//   }
//
//   [Fact]
//   public async Task DeleteOrder_AsRegularUser_Returns403()
//   {
//       _httpClient.AsUser("bob@example.com"); // No roles
//       var response = await _httpClient.DeleteAsync("/api/orders/1");
//       Assert.Equal(HttpStatusCode.Forbidden, response.StatusCode);
//   }

// TestcontainersOrderApiFactory.cs
// Uses Testcontainers to spin up a real PostgreSQL container in CI.
// Requires NuGet: Testcontainers.PostgreSql
//
// This is the production-grade approach for teams who need
// their integration tests to run against the real database engine.

using DotNet.Testcontainers.Builders;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Testcontainers.PostgreSql;
using OrderApi.Data;

namespace OrderApi.IntegrationTests;

// IAsyncLifetime makes xUnit call InitializeAsync before the first test
// and DisposeAsync after the last — perfect for starting and stopping
// the Docker container around the test run.
public class PostgresOrderApiFactory
    : WebApplicationFactory<Program>, IAsyncLifetime
{
    // Testcontainers builds a real Docker container for PostgreSQL.
    // The builder pattern configures the image, port mapping,
    // and database credentials.
    private readonly PostgreSqlContainer _postgresContainer =
        new PostgreSqlBuilder()
            .WithImage("postgres:16-alpine")   // Pin the version for reproducibility
            .WithDatabase("integration_tests")
            .WithUsername("test_user")
            .WithPassword("test_password_never_used_in_prod")
            .WithCleanUp(true)  // Remove container after test run
            .Build();

    // Start the container before any test touches the factory.
    // This is where Docker actually pulls the image and boots Postgres.
    public async Task InitializeAsync()
    {
        await _postgresContainer.StartAsync();
    }

    // Stop and remove the container when the test run finishes.
    public new async Task DisposeAsync()
    {
        await _postgresContainer.StopAsync();
        await base.DisposeAsync();
    }

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureServices(services =>
        {
            // Remove the production DbContext pointing at SQL Server
            services.RemoveAll<DbContextOptions<OrderDbContext>>();
            services.RemoveAll<OrderDbContext>();

            // Wire up EF Core to the live Postgres container.
            // GetConnectionString() returns the dynamically assigned
            // host/port from the running container.
            services.AddDbContext<OrderDbContext>(options =>
            {
                options.UseNpgsql(
                    _postgresContainer.GetConnectionString());
            });

            // Run migrations against the real Postgres schema.
            // MigrateAsync is better than EnsureCreated here because
            // it validates that your migration history is correct.
            var serviceProvider = services.BuildServiceProvider();
            using var scope     = serviceProvider.CreateScope();
            var dbContext       = scope.ServiceProvider
                                       .GetRequiredService<OrderDbContext>();

            dbContext.Database.Migrate();
        });

        builder.UseEnvironment("Testing");
    }
}

// -----------------------------------------------------------------
// CollectionFixture.cs — share ONE factory across ALL test classes
// -----------------------------------------------------------------
// This cuts host boot time from O(n classes) to O(1).

[CollectionDefinition("OrderApi Integration Tests")]
public class OrderApiTestCollection
    : ICollectionFixture<PostgresOrderApiFactory> { }

// Then in each test class, replace IClassFixture with [Collection]:
//
//   [Collection("OrderApi Integration Tests")]
//   public class OrderEndpointTests
//   {
//       public OrderEndpointTests(PostgresOrderApiFactory factory) { ... }
//   }
//
// All classes in the same collection share the same factory instance —
// one Docker container, one host boot, for the entire test run.