running-tdd-cycle

Python TDD Workflow

The Cycle

RED → GREEN → REFACTOR → RED → ...

1. RED: Write a failing test
2. GREEN: Write minimal code to pass
3. REFACTOR: Improve structure, keep tests green

Phase Tracking

Always state the current phase before working:

"We're in the RED phase. I'll write a failing test for [feature]."

Ask before transitioning:

"Tests are passing. Ready to move to REFACTOR, or should we add more tests?"

---

RED Phase (Write Failing Tests)

What To Do

1. Write acceptance test scenarios first (outside-in)
2. Create test DSL methods for domain operations
3. Implement test adapters (in-memory ports)
4. Use PyTest and Hypothesis where appropriate

What NOT To Do

• Write production implementation code
• Write passing tests (tests must fail first)
• Over-design the test infrastructure

Example

def test_user_can_rsvp_to_event():
    """Acceptance test - defines expected behavior."""
    app = create_test_app()
    organizer = TestOrganizer(app)
    attendee = TestAttendee(app)

    event = organizer.create_event("Team Meeting")
    attendee.rsvp(event, "yes")

    assert event.attendee_count == 1

Run tests to confirm they fail:

pytest -x  # Stop at first failure

---

GREEN Phase (Make Tests Pass)

What To Do

1. Write the minimal code to make tests pass
2. Follow architecture patterns (functional core, Pydantic, etc.)
3. It's okay if the code is ugly - we'll refactor next

What NOT To Do

• Add features beyond what tests require
• Refactor while getting to green
• Write "clean" code (that's for REFACTOR phase)
• Add error handling for untested cases

Process

1. Run the failing test
2. Write just enough code to pass
3. Run tests again
4. Repeat until green

pytest -x  # Run until first failure
pytest     # All tests pass = ready for REFACTOR

---

REFACTOR Phase (Improve Structure)

What To Do

1. Improve code structure and readability
2. Extract methods, rename for clarity
3. Remove duplication
4. Run tests after EACH change
5. Run the code-reviewer agent to check architecture compliance

What NOT To Do

• Change behavior (tests must stay green)
• Add new features
• Skip running tests between changes

Process

Make small change → Run tests → Green? → Next change
                              → Red? → Undo and try again

When refactoring is complete, spawn the code-reviewer agent to verify the code follows architecture patterns.

---

TDD Implementation Order

When building a new feature:

1. Acceptance test - High-level scenario (fails)
2. DSL methods - Make test readable (still fails)
3. Test adapters - In-memory implementations (still fails)
4. Domain logic - Business rules (GREEN!)
5. Refactor - Clean up
6. Next test - Back to RED

---

Commands

Check current state:

pytest -v           # Verbose output
pytest --tb=short   # Short tracebacks
pytest -x           # Stop at first failure

Run specific test:

pytest tests/test_events.py::test_user_can_rsvp

---

Prompts for Phase Transitions

Starting RED:

"Let's write a failing test for [feature]. What behavior should we test first?"

Moving to GREEN:

"Test is failing as expected. Now I'll write minimal code to make it pass."

Moving to REFACTOR:

"All tests passing. Let's clean up the code. I see we could [improvement]."

Back to RED:

"Refactoring complete. What's the next behavior we should test?"