Testing

#Choose tests by risk: pyramid and trophy

Tests should catch failures before users do and make their cause easy to locate. A unit test checks a small behavior without infrastructure; an integration test checks connected components; an E2E test exercises a complete user journey.

These are guides rather than mandatory ratios. Test invoice discounts with fast units, persistence and payment boundaries with integration tests, and checkout with selected E2E journeys. Avoid repeating every calculation case at every level.

#Readable unit tests: AAA, FIRST and xUnit v3

A useful test explains one rule and fails clearly. AAA means Arrange inputs, Act on the behavior, and Assert the result. FIRST means Fast, Independent, Repeatable, Self-validating and Timely. This example belongs in an xUnit v3 test project with using Xunit;.

public static class ShippingPolicy
{
    public static int Fee(int total) => total >= 1000 ? 0 : 50;
}

public sealed class ShippingTests
{
    [Fact] // (1)
    public void Fee_AtFreeShippingThreshold_IsZero()
    {
        var total = 1000;                  // Arrange
        var fee = ShippingPolicy.Fee(total); // Act
        Assert.Equal(0, fee);              // Assert (2)
    }

    [Theory] // (3)
    [InlineData(999, 50)]
    [InlineData(1000, 0)]
    [InlineData(1001, 0)]
    public void Fee_UsesThreshold(int total, int expected) =>
        Assert.Equal(expected, ShippingPolicy.Fee(total));
}

Several assertions can describe one logical outcome. Avoid testing trivial getters just to raise coverage or combining unrelated behaviors into one long test. Use the xUnit v3 guide to configure the appropriate runner.

#Fixtures: share setup cost without sharing failures

xUnit creates a fresh test-class instance for each test case. Use constructors for lightweight setup and IDisposable or IAsyncDisposable for cleanup. A fixture shares an expensive resource; it does not automatically reset its data.

This example requires using Xunit; and demonstrates collection wiring with a counter; a real database fixture also needs data isolation.

public sealed class SharedCounter
{
    public int Value { get; set; }
}

[CollectionDefinition("orders")]
public sealed class OrdersCollection : ICollectionFixture<SharedCounter> { } // (1)

[Collection("orders")]
public sealed class OrderTests(SharedCounter counter) // (2)
{
    [Fact]
    public void Counter_CanBeReset()
    {
        counter.Value = 0;
        Assert.Equal(0, counter.Value);
    }
}

#Assertions and test doubles: test the contract

An assertion should detect the intended defect: a wrong total, a specific error, or a duplicate charge. A dummy fills an unused parameter; a stub returns predefined responses; a fake is a simplified working implementation; a mock verifies expected interactions; a spy records calls for later inspection. These are roles, and one library can support several.

This standalone xUnit example requires the NSubstitute and Moq packages. It shows equivalent stubs in both libraries; use one in an actual test.

using Moq;
using NSubstitute;
using Xunit;

public interface IPaymentGateway
{
    bool Charge(decimal amount);
}

public sealed class Checkout(IPaymentGateway gateway)
{
    public bool TryPay(decimal amount)
    {
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(amount);
        return gateway.Charge(amount);
    }
}

public sealed class GatewayTests
{
    [Fact]
    public void TryPay_WhenGatewayDeclines_ReturnsFalse()
    {
        var sub = Substitute.For<IPaymentGateway>();
        sub.Charge(100m).Returns(false); // (1)
        Assert.False(new Checkout(sub).TryPay(100m));
        sub.Received(1).Charge(100m); // (2)

        var mock = new Mock<IPaymentGateway>();
        mock.Setup(x => x.Charge(100m)).Returns(false); // (3)
        Assert.False(new Checkout(mock.Object).TryPay(100m));
        mock.Verify(x => x.Charge(100m), Times.Once());
    }
}

Use real domain objects and avoid verifying internal calls that change during refactoring. Built-in assertions are sufficient; Shouldly and AwesomeAssertions offer readable alternatives. FluentAssertions v8 requires a commercial license for commercial use; review its license before upgrading, as with any dependency.

#Test time without Thread.Sleep

A booking-expiry test should not wait ten real minutes. Injecting TimeProvider separates the rule from the machine clock. This example requires xUnit and Microsoft.Extensions.TimeProvider.Testing.

using Microsoft.Extensions.Time.Testing;
using Xunit;

public sealed class Booking(TimeProvider clock, DateTimeOffset expiresAt)
{
    public bool IsExpired => clock.GetUtcNow() >= expiresAt; // (1)
}

public sealed class BookingTests
{
    [Fact]
    public void Booking_AtExpiry_IsExpired()
    {
        var start = new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero);
        var clock = new FakeTimeProvider(start); // (2)
        var booking = new Booking(clock, start.AddMinutes(10));
        Assert.False(booking.IsExpired);
        clock.Advance(TimeSpan.FromMinutes(10)); // (3)
        Assert.True(booking.IsExpired);
    }
}

Advancing the clock does not mean every background continuation has completed. Await an explicit completion signal. Measure elapsed duration with timestamp APIs rather than an adjustable wall clock.

#Integration: an API with a real database

Testing a controller alone misses missing DI registrations and failed query translation. WebApplicationFactory uses TestServer without a network socket by default; Testcontainers manages a disposable database in Docker. This fragment requires xUnit v3, Microsoft.AspNetCore.Mvc.Testing 10, Testcontainers.PostgreSql, and an API project reference. The API must expose public partial class Program { } and read its connection string when registering DbContext. Assume a successful /health endpoint; apply migrations in a separate setup step before data tests.

using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Testcontainers.PostgreSql;
using Xunit;

public sealed class ApiFixture : IAsyncLifetime
{
    private readonly PostgreSqlContainer db = new PostgreSqlBuilder()
        .WithImage("postgres:17").Build();
    public WebApplicationFactory<Program> App { get; private set; } = null!;

    public async ValueTask InitializeAsync()
    {
        await db.StartAsync(); // (1)
        App = new WebApplicationFactory<Program>().WithWebHostBuilder(b =>
            b.UseSetting("ConnectionStrings:Default", db.GetConnectionString())); // (2)
    }

    public async ValueTask DisposeAsync()
    {
        if (App is not null) await App.DisposeAsync(); // (3)
        await db.DisposeAsync();
    }
}

public sealed class ApiTests(ApiFixture fixture) : IClassFixture<ApiFixture>
{
    [Fact]
    public async Task Health_ReturnsSuccess()
    {
        using var client = fixture.App.CreateClient(); // (4)
        using var response = await client.GetAsync("/health");
        response.EnsureSuccessStatusCode();
    }
}

Replace the payment boundary with a fake, but retain real authentication in security tests. TestServer does not test TLS or the reverse proxy; those need deployment tests. See the official Testcontainers example.

#Database isolation and why EF InMemory is insufficient

If a test passes alone but fails in the suite, look for shared data. A database per group with reset between cases is practical. Respawn inspects relationships and deletes data in a suitable order; initialize it after migrations and preserve migration history. This fragment assumes an open Npgsql connection to a test-only database and the Respawn package.

var reset = await Respawn.Respawner.CreateAsync(connection, new()
{
    DbAdapter = Respawn.DbAdapter.Postgres,
    SchemasToInclude = ["public"],
    TablesToIgnore = [new Respawn.Graph.Table("__EFMigrationsHistory")]
}); // (1)

await reset.ResetAsync(connection); // (2)
// Seed only the data required by the next test.

Transaction rollback works only when all work actually participates in that transaction; an HTTP request often opens another connection. EF InMemory is not relational: it cannot validate SQL translation, foreign keys or real transactions. SQLite helps in selected cases but differs from SQL Server and PostgreSQL in dialect and behavior. Test important queries on the production engine. See EF's comparison and Respawn.

#Contract and architecture tests

A service can pass every unit test and break a consumer by renaming a field. Consumer-driven contracts record the requests and responses a consumer needs; provider verification checks the actual provider against them. Pact is one option. Contracts do not replace authentication tests or complete business journeys.

Architecture tests prevent dependencies that violate architectural decisions. This xUnit example assumes a project reference to a domain assembly named Store.Domain.

using System.Reflection;
using Xunit;

public sealed class DependencyTests
{
    [Fact]
    public void Domain_DoesNotReferenceEfCore()
    {
        var domain = Assembly.Load("Store.Domain"); // (1)
        var references = domain.GetReferencedAssemblies();
        Assert.DoesNotContain(references,
            a => a.Name?.StartsWith("Microsoft.EntityFrameworkCore") == true); // (2)
    }
}

Snapshot tests help protect stable JSON shapes, but changes need review and volatile IDs and timestamps need normalization. Automatically accepting new snapshots removes their value.

#TDD, BDD, coverage and mutation testing

When a discount rule is unclear, write an expected example first. TDD is a short cycle: Red, confirm failure for the intended reason; Green, implement the minimum correct behavior; Refactor, improve design while tests remain green. BDD starts with collaborative examples and business discussion, sometimes expressed as Given, When and Then; it is more than a tool or syntax.

1. Write a case at the free-shipping threshold.
2. Run it before implementation to prove it detects missing behavior.
3. Implement it, add a below-threshold case, then improve the design.

Line coverage records executed code; branch coverage records decision paths. Neither measures assertion strength. Stryker.NET deliberately changes code, such as replacing >= with >; the boundary test should fail and kill that mutant.

#Flaky tests, load and concurrency

A flaky test changes outcome without an intentional code change. Common causes include real time, unrecorded random seeds, shared state, networks and assumed execution order. Use controlled clocks, isolated data and bounded polling for explicit conditions rather than arbitrary sleeps. Temporary quarantine needs an owner and repair deadline; retries alone hide the problem.

k6 defines load scenarios in JavaScript; NBomber supports .NET scenarios. Specify a realistic workload, arrival rate, duration and warm-up, then monitor throughput, errors, p95 and p99 alongside CPU and database waits. Use a dedicated environment; a load test is not a focused race-condition test.

1. To test the last item, seed stock = 1 in a real database.
2. Use an independent DbContext per buyer and coordinate starts with a signal or suitable barrier.
3. Run both attempts and assert exactly one success, nonnegative stock and an expected loser outcome.
4. Repeat with varied scheduling and test retries and idempotency. Repetition increases confidence but cannot prove every interleaving.