dotnet-testing

.NET Testing Standards

.NET-specific testing practices. For universal testability principles, see engineering-principles.mdc. For test strategy (what to test at each layer), see dotnet-architecture.mdc.

Conflict resolution: Where this file provides .NET-specific guidance that differs from engineering-principles.mdc, this file takes precedence for .cs and .csproj files.

---

Test naming

Use the MethodName_StateUnderTest_ExpectedBehaviour format for unit tests and Given_When_Then for scenario-based integration tests:

// Unit test — method under test is explicit
[Fact]
public async Task PlaceOrder_WhenCustomerHasInsufficientCredit_ReturnsFailure() { }

// Integration test — scenario is explicit
[Fact]
public async Task GivenAuthenticatedUser_WhenPlacingOrderWithInvalidLines_ThenReturnsBadRequest() { }

• Test class name matches the subject under test: OrderServiceTests, PlaceOrderCommandHandlerTests
• Do not use Test suffix on test project folders; use MyApp.Application.Tests

---

Project structure

tests/
├── MyApp.Domain.Tests/          ← entity and value object behaviour
├── MyApp.Application.Tests/     ← handler, validator, pipeline behaviour
├── MyApp.Infrastructure.Tests/  ← EF Core, HTTP clients, adapters
└── MyApp.Api.Tests/             ← full request/response via WebApplicationFactory

Each test project references only the layer it tests; it does not skip layers.

---

Unit tests — handlers and domain

• Use xUnit with FluentAssertions; avoid raw Assert.* calls
• No infrastructure dependencies; stub with NSubstitute or Moq
• Arrange/Act/Assert sections separated by a blank line; no inline comments labelling them

[Fact]
public async Task Handle_WhenOrderNotFound_ReturnsFailure()
{
    var repository = Substitute.For<IOrderRepository>();
    repository.GetByIdAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
              .Returns((Order?)null);

    var handler = new GetOrderByIdQueryHandler(repository);
    var result = await handler.Handle(new GetOrderByIdQuery(Guid.NewGuid()), default);

    result.IsFailure.Should().BeTrue();
    result.Error.Should().Contain("not found");
}