tdd-workflow

TDD Workflow — .NET / Verendar

The Cycle

RED → GREEN → REFACTOR — always in that order. Never write implementation before a failing test exists.

Step 1: Define the Behaviour (User Story)

As a [role], I want to [action], so that [benefit].

Example:
As a user, I want to cancel a booking,
so that I can get a refund if my plans change.

Step 2: Write Failing Tests (RED)

// Verendar.Garage.Tests/Services/BookingServiceTests.cs
[Fact]
public async Task CancelAsync_PendingBooking_PublishesCancelledEvent()
{
    // Arrange
    var booking = BookingFaker.Pending();
    _bookingRepo.FindByIdAsync(booking.Id).Returns(booking);

    // Act
    var result = await _sut.CancelAsync(booking.Id, booking.UserId, CancellationToken.None);

    // Assert
    result.IsSuccess.Should().BeTrue();
    await _publishEndpoint.Received(1)
        .Publish(Arg.Any<BookingCancelledEvent>(), Arg.Any<CancellationToken>());
}

[Fact]
public async Task CancelAsync_AlreadyCancelled_ReturnsFailure()
{
    var booking = BookingFaker.Cancelled();
    _bookingRepo.FindByIdAsync(booking.Id).Returns(booking);

    var result = await _sut.CancelAsync(booking.Id, booking.UserId, CancellationToken.None);

    result.IsSuccess.Should().BeFalse();
}

Run: task test PROJECT=Garage/Verendar.Garage.Tests → tests must fail.

Step 3: Implement Minimally (GREEN)

Write the least code needed to make the tests pass. No extras.

Step 4: Refactor

Clean up while keeping all tests green. Only after GREEN.

Step 5: Verify Coverage

task test:all
dotnet test --collect:"XPlat Code Coverage"

Minimum 80% overall. 100% for payment and auth logic.

Test Types

Unit Test Setup

public class BookingServiceTests
{
    private readonly IUnitOfWork _uow = Substitute.For<IUnitOfWork>();
    private readonly IPublishEndpoint _pub = Substitute.For<IPublishEndpoint>();
    private readonly BookingService _sut;

    public BookingServiceTests()
    {
        _uow.Bookings.Returns(Substitute.For<IBookingRepository>());
        _sut = new BookingService(_uow, _pub, NullLogger<BookingService>.Instance);
    }
}

Integration Test Setup

public class BookingApiTests(GarageWebFactory factory) : IClassFixture<GarageWebFactory>
{
    private readonly HttpClient _client = factory.CreateClient();

    [Fact]
    public async Task POST_Cancel_Returns200()
    {
        _client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", factory.GenerateUserToken(Guid.NewGuid()));

        var response = await _client.PostAsync($"/api/bookings/{bookingId}/cancel", null);

        response.StatusCode.Should().Be(HttpStatusCode.OK);
    }
}

See references/dotnet-patterns.md for the full GarageWebFactory with Testcontainers setup.

Anti-Patterns

Run Commands

task test:all                                         # all tests
task test PROJECT=Garage/Verendar.Garage.Tests        # single project
dotnet test --filter "FullyQualifiedName~CancelAsync" # single test