Integration Tests

An integration test runs your code against the real thing it will use in production. A real database, a real migration, real SQL generated by the real provider.

Everything in the previous module removed infrastructure so tests could be fast and focused. That is the right trade for logic, and it leaves a gap: every unit test in the suite can pass while the application fails to start, because nothing the unit tests did ever touched a connection string, a registration or a query the database has to understand.

So this is not a stricter version of unit testing. It is a different question. A unit test asks whether a rule is correct. An integration test asks whether the parts fit together.

using Microsoft.EntityFrameworkCore;
using Testcontainers.MsSql;
using Xunit;

public class SqlServerFixture : IAsyncLifetime
{
    private readonly MsSqlContainer _container = new MsSqlBuilder().Build();

    public string ConnectionString => _container.GetConnectionString();

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

        await using var db = CreateContext();
        await db.Database.MigrateAsync();
    }

    public OrderingDbContext CreateContext() =>
        new OrderingDbContext(
            new DbContextOptionsBuilder<OrderingDbContext>()
                .UseSqlServer(ConnectionString)
                .Options);

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

• Testcontainers starts a database in a container for the test run and throws it away afterwards. Nothing is installed on the machine, and the version is pinned by the image rather than by whatever a developer happens to have.
• IAsyncLifetime is xUnit's hook for setup and teardown that needs to await something. InitializeAsync runs before the tests, DisposeAsync after. The exact signatures differ between xUnit major versions, so match whatever the interface in your project declares.
• MigrateAsync applies your real migrations to the empty database. This single line is doing more work than it looks like: if a migration is broken, the fixture fails and every test in the class reports it.
• Starting the container takes a few seconds, which is why it belongs in a fixture shared by a class or a collection rather than running per test. Share the container; do not share the data — that is the next section.
• This requires a container runtime on the machine and in the pipeline. Where that is not available, the alternative is a database the pipeline provisions itself; the test code is the same, only ConnectionString changes.

public class OrderQueryTests : IClassFixture<SqlServerFixture>
{
    private readonly SqlServerFixture _fixture;

    public OrderQueryTests(SqlServerFixture fixture) => _fixture = fixture;

    [Fact]
    public async Task FindByCompany_MatchesCaseInsensitively()
    {
        // Arrange
        await using var db = _fixture.CreateContext();
        db.Customers.Add(new Customer { CompanyName = "Kirby Logistics" });
        await db.SaveChangesAsync();

        var repository = new CustomerRepository(db);

        // Act
        IReadOnlyList<Customer> matches = await repository.FindByCompanyAsync("kirby");

        // Assert
        Assert.Single(matches);
    }

    [Fact]
    public async Task SaveChanges_WithDuplicateEmail_IsRejectedByTheDatabase()
    {
        await using var db = _fixture.CreateContext();
        db.Customers.Add(new Customer { CompanyName = "Ward Supplies", Email = "ops@ward.example" });
        db.Customers.Add(new Customer { CompanyName = "Ward Supplies Ltd", Email = "ops@ward.example" });

        await Assert.ThrowsAsync<DbUpdateException>(() => db.SaveChangesAsync());
    }
}

• The first test is the one worth studying. If FindByCompanyAsync lowercases both sides in C#, it works perfectly against a list and throws when the provider tries to turn it into SQL. A fake repository reports success for code that cannot run.
• It also pins down behaviour that depends on the database rather than on your code. Whether "kirby" matches "Kirby" is decided by the column's collation, and no amount of C# reasoning will tell you what that is on the server you deploy to.
• The second test asserts that the unique index exists and is enforced. The in-memory fake from the previous module cheerfully accepts both rows, so this rule has no coverage until a real database is involved.
• DbUpdateException is the wrapper Entity Framework Core raises when the database refuses a write. Asserting on the wrapper rather than the provider-specific error inside it keeps the test readable and still proves the write was rejected.
• IClassFixture<T> tells xUnit to create the fixture once and hand it to every test in the class, so the container starts once rather than twice.