.NET Testing Patterns

Reference for writing and reviewing tests.

Test Organization

tests/
├── MyApp.UnitTests/           # Fast, isolated, mock dependencies
│   ├── Services/
│   │   └── UserServiceTests.cs
│   └── Domain/
│       └── UserTests.cs
├── MyApp.IntegrationTests/    # Slower, real dependencies
│   ├── Api/
│   │   └── UserEndpointTests.cs
│   └── Infrastructure/
│       └── UserRepositoryTests.cs
└── MyApp.ArchitectureTests/   # Optional: enforce architecture rules
    └── LayerDependencyTests.cs

xUnit Patterns

Test Class Setup

public class UserServiceTests
{
    private readonly IUserRepository _repo = Substitute.For<IUserRepository>();
    private readonly UserService _sut; // system under test

    public UserServiceTests()
    {
        _sut = new UserService(_repo);
    }

    [Fact]
    public async Task GetByIdAsync_WhenUserExists_ReturnsUser()
    {
        var user = new User(Guid.NewGuid(), "test@example.com");
        _repo.GetByIdAsync(user.Id, Arg.Any<CancellationToken>()).Returns(user);

        var result = await _sut.GetByIdAsync(user.Id, CancellationToken.None);

        result.Should().Be(user);
    }
}

Naming Convention

MethodName_StateUnderTest_ExpectedBehavior

[Fact]
public async Task GetByIdAsync_WhenUserExists_ReturnsUser() { }

[Fact]
public async Task GetByIdAsync_WhenUserNotFound_ReturnsNull() { }

[Theory]
[InlineData("")]
[InlineData(null)]
public async Task CreateAsync_WithInvalidEmail_ReturnsValidationError(string? email) { }

IClassFixture for Shared Setup

public class DatabaseTests : IClassFixture<DatabaseFixture>
{
    private readonly DatabaseFixture _fixture;
    public DatabaseTests(DatabaseFixture fixture) => _fixture = fixture;
}

Integration Tests with WebApplicationFactory

The factory swaps the app's database for one running in a Testcontainers container (Testcontainers.MsSql; Testcontainers.PostgreSql for Npgsql), so tests run against the same provider as production. Docker must be available where the tests run.

public sealed class ApiFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    // The parameterless MsSqlBuilder() is obsolete in Testcontainers 4.x; pin the image explicitly.
    private readonly MsSqlContainer _db =
        new MsSqlBuilder("mcr.microsoft.com/mssql/server:2022-CU14-ubuntu-22.04").Build();

    public Task InitializeAsync() => _db.StartAsync();

    async Task IAsyncLifetime.DisposeAsync()
    {
        await _db.DisposeAsync();
        await base.DisposeAsync();
    }

    protected override void ConfigureWebHost(IWebHostBuilder builder) =>
        builder.ConfigureTestServices(services =>
        {
            // EF Core 9+ also registers the original UseSqlServer(...) callback as an
            // IDbContextOptionsConfiguration<T>; leaving it in re-applies the production connection.
            services.RemoveAll<DbContextOptions<ApplicationDbContext>>();
            services.RemoveAll<IDbContextOptionsConfiguration<ApplicationDbContext>>();
            services.AddDbContext<ApplicationDbContext>(options =>
                options.UseSqlServer(_db.GetConnectionString()));
        });
}

public class UserEndpointTests : IClassFixture<ApiFactory>
{
    private readonly HttpClient _client;

    public UserEndpointTests(ApiFactory factory) => _client = factory.CreateClient();

    [Fact]
    public async Task CreateUser_Returns201WithLocation()
    {
        var request = new { Name = "Test", Email = "test@example.com" };
        var response = await _client.PostAsJsonAsync("/api/users", request);

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

Under xUnit v2 IAsyncLifetime.DisposeAsync returns Task, so the explicit implementation above keeps it apart from WebApplicationFactory.DisposeAsync() (ValueTask). xUnit v3 unifies both on ValueTask and the explicit form is no longer needed.

Controlling Time

Code that takes TimeProvider (never DateTime.UtcNow) is tested with FakeTimeProvider from Microsoft.Extensions.TimeProvider.Testing — no mock needed:

[Fact]
public void Expire_AfterTtl_MarksSessionExpired()
{
    var time = new FakeTimeProvider(new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero));
    var session = Session.Start(time, ttl: TimeSpan.FromMinutes(30));

    time.Advance(TimeSpan.FromMinutes(31));

    session.IsExpired(time).Should().BeTrue();
}

In a WebApplicationFactory, swap it in ConfigureTestServices: services.RemoveAll<TimeProvider>(); services.AddSingleton<TimeProvider>(time);. Advance also fires timers and Task.Delay(…, time) calls created from the fake provider.

Mocking Libraries

NSubstitute is the default for new test projects. When the solution already uses another library, mirror it — the same behavior in each:

Test Data

AutoFixture (recommended for complex objects)

var fixture = new Fixture();
var user = fixture.Create<User>();

Builder Pattern (for domain-specific)

var user = new UserBuilder().WithEmail("test@example.com").Build();

Examples here use NSubstitute and FluentAssertions. Read the test project's .csproj and mirror whatever it already references — a second mocking or assertion library in one solution is debt. For a new project: FluentAssertions 7.x (pin [7,8) — v8+ needs a commercial licence) or Shouldly.

Choosing a Tier

Confidence per test is not uniform. An integration test through WebApplicationFactory exercises real DI, middleware, and routing; a unit test proves one method handles one case. Prefer the highest tier that is still fast and deterministic for the behavior in question.

Mocks

A test that only asserts on its mocks proves nothing. Litmus: delete every Verify(), Received(), and MustHaveHappened() call. If nothing is left that would fail when the implementation breaks, the test is measuring its own setup.

Preference order:

1. Real, if it is controllable and fast — TestServer, IMemoryCache, a real filesystem with IDisposable cleanup.
2. A container — Testcontainers for SQL Server, Redis, RabbitMQ. Slower, but the behavior is the behavior.
3. A mock — only when the dependency is non-deterministic, costly (a paid API), or slow.

A mock is a claim about a contract, so verify the claim before writing it: read the real signature (mcp__roslyn__get_class_outline) for return types and nullability, and read the implementation for the values it actually returns. A mock returning "PENDING" where the real code returns OrderStatus.Pending hides the bug it was supposed to expose.

Boundary Coverage

Every boundary the feature crosses wants at least one test with the real implementation behind it. Mock-only coverage at a boundary means nothing has proven the integration works.