Instruction file imported from klod68/littlerae (.github/instructions/tdd.instructions.md). Copyright stays with the author.

--- scope: "tdd" applyTo: "tests/,src//*.cs" priority: "feature"

Test-Driven Development — Standards

Apply these rules for all .NET projects using xUnit. TDD is not optional — it is the workflow. Red → Green → Refactor, in that order.

The Discipline

1. Red — Write a failing test that describes the desired behavior. It must fail for the right reason (not a compile error — a behavioral assertion failure).
2. Green — Write the minimum production code to make the test pass. No more.
3. Refactor — Improve the structure of both test and production code without changing behavior. Run tests after every change.

Test Boundary Matrix

Do NOT test:

• Private methods (tested through public behavior)
• EF Core internal mechanics (trust the framework)
• DI container wiring (tested implicitly via integration tests)
• Framework routing, middleware behavior

Test Project Structure

tests/
├── {Solution}.Tests.Unit/
│   ├── Domain/
│   │   ├── Entities/
│   │   │   └── {EntityName}Tests.cs
│   │   └── ValueObjects/
│   │       └── {ValueObjectName}Tests.cs
│   ├── Application/
│   │   ├── Commands/
│   │   │   └── {CommandName}HandlerTests.cs
│   │   ├── Queries/
│   │   │   └── {QueryName}HandlerTests.cs
│   │   └── Validators/
│   │       └── {CommandName}ValidatorTests.cs
│   └── Builders/              ← Test Data Builders
│       └── {EntityName}Builder.cs
└── {Solution}.Tests.Integration/
    └── Repositories/
        └── {EntityName}RepositoryTests.cs

Naming Convention

Format: {MethodUnderTest}_{Scenario}_{ExpectedResult}

// Correct
[Fact]
public async Task Handle_ValidCommand_ReturnsSuccessResult() { }

[Fact]
public async Task Handle_NullTitle_ReturnsValidationFailure() { }

[Fact]
public async Task GetByIdAsync_ExistingId_ReturnsHydratedEntity() { }

[Fact]
public async Task GetByIdAsync_NonExistentId_ReturnsNull() { }

// Wrong — too vague, no scenario, no expected result
[Fact]
public async Task TestHandle() { }

Unit Test Templates

Domain Entity — Factory Method Tests

public sealed class {EntityName}Tests
{
    public sealed class Create
    {
        [Fact]
        public void Create_ValidInputs_ReturnsSuccessWithPopulatedEntity()
        {
            // Arrange
            const string title = "Valid Title";

            // Act
            var result = {EntityName}.Create(title);

            // Assert
            result.IsSuccess.Should().BeTrue();
            result.Value.Title.Should().Be(title);
            result.Value.Id.Should().NotBe(default);
        }

        [Theory]
        [InlineData("")]
        [InlineData("   ")]
        [InlineData(null)]
        public void Create_EmptyOrNullTitle_ReturnsFailure(string? title)
        {
            // Act
            var result = {EntityName}.Create(title!);

            // Assert
            result.IsFailure.Should().BeTrue();
            result.Error.Code.Should().Be({EntityName}Errors.TitleRequired.Code);
        }
    }
}

Application Handler — Unit Tests (NSubstitute)

public sealed class Create{EntityName}HandlerTests
{
    private readonly I{EntityName}Repository _repository =
        Substitute.For<I{EntityName}Repository>();
    private readonly Create{EntityName}Handler _sut;

    public Create{EntityName}HandlerTests()
    {
        _sut = new Create{EntityName}Handler(_repository);
    }

    [Fact]
    public async Task Handle_ValidCommand_PersistsAndReturnsId()
    {
        // Arrange
        var command = new Create{EntityName}Command("Valid Title");
        _repository
            .AddAsync(Arg.Any<{EntityName}>(), Arg.Any<CancellationToken>())
            .Returns(Task.CompletedTask);

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

        // Assert
        result.IsSuccess.Should().BeTrue();
        result.Value.Should().NotBe(default({EntityId}));
        await _repository
            .Received(1)
            .AddAsync(Arg.Any<{EntityName}>(), Arg.Any<CancellationToken>());
    }

    [Fact]
    public async Task Handle_CancellationRequested_PropagatesCancellation()
    {
        // Arrange
        var cts = new CancellationTokenSource();
        cts.Cancel();
        var command = new Create{EntityName}Command("Valid Title");

        // Act & Assert
        await _sut
            .Invoking(h => h.Handle(command, cts.Token))
            .Should()
            .ThrowAsync<OperationCanceledException>();
    }
}

Integration Test (EF Core InMemory)

public sealed class {EntityName}RepositoryTests : IDisposable
{
    private readonly {DbContextName} _db;
    private readonly EfCore{EntityName}Repository _sut;

    public {EntityName}RepositoryTests()
    {
        var options = new DbContextOptionsBuilder<{DbContextName}>()
            .UseInMemoryDatabase(Guid.NewGuid().ToString()) // unique per test
            .Options;

        _db = new {DbContextName}(options);
        _sut = new EfCore{EntityName}Repository(_db);
    }

    [Fact]
    public async Task GetByIdAsync_ExistingEntity_ReturnsHydratedEntity()
    {
        // Arrange
        var entity = {EntityName}.Create("Test").Value;
        await _sut.AddAsync(entity, CancellationToken.None);
        await _db.SaveChangesAsync();

        // Act
        var retrieved = await _sut.GetByIdAsync(entity.Id, CancellationToken.None);

        // Assert
        retrieved.Should().NotBeNull();
        retrieved!.Id.Should().Be(entity.Id);
    }

    public void Dispose() => _db.Dispose();
}

Coverage Targets

Mandatory Test Scenarios (All Features)

These six scenarios form the minimum viable test surface for any feature. They are not exhaustive — they are the scenarios most likely to catch real defects at the cheapest testing layer. Coverage tools measure lines, not intent; these scenarios measure intent.

Tools Reference

Common Anti-Patterns

See Also

• cqrs.md — CQRS via MediatR, command/query separation, pipeline behaviors
• design-patterns.md — Approved GoF patterns: Factory, Repository, Decorator, Strategy, Specification
• naming.md — Naming conventions for types, methods, properties, namespaces
• eval-driven-development.md — Eval-driven development for AI agent behavior validation
• result-error-handling.md — Result object pattern, error constants, exception boundaries