tdd-guide

TDD Guide

Enforces Red-Green-Refactor discipline across all four stacks. Every feature starts with a failing test.

Iron Law: Write the failing test FIRST. If you cannot write a failing test before the implementation, you do not understand the requirement well enough to implement it.

Red-Green-Refactor Cycle

RED   → Write a failing test that describes the desired behavior
GREEN → Write the minimum code to make it pass (no more)
REFACTOR → Clean up — same behavior, better structure (tests still pass)

Never skip RED. "I'll add tests after" is how coverage gaps form.

Stack-Specific Test Runners

Spring Boot (Java 21 / JUnit 5 / WebFlux)

# Run single test
./mvnw test -Dtest=UserServiceTest -q

# Run all tests + coverage
./mvnw test jacoco:report -q

# Watch mode (rerun on change)
./mvnw test -Dtest=UserServiceTest --no-transfer-progress -Dsurefire.rerunFailingTestsCount=0

// WebFlux reactive test pattern (NOT MockMvc)
@WebFluxTest(UserController.class)
class UserControllerTest {
    @Autowired WebTestClient webTestClient;
    @MockBean UserService userService;

    @Test
    void createUser_returnsCreated() {
        when(userService.create(any())).thenReturn(Mono.just(savedUser));

        webTestClient.post().uri("/users")
            .bodyValue(createRequest)
            .exchange()
            .expectStatus().isCreated()
            .expectBody(UserResponse.class)
            .value(u -> assertThat(u.id()).isNotNull());
    }
}

Python (pytest / FastAPI)

# Run with coverage
pytest --cov=src --cov-report=term-missing -q

# Run single test file
pytest tests/test_user_service.py -v

# Run tests matching name pattern
pytest -k "test_create" -v

# FastAPI async test pattern
@pytest.mark.asyncio
async def test_create_user_returns_201(client: AsyncClient):
    response = await client.post("/users", json={"name": "Alice", "email": "[email protected]"})
    assert response.status_code == 201
    assert response.json()["id"] is not None