faysilalshareef/unit-testing

Unit Testing — xUnit, Mocking, Assertions

Core Principles

• Follow Arrange-Act-Assert (AAA) pattern in every test
• Test naming: {MethodName}_When{Condition}_Should{Expected}
• One assertion per test (or closely related assertions)
• Use NSubstitute (preferred) or Moq for mocking dependencies
• FluentAssertions for readable, expressive assertions
• Test behavior, not implementation details

Key Patterns

Basic Test Structure

namespace {Company}.{Domain}.Tests.Unit;

public sealed class OrderServiceTests
{
    private readonly IOrderRepository _repository = Substitute.For<IOrderRepository>();
    private readonly IUnitOfWork _unitOfWork = Substitute.For<IUnitOfWork>();
    private readonly OrderService _sut;

    public OrderServiceTests()
    {
        _sut = new OrderService(_repository, _unitOfWork);
    }

    [Fact]
    public async Task GetOrderAsync_WhenOrderExists_ShouldReturnOrder()
    {
        // Arrange
        var orderId = Guid.NewGuid();
        var expected = new Order { Id = orderId, CustomerName = "Test" };
        _repository.FindAsync(orderId, Arg.Any<CancellationToken>())
            .Returns(expected);

        // Act
        var result = await _sut.GetOrderAsync(orderId);

        // Assert
        result.Should().NotBeNull();
        result!.CustomerName.Should().Be("Test");
    }

    [Fact]
    public async Task GetOrderAsync_WhenOrderNotFound_ShouldReturnNull()
    {
        // Arrange
        _repository.FindAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
            .Returns((Order?)null);

        // Act
        var result = await _sut.GetOrderAsync(Guid.NewGuid());

        // Assert
        result.Should().BeNull();
    }
}

Testing MediatR Handlers

public sealed class CreateOrderHandlerTests
{
    private readonly ICommitEventService<OrderEventData> _commitService =
        Substitute.For<ICommitEventService<OrderEventData>>();
    private readonly CreateOrderHandler _sut;

    public CreateOrderHandlerTests()
    {
        _sut = new CreateOrderHandler(_commitService);
    }

    [Fact]
    public async Task Handle_ShouldCreateOrderAndCommitEvents()
    {
        // Arrange
        var command = new CreateOrderCommand("Test Customer", 100m, []);

        // Act
        var result = await _sut.Handle(command, CancellationToken.None);

        // Assert
        result.Id.Should().NotBeEmpty();
        result.Sequence.Should().Be(1);

        await _commitService.Received(1).CommitAsync(
            Arg.Any<Guid>(),
            Arg.Is<IReadOnlyList<Event<OrderEventData>>>(events =>
                events.Count == 1),
            Arg.Any<CancellationToken>());
    }
}

FluentAssertions Patterns

// Collection assertions
orders.Should().HaveCount(3);
orders.Should().Contain(o => o.CustomerName == "Test");
orders.Should().BeInDescendingOrder(o => o.Total);
orders.Should().AllSatisfy(o => o.Status.Should().Be(OrderStatus.Active));

// Object assertions
order.Should().BeEquivalentTo(expected, options =>
    options.Excluding(o => o.RowVersion));

// Exception assertions
var act = () => order.Complete();
act.Should().Throw<InvalidOperationException>()
    .WithMessage("*already completed*");

// Async exception assertions
var act = async () => await handler.Handle(command, CancellationToken.None);
await act.Should().ThrowAsync<OrderNotFoundException>();

Parameterized Tests

[Theory]
[InlineData("", false)]
[InlineData("Valid Name", true)]
[InlineData(null, false)]
public void Validate_CustomerName_ShouldReturnExpectedResult(
    string? name, bool expectedValid)
{
    // Arrange
    var validator = new CreateOrderValidator();
    var command = new CreateOrderCommand(name!, 100m, []);

    // Act
    var result = validator.Validate(command);

    // Assert
    result.IsValid.Should().Be(expectedValid);
}

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Testing private methods directly | Test through public API | | Multiple unrelated assertions | One logical assertion per test | | Brittle mock verification order | Verify behavior, not call sequence | | Test names like Test1, TestCreate | Descriptive: MethodName_When_Should | | Sharing mutable state between tests | Fresh instances per test (constructor) |

Detect Existing Patterns

# Find test projects
find . -name "*Tests*.csproj" -type f

# Find xUnit usage
grep -r "\[Fact\]\|\[Theory\]" --include="*.cs" tests/

# Find mocking framework
grep -r "Substitute.For\|Mock<\|new Mock" --include="*.cs" tests/

# Find FluentAssertions
grep -r "\.Should()" --include="*.cs" tests/

Adding to Existing Project

1. Match the existing mocking framework — NSubstitute or Moq (don't mix)
2. Follow test naming conventions used in existing tests
3. Use FluentAssertions if already in the project
4. Place tests in parallel structure: src/X/ maps to tests/X.Tests/
5. One test class per production class with matching name suffix Tests