Tdd Workflow

Create ONE minimal test demonstrating required behavior.

Quality Standards:

• Single responsibility (one assertion focus)
• Descriptive naming that clarifies intent
• Tests actual implementation, not mocks when possible

// Example: Testing retry logic
test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };

  const result = await retryOperation(operation);

  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

2. VERIFY RED: Confirm Failure

Must verify:

• Test FAILS (not errors)
• Failure message reflects missing feature
• Failure is expected

⚠️ If test passes immediately → You're testing existing code. Revise the test.

3. GREEN: Minimal Implementation

Write the simplest code that makes the test pass.

DO NOT:

• Over-engineer
• Add untested features
• Refactor beyond scope

// Minimal implementation for the test above
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

4. VERIFY GREEN: Confirm Success

Must verify:

• Target test passes
• ALL existing tests pass
• No errors or warnings

⚠️ If tests fail → Fix CODE, never the test.

5. REFACTOR: Improve Without Changing Behavior

• Remove duplication
• Improve naming
• Extract helper functions

Keep tests GREEN throughout refactoring.

Bug Fix Protocol

NEVER fix a bug without writing a failing test first.

// Scenario: Empty email incorrectly accepted

// 1. RED: Write failing test
test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

// 2. VERIFY RED: Run test, confirm it fails

// 3. GREEN: Minimal fix
function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // existing logic
}

// 4. VERIFY GREEN: All tests pass

Common Rationalizations (And Why They're Wrong)

Red Flags: DELETE Code and Restart

Stop immediately and restart if:

• Code written BEFORE tests
• Tests pass immediately upon writing
• Unable to articulate why test initially failed
• Using "keep as reference" justifications
• Claiming "spirit over ritual" approach
• Making fixes without understanding root cause

Completion Checklist

Before marking task complete:

• Each function/method has corresponding test
• Observed each test FAIL before implementation
• Failures occurred due to missing features, not typos
• Code written minimally to pass tests
• All tests passing with clean output
• Real code tested (mocks limited to unavoidable cases)
• Edge cases and error scenarios covered

Incomplete checklist = TDD process was skipped → RESTART

Integration with Project

Running Tests

# Frontend (Next.js)
cd frontend && npm test

# Backend (Python)
cd backend && pytest

# Watch mode
npm test -- --watch
pytest --watch

Test File Locations

Quick Reference Card

┌─────────────────────────────────────────┐
│           TDD CYCLE                     │
├─────────────────────────────────────────┤
│  1. RED    → Write failing test         │
│  2. VERIFY → Confirm it fails           │
│  3. GREEN  → Minimal code to pass       │
│  4. VERIFY → Confirm all tests pass     │
│  5. REFACTOR → Improve, keep green      │
├─────────────────────────────────────────┤
│  ⚠️ NO CODE WITHOUT FAILING TEST FIRST  │
│  ⚠️ NO FIX WITHOUT UNDERSTANDING ROOT   │
│  ⚠️ NO SKIP "JUST THIS ONCE"            │
└─────────────────────────────────────────┘