tdd-workflow

TDD Workflow

Quality Gate Thresholds (ENFORCED)

Gate	Threshold	Status
Compile	0 errors	REQUIRED
Tests	100% pass (0 failures)	REQUIRED
Coverage	≥ 80% line coverage	REQUIRED
Checkstyle	0 violations	REQUIRED (if configured)

⛔ BLOCKING: TDD workflow is NOT complete until ALL gates pass.

Step 0: Verify Coverage Configuration ⚠️ PREREQUISITE

Before starting ANY TDD cycle, verify JaCoCo is configured:

grep -l "jacoco-maven-plugin" pom.xml

If NOT configured, add it FIRST to pom.xml:

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.11</version>
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals><goal>report</goal></goals>
        </execution>
        <execution>
            <id>check</id>
            <phase>verify</phase>
            <goals><goal>check</goal></goals>
            <configuration>
                <rules>
                    <rule>
                        <element>BUNDLE</element>
                        <limits>
                            <limit>
                                <counter>LINE</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.80</minimum>
                            </limit>
                        </limits>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

⛔ Do NOT start TDD without coverage configuration in place.

The Red-Green-Refactor Cycle

    ┌──────────────────┐
    │       RED        │
    │  Write a failing │
    │      test        │
    └────────┬─────────┘
             │
             ▼
    ┌──────────────────┐
    │      GREEN       │
    │  Write minimal   │
    │  code to pass    │
    └────────┬─────────┘
             │
             ▼
    ┌──────────────────┐
    │    REFACTOR      │
    │  Improve code    │
    │  keeping green   │
    └────────┬─────────┘
             │
             └─────────────────┐
                               │
             Repeat for        ▼
             next behavior  ◄──┘

Step-by-Step Process

RED Phase: Write a Failing Test

1. Write ONE test for ONE behavior
2. Run it — confirm it FAILS
3. The failure message should describe what's missing

@Test
void should_createTodo_whenValidRequest() {
    // Given
    CreateTodoRequest request = new CreateTodoRequest("New Todo");

    // When
    TodoResponse response = todoService.create(request);

    // Then
    assertThat(response.id()).isNotNull();
    assertThat(response.title()).isEqualTo("New Todo");
    assertThat(response.completed()).isFalse();
}

Run: mvn test -Dtest=TodoServiceTest#should_createTodo_whenValidRequest

Expected output: FAIL (method doesn't exist yet)

GREEN Phase: Write Minimal Code to Pass

1. Write the SIMPLEST code that makes the test pass
2. Don't add extra features
3. Don't optimize yet
4. Just make it work

public TodoResponse create(CreateTodoRequest request) {
    Todo todo = new Todo();
    todo.setTitle(request.title());
    todo.setCompleted(false);
    todo.setCreatedAt(Instant.now());
    Todo saved = todoRepository.save(todo);
    return new TodoResponse(
        saved.getId(),
        saved.getTitle(),
        saved.isCompleted(),
        saved.getCreatedAt()
    );
}

Run: mvn test -Dtest=TodoServiceTest#should_createTodo_whenValidRequest

Expected output: PASS

REFACTOR Phase: Improve While Green

1. Clean up code (extract methods, improve names)
2. Run tests after EACH change
3. If any test fails, undo last change
4. Tests must stay GREEN throughout

// REFACTOR: Extract mapping to private method
public TodoResponse create(CreateTodoRequest request) {
    Todo todo = buildTodoFromRequest(request);
    Todo saved = todoRepository.save(todo);
    return toResponse(saved);
}

private Todo buildTodoFromRequest(CreateTodoRequest request) {
    Todo todo = new Todo();
    todo.setTitle(request.title());
    todo.setCompleted(false);
    todo.setCreatedAt(Instant.now());
    return todo;
}

private TodoResponse toResponse(Todo todo) {
    return new TodoResponse(
        todo.getId(),
        todo.getTitle(),
        todo.isCompleted(),
        todo.getCreatedAt()
    );
}

Run: mvn test (all tests)

Expected output: ALL PASS

Error Recovery Protocol

When a Test Fails Unexpectedly

ATTEMPT 1:
  - Read error message carefully
  - Identify likely cause
  - Make targeted fix
  - Run test

ATTEMPT 2 (if still failing):
  - Read FULL stack trace
  - Check related code (imports, dependencies)
  - Make targeted fix
  - Run test

ATTEMPT 3 (if still failing):
  - Use diagnostic commands (grep, read configs)
  - Check error→fix patterns in verification skill
  - Make targeted fix
  - Run test

AFTER 3 ATTEMPTS:
  - STOP
  - Summarize what you've tried
  - Ask developer for guidance

Max Retry Rule

Do NOT:

• Keep trying the same fix repeatedly
• Try random fixes without diagnosis
• Skip the failing test
• Comment out assertions
• Lower quality thresholds

DO:

• Diagnose before each fix attempt
• Try DIFFERENT approaches each time
• Document what you've tried
• Ask for help after 3 attempts

Test Types: When to Write What

Unit Tests (MOST tests - 70%)

When: Testing individual methods/classes in isolation Tool: JUnit 5 + Mockito Speed: Milliseconds Example: Service method logic

@ExtendWith(MockitoExtension.class)
class TodoServiceTest {
    @Mock TodoRepository repository;
    @InjectMocks TodoService service;

    @Test
    void should_returnTodo_whenExists() {
        when(repository.findById(1L)).thenReturn(Optional.of(todo));
        TodoResponse result = service.findById(1L);
        assertThat(result.title()).isEqualTo("Test");
    }
}

Slice Tests (Controller/Repository - 20%)

When: Testing Spring components with partial context Tool: @WebMvcTest, @DataJdbcTest Speed: 1-2 seconds Example: Controller HTTP handling, Repository queries

@WebMvcTest(TodoController.class)
class TodoControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean TodoService service;

    @Test
    void should_return200_whenGetAll() throws Exception {
        mockMvc.perform(get("/api/v1/todos"))
            .andExpect(status().isOk());
    }
}

Integration Tests (FEW tests - 10%)

When: Testing full request flow with real dependencies Tool: @SpringBootTest + Testcontainers Speed: 5-10 seconds Example: Full create→retrieve flow

@SpringBootTest(webEnvironment = RANDOM_PORT)
@Testcontainers
class TodoIntegrationTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");

    @Test
    void should_createAndRetrieveTodo() {
        // Full flow with real DB
    }
}

Test Pyramid

        /\
       /  \      Integration (10%)
      /────\     - Slow, expensive
     /      \    - Test critical flows
    /────────\
   /          \   Slice Tests (20%)
  /   ─────    \  - Controller, Repository
 /              \ - Medium speed
/────────────────\
       Unit (70%)
    - Fast, focused
    - Test all logic

Test Coverage Guidelines

Layer	Target	What to Test
Service	80%+	All business logic, edge cases, error paths
Controller	All endpoints	Happy path, validation errors, not found
Repository	Custom queries	Complex queries, edge cases
DTOs	Validation	All validation rules

Coverage Verification ⚠️ MANDATORY

Before declaring any implementation complete, you MUST verify coverage:

# Generate coverage report
mvn test jacoco:report

# Check coverage in browser
open target/site/jacoco/index.html

Coverage Thresholds (REQUIRED)

Metric	Minimum	Action if Below
Line Coverage	80%	Add more tests
Branch Coverage	75%	Test if/else paths
Method Coverage	80%	Test all public methods

Coverage Verification Steps

1. Run coverage report:

   mvn test jacoco:report
   

2. Check percentage:

   • Open target/site/jacoco/index.html
   • Or parse target/site/jacoco/jacoco.xml

3. If below 80%:

   • Identify red (uncovered) lines in report
   • Add tests for those code paths
   • Re-run coverage
   • Repeat until ≥ 80%

4. Only then declare done

⛔ NEVER mark complete with coverage < 80%

A pre-completion hook enforces this requirement automatically.

What NOT to Test

• Getters/setters with no logic
• Framework code (Spring does this)
• Third-party libraries
• Trivial constructors
• Private methods directly (test via public API)

Test Quality Checklist

For each test:

• Clear name describing behavior: should_X_whenY()
• Follows Given-When-Then structure
• Tests ONE behavior
• Independent of other tests
• Deterministic (no random, no time-dependent)
• Fast (unit < 100ms, slice < 2s, integration < 10s)
• Meaningful assertions (not just "no exception")

Common TDD Mistakes

Mistake 1: Writing Tests After Code

❌ Write code → Write tests → Hope they pass
✓ Write test → See it fail → Write code → See it pass

Mistake 2: Testing Implementation, Not Behavior

// ❌ Testing implementation details
verify(repository).save(any());
assertThat(service.getCache().size()).isEqualTo(1);

// ✓ Testing observable behavior
assertThat(result.id()).isNotNull();
assertThat(service.findById(id)).isEqualTo(expected);

Mistake 3: Too Many Assertions Per Test

// ❌ Testing multiple behaviors
@Test void testTodoOperations() {
    // create, update, delete, find all in one test
}

// ✓ One behavior per test
@Test void should_createTodo_whenValidRequest() { }
@Test void should_updateTodo_whenExists() { }
@Test void should_deleteTodo_whenExists() { }

Mistake 4: Not Running Tests Frequently

❌ Write 500 lines → Run tests → 47 failures
✓ Write test → Run → Write code → Run → Refactor → Run