Tdd Mastery

<domain_overview>

🧪 TDD MASTERY: THE IRON LAW

Philosophy: If you didn't watch the test fail, you don't know if it tests the right thing. TDD is not optional—it's the foundation of trustworthy code.

TEST-FIRST INTEGRITY MANDATE (CRITICAL): Never write production code before a test exists and has been seen failing. AI-generated code often attempts to write implementation and tests simultaneously or implementation first. You MUST strictly adhere to the Red-Green-Refactor cycle. Any code submitted without a preceding failing test or that generates tests after the implementation must be rejected as "Legacy Code on Arrival".

---

🚨 THE IRON LAW

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Implement fresh from tests. Period. </domain_overview> <core_workflow>

🔴 RED-GREEN-REFACTOR CYCLE

Phase 1: RED - Write Failing Test

Write one minimal test showing what should happen.

Good Example:

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);
});

Clear name, tests real behavior, one thing

Bad Example:

test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(2);
});

Vague name, tests mock not code

Requirements:

• One behavior per test
• Clear, descriptive name
• Real code (mocks only if unavoidable)

Phase 2: VERIFY RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts
# or
pytest tests/path/test.py::test_name -v

Confirm:

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

Phase 3: GREEN - Minimal Code

Write simplest code to pass the test.

Good:

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');
}

Just enough to pass

Bad:

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI - You Aren't Gonna Need It
}

Over-engineered

Don't add features, refactor other code, or "improve" beyond the test.

Phase 4: VERIFY GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)

Test fails? Fix code, not test.

Other tests fail? Fix now.

Phase 5: REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Phase 6: COMMIT

git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature with tests"

Repeat for next behavior.

--- </core_workflow>

<quality_standards>

📋 GOOD TEST QUALITIES

---

🚫 COMMON RATIONALIZATIONS (ALL INVALID)

---

🚨 RED FLAGS - STOP AND START OVER

If you catch yourself:

• Writing code before test
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• "Just this once"
• "I already manually tested it"
• "Keep as reference"
• "TDD is dogmatic, I'm being pragmatic"

ALL of these mean: Delete code. Start over with TDD.

--- </quality_standards>

<bug_fix_protocol>

🐛 BUG FIX WORKFLOW

Bug found? Write failing test reproducing it. Follow TDD cycle.

Example:

Bug: Empty email accepted

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

VERIFY RED:
$ npm test
FAIL: expected 'Email required', got undefined

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

VERIFY GREEN:
$ npm test
PASS

Never fix bugs without a test.

--- </bug_fix_protocol>

<integration_and_tooling>

🔗 RALPH WIGGUM INTEGRATION

When Ralph Wiggum is active:

1. Before ANY implementation: Write failing test first 2. Proactive Gate: Check edge cases BEFORE coding (use TDD to cover them) 3. Reflection Loop: After implementation, verify RED-GREEN was followed 4. Verification Matrix: Track test coverage for each feature

Ralph Wiggum will REJECT:

• Code without corresponding tests
• Tests that were written after code
• Tests that pass without implementation

---

✅ VERIFICATION CHECKLIST

Before marking work complete:

• [ ] Every new function/method has a test
• [ ] Watched each test fail before implementing
• [ ] Each test failed for expected reason (feature missing, not typo)
• [ ] Wrote minimal code to pass each test
• [ ] All tests pass
• [ ] Output pristine (no errors, warnings)
• [ ] Tests use real code (mocks only if unavoidable)
• [ ] Edge cases and errors covered

Can't check all boxes? You skipped TDD. Start over.

---

🛠️ TESTING INFRASTRUCTURE

Stack Detection & Tool Setup

Auto-detect project type and setup appropriate tools:

Test Coverage Rules

For every new function/component, generate:

• 1 Happy Path - Expected successful behavior
• 2 Edge Cases - Boundary conditions, invalid inputs
• 1 Error Case - Expected failure handling

Contract-First (MSW)

Rule: Every frontend-backend interaction MUST have an MSW handler.

// Example MSW handler
import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      name: 'Test User'
    })
  })
]

Benefit: Decouples frontend development from backend availability.

Ghost Inspector Protocol

AI must scan for "Untested Logic Slabs" (>20 lines without coverage) and flag them:

# Check coverage gaps
npm run test -- --coverage
# Look for files with <80% coverage

--- </integration_and_tooling>

<reference_and_audit>

📖 RELATED SKILLS

• @testing-anti-patterns.md - Common mock/test mistakes to avoid
• @clean-code - Code quality standards
• @verification-mastery - Evidence before completion claims
• @debug-mastery - When tests reveal bugs

---

🏁 FINAL RULE

Production code → test exists and failed first
Otherwise → not TDD

No exceptions without explicit user permission. </reference_and_audit>

Testing Anti-Patterns

Load this reference when: writing or changing tests, adding mocks, or tempted to add test-only methods to production code.

Overview

Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.

Core principle: Test what the code does, not what the mocks do.

Following strict TDD prevents these anti-patterns.

---

The Iron Laws

1. NEVER test mock behavior
2. NEVER add test-only methods to production classes
3. NEVER mock without understanding dependencies

---

Anti-Pattern 1: Testing Mock Behavior

The violation:

// ❌ BAD: Testing that the mock exists
test('renders sidebar', () => {
  render(<Page />);
  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
});

Why this is wrong:

• You're verifying the mock works, not that the component works
• Test passes when mock is present, fails when it's not
• Tells you nothing about real behavior

The fix:

// ✅ GOOD: Test real component or don't mock it
test('renders sidebar', () => {
  render(<Page />);  // Don't mock sidebar
  expect(screen.getByRole('navigation')).toBeInTheDocument();
});

// OR if sidebar must be mocked for isolation:
// Don't assert on the mock - test Page's behavior with sidebar present

Gate Function

BEFORE asserting on any mock element:
  Ask: "Am I testing real component behavior or just mock existence?"

  IF testing mock existence:
    STOP - Delete the assertion or unmock the component

  Test real behavior instead

---

Anti-Pattern 2: Test-Only Methods in Production

The violation:

// ❌ BAD: destroy() only used in tests
class Session {
  async destroy() {  // Looks like production API!
    await this._workspaceManager?.destroyWorkspace(this.id);
    // ... cleanup
  }
}

// In tests
afterEach(() => session.destroy());

Why this is wrong:

• Production class polluted with test-only code
• Dangerous if accidentally called in production
• Violates YAGNI and separation of concerns
• Confuses object lifecycle with entity lifecycle

The fix:

// ✅ GOOD: Test utilities handle test cleanup
// Session has no destroy() - it's stateless in production

// In test-utils/
export async function cleanupSession(session: Session) {
  const workspace = session.getWorkspaceInfo();
  if (workspace) {
    await workspaceManager.destroyWorkspace(workspace.id);
  }
}

// In tests
afterEach(() => cleanupSession(session));

Gate Function

BEFORE adding any method to production class:
  Ask: "Is this only used by tests?"

  IF yes:
    STOP - Don't add it
    Put it in test utilities instead

  Ask: "Does this class own this resource's lifecycle?"

  IF no:
    STOP - Wrong class for this method

---

Anti-Pattern 3: Mocking Without Understanding

The violation:

// ❌ BAD: Mock breaks test logic
test('detects duplicate server', () => {
  // Mock prevents config write that test depends on!
  vi.mock('ToolCatalog', () => ({
    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
  }));

  await addServer(config);
  await addServer(config);  // Should throw - but won't!
});

Why this is wrong:

• Mocked method had side effect test depended on (writing config)
• Over-mocking to "be safe" breaks actual behavior
• Test passes for wrong reason or fails mysteriously

The fix:

// ✅ GOOD: Mock at correct level
test('detects duplicate server', () => {
  // Mock the slow part, preserve behavior test needs
  vi.mock('MCPServerManager'); // Just mock slow server startup

  await addServer(config);  // Config written
  await addServer(config);  // Duplicate detected ✓
});

Gate Function

BEFORE mocking any method:
  STOP - Don't mock yet

  1. Ask: "What side effects does the real method have?"
  2. Ask: "Does this test depend on any of those side effects?"
  3. Ask: "Do I fully understand what this test needs?"

  IF depends on side effects:
    Mock at lower level (the actual slow/external operation)
    OR use test doubles that preserve necessary behavior
    NOT the high-level method the test depends on

  IF unsure what test depends on:
    Run test with real implementation FIRST
    Observe what actually needs to happen
    THEN add minimal mocking at the right level

  Red flags:
    - "I'll mock this to be safe"
    - "This might be slow, better mock it"
    - Mocking without understanding the dependency chain

---

Anti-Pattern 4: Incomplete Mocks

The violation:

// ❌ BAD: Partial mock - only fields you think you need
const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' }
  // Missing: metadata that downstream code uses
};

// Later: breaks when code accesses response.metadata.requestId

Why this is wrong:

• Partial mocks hide structural assumptions - You only mocked fields you know about
• Downstream code may depend on fields you didn't include - Silent failures
• Tests pass but integration fails - Mock incomplete, real API complete
• False confidence - Test proves nothing about real behavior

The Iron Rule: Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.

The fix:

// ✅ GOOD: Mirror real API completeness
const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' },
  metadata: { requestId: 'req-789', timestamp: 1234567890 }
  // All fields real API returns
};

Gate Function

BEFORE creating mock responses:
  Check: "What fields does the real API response contain?"

  Actions:
    1. Examine actual API response from docs/examples
    2. Include ALL fields system might consume downstream
    3. Verify mock matches real response schema completely

  Critical:
    If you're creating a mock, you must understand the ENTIRE structure
    Partial mocks fail silently when code depends on omitted fields

  If uncertain: Include all documented fields

---

Anti-Pattern 5: Integration Tests as Afterthought

The violation:

✅ Implementation complete
❌ No tests written
"Ready for testing"

Why this is wrong:

• Testing is part of implementation, not optional follow-up
• TDD would have caught this
• Can't claim complete without tests

The fix:

TDD cycle:
1. Write failing test
2. Implement to pass
3. Refactor
4. THEN claim complete

---

When Mocks Become Too Complex

Warning signs:

• Mock setup longer than test logic
• Mocking everything to make test pass
• Mocks missing methods real components have
• Test breaks when mock changes

Consider: Integration tests with real components often simpler than complex mocks

---

TDD Prevents These Anti-Patterns

Why TDD helps: 1. Write test first → Forces you to think about what you're actually testing 2. Watch it fail → Confirms test tests real behavior, not mocks 3. Minimal implementation → No test-only methods creep in 4. Real dependencies → You see what the test actually needs before mocking

If you're testing mock behavior, you violated TDD - you added mocks without watching test fail against real code first.

---

Quick Reference

---

Red Flags

• Assertion checks for *-mock test IDs
• Methods only called in test files
• Mock setup is >50% of test
• Test fails when you remove mock
• Can't explain why mock is needed
• Mocking "just to be safe"

---

The Bottom Line

Mocks are tools to isolate, not things to test.

If TDD reveals you're testing mock behavior, you've gone wrong.

Fix: Test real behavior or question why you're mocking at all.