Tdd

/tdd -- Red-Green-Refactor for .NET

What

Guides a strict test-driven development cycle for .NET features. Instead of writing implementation first and bolting on tests after, this command flips the order: write a failing test that defines the desired behavior, implement the minimum code to make it pass, then refactor with confidence.

Every cycle uses the .NET testing stack:

• xUnit v3 -- Test framework with [Fact] and [Theory]
• WebApplicationFactory -- Integration tests against the real HTTP pipeline
• Testcontainers -- Real databases (PostgreSQL, SQL Server) in tests
• Verify -- Snapshot testing for complex response structures
• FakeTimeProvider -- Deterministic time in tests

When

• User says "TDD", "test-driven", "let's TDD this", "write the test first"
• Building a new feature with clear acceptance criteria
• Fixing a bug (write a test that reproduces the bug first, then fix)
• Adding behavior to an existing feature (test the new behavior first)
• Any time the user wants proof that code works before it ships

Skip TDD for: Trivial config changes, scaffolding without logic, documentation.

How

Cycle: Red -> Green -> Refactor

Each feature goes through one or more TDD cycles. A cycle covers one discrete behavior.

Step 1: Red -- Write the Failing Test

Write a test that describes the desired behavior. The test MUST fail because the implementation does not exist yet.

[Fact]public async Task CreateOrder_WithValidItems_Returns201WithOrderId(){    // Arrange    var client = _factory.CreateClient();    var request = new CreateOrderRequest([        new OrderItemRequest("SKU-001", 2, 29.99m)    ]);
    // Act    var response = await client.PostAsJsonAsync("/api/orders", request);
    // Assert — plain xUnit Assert (FluentAssertions v8+ requires a commercial license)    Assert.Equal(HttpStatusCode.Created, response.StatusCode);    var result = await response.Content.ReadFromJsonAsync<CreateOrderResponse>();    Assert.NotNull(result);    Assert.NotEqual(Guid.Empty, result.OrderId);}

Run the test and confirm it fails:

dotnet test --filter "CreateOrder_WithValidItems_Returns201WithOrderId"

If the test passes without implementation, the test is not testing what you think. Rewrite it.

Step 2: Green -- Minimal Implementation

Write the minimum code to make the test pass. Do not add features, optimizations, or edge case handling. The goal is a green test, nothing more.

• Create the endpoint, handler, request/response types, and EF config as needed
• Use the simplest logic that satisfies the test assertion
• Do not refactor yet -- ugly passing code is fine at this stage

Run the test and confirm it passes:

dotnet test --filter "CreateOrder_WithValidItems_Returns201WithOrderId"

Step 3: Refactor -- Clean Up with Confidence

Now that the test is green, refactor freely:

• Extract methods, rename variables, improve structure
• Apply modern C# patterns (primary constructors, records, collection expressions)
• Add validation, error handling, and edge cases (with new tests for each)
• Run the full test suite after each refactor step to catch regressions

dotnet test

If any test goes red during refactoring, undo the last change and try a smaller step.

Multi-Cycle Features

Most features require multiple TDD cycles. Plan the cycles upfront:

Feature: Order Management
Cycle 1: Create order with valid items -> 201Cycle 2: Create order with empty items -> 400 validation errorCycle 3: Create order with invalid SKU -> 400 with specific errorCycle 4: Get order by ID -> 200 with full order detailsCycle 5: Get order that does not exist -> 404

Each cycle adds one behavior. Never combine multiple behaviors in a single cycle.

Test Infrastructure Setup

If the project lacks test infrastructure, set it up before the first cycle:

1. Create test project with xUnit v3 and required packages
2. Configure WebApplicationFactory with Testcontainers for the real database
3. Add a shared fixture to avoid spinning up containers per test class
4. Verify the infrastructure with a simple health-check test

Example

User: /tdd Let's TDD a product search endpoint
Claude: I'll plan the TDD cycles for product search:
Cycle 1: Search with matching term returns matching productsCycle 2: Search with no matches returns empty listCycle 3: Search with pagination returns correct pageCycle 4: Search with filters narrows results
Starting Cycle 1: Red phaseWriting a failing integration test for basic product search...
[writes test, runs it, confirms failure]
Cycle 1: Green phaseImplementing the minimum to make the search test pass...
[implements, runs test, confirms pass]
Cycle 1: Refactor phaseThe implementation works but the query could use a projectioninstead of loading full entities. Refactoring...
[refactors, runs full suite, all green]
Cycle 1 complete. Moving to Cycle 2...

Related

• /verify -- Run full verification after completing all TDD cycles
• /scaffold -- Generate initial feature structure that tests will drive