specweave 0.26.4 → 0.26.9

package/plugins/specweave-testing/skills/tdd-expert/SKILL.md

@@ -5,17 +5,15 @@ description: Test-Driven Development (TDD) expertise covering red-green-refactor
 
 # Test-Driven Development (TDD) Expert
 
-## Core Philosophy
+**Self-contained TDD expertise for ANY user project.**
 
-Test-Driven Development is a software development approach where tests are written BEFORE the implementation code. This forces better design, ensures testability, and provides a safety net for refactoring.
-
-**Core Principle**: "Red, Green, Refactor"
+---
 
-## The TDD Cycle
+## The TDD Cycle: Red-Green-Refactor
 
-### 1. Red Phase: Write a Failing Test
+### 1. RED Phase: Write Failing Test
 
-**Goal**: Define expected behavior through a test that fails
+**Goal**: Define expected behavior through a failing test
 
 ```typescript
 import { describe, it, expect } from 'vitest';
@@ -24,911 +22,433 @@ import { Calculator } from './Calculator';
 describe('Calculator', () => {
   it('should add two numbers', () => {
     const calculator = new Calculator();
-
-    // This test WILL fail because Calculator doesn't exist yet
-    expect(calculator.add(2, 3)).toBe(5);
+    expect(calculator.add(2, 3)).toBe(5); // WILL FAIL - Calculator doesn't exist
   });
 });
 ```
 
-**Red Phase Checklist**:
+**RED Checklist**:
 - [ ] Test describes ONE specific behavior
-- [ ] Test fails for the RIGHT reason (not syntax error)
-- [ ] Test is readable and understandable
-- [ ] Expected behavior is clear from test name
+- [ ] Test fails for RIGHT reason (not syntax error)
+- [ ] Test name is clear
+- [ ] Expected behavior obvious
 
-**Common Mistakes in Red Phase**:
-- Writing multiple assertions in one test
-- Testing implementation details instead of behavior
-- Writing tests that pass immediately (no value!)
-- Unclear test names
+### 2. GREEN Phase: Minimal Implementation
 
-### 2. Green Phase: Make It Pass (Minimal Implementation)
-
-**Goal**: Write the simplest code that makes the test pass
+**Goal**: Simplest code that makes test pass
 
 ```typescript
 // Calculator.ts
 export class Calculator {
   add(a: number, b: number): number {
-    return 5; // Hardcoded! But test passes
+    return a + b; // Minimal implementation
   }
 }
 ```
 
-**Wait, hardcoded 5?** Yes! This is intentional. The green phase is about making tests pass with minimal code. The next test will force us to generalize.
-
-**Add another test** (triangulation):
-```typescript
-it('should add different numbers', () => {
-  const calculator = new Calculator();
-  expect(calculator.add(10, 20)).toBe(30); // Now hardcoded 5 fails!
-});
-```
-
-**Now implement properly**:
-```typescript
-export class Calculator {
-  add(a: number, b: number): number {
-    return a + b; // Generalized solution
-  }
-}
-```
-
-**Green Phase Checklist**:
-- [ ] All tests pass
-- [ ] Implementation is minimal (no premature optimization)
-- [ ] No extra features beyond what tests require
-- [ ] Code is simple and direct
-
-**Common Mistakes in Green Phase**:
-- Over-engineering the solution
-- Adding features not covered by tests
-- Premature optimization
-- Skipping the refactor phase
+**GREEN Checklist**:
+- [ ] Test passes
+- [ ] Code is simplest possible
+- [ ] No premature optimization
+- [ ] No extra features
 
-### 3. Refactor Phase: Improve Code Quality
+### 3. REFACTOR Phase: Improve Design
 
-**Goal**: Improve code structure while keeping all tests green
+**Goal**: Improve code quality without changing behavior
 
 ```typescript
-// Before refactoring
+// Refactor: Support variable arguments
 export class Calculator {
-  add(a: number, b: number): number {
-    return a + b;
-  }
-
-  subtract(a: number, b: number): number {
-    return a - b;
-  }
-
-  multiply(a: number, b: number): number {
-    return a * b;
-  }
-
-  divide(a: number, b: number): number {
-    if (b === 0) {
-      throw new Error('Division by zero');
-    }
-    return a / b;
-  }
-}
-```
-
-**Refactored with better design**:
-```typescript
-// Extract operation interface
-interface Operation {
-  execute(a: number, b: number): number;
-}
-
-class AddOperation implements Operation {
-  execute(a: number, b: number): number {
-    return a + b;
-  }
-}
-
-class DivideOperation implements Operation {
-  execute(a: number, b: number): number {
-    if (b === 0) {
-      throw new Error('Division by zero');
-    }
-    return a / b;
+  add(...numbers: number[]): number {
+    return numbers.reduce((sum, n) => sum + n, 0);
   }
 }
 
-export class Calculator {
-  private operations: Map<string, Operation> = new Map([
-    ['add', new AddOperation()],
-    ['divide', new DivideOperation()],
-  ]);
-
-  perform(operation: string, a: number, b: number): number {
-    const op = this.operations.get(operation);
-    if (!op) {
-      throw new Error(`Unknown operation: ${operation}`);
-    }
-    return op.execute(a, b);
-  }
-}
+// Tests still pass!
 ```
 
-**Refactor Phase Checklist**:
+**REFACTOR Checklist**:
 - [ ] All tests still pass
 - [ ] Code is more readable
-- [ ] Duplication removed (DRY principle)
-- [ ] Code follows SOLID principles
-- [ ] Better separation of concerns
-- [ ] No new functionality added
-
-**Refactoring Patterns**:
-- Extract Method/Function
-- Extract Class
-- Introduce Parameter Object
-- Replace Conditional with Polymorphism
-- Extract Interface
-- Rename for clarity
-
-## TDD Best Practices
+- [ ] Removed duplication
+- [ ] Better design patterns
 
-### 1. Test Behavior, Not Implementation
-
-**❌ BAD: Testing implementation details**
-```typescript
-it('should call internal helper method', () => {
-  const spy = vi.spyOn(calculator, '_internalHelper');
-  calculator.add(2, 3);
-  expect(spy).toHaveBeenCalled(); // Brittle! Breaks on refactor
-});
-```
-
-**✅ GOOD: Testing behavior**
-```typescript
-it('should return sum of two numbers', () => {
-  expect(calculator.add(2, 3)).toBe(5); // Robust!
-});
-```
+---
 
-### 2. One Assertion Per Test (When Possible)
+## TDD Benefits
 
-**❌ BAD: Multiple unrelated assertions**
-```typescript
-it('should validate user', () => {
-  expect(user.name).toBe('John');
-  expect(user.email).toBe('john@example.com');
-  expect(user.isActive).toBe(true);
-  expect(user.roles).toContain('admin');
-});
-```
+**Design Benefits**:
+- Forces modular, testable code
+- Reveals design problems early
+- Encourages SOLID principles
+- Promotes simple solutions
 
-**✅ GOOD: Focused tests**
-```typescript
-it('should have correct name', () => {
-  expect(user.name).toBe('John');
-});
+**Quality Benefits**:
+- 100% test coverage (by definition)
+- Tests document behavior
+- Regression safety net
+- Faster debugging
 
-it('should have valid email', () => {
-  expect(user.email).toBe('john@example.com');
-});
+**Productivity Benefits**:
+- Less time debugging
+- Confidence to refactor
+- Faster iterations
+- Clearer requirements
 
-it('should be active by default', () => {
-  expect(user.isActive).toBe(true);
-});
+---
 
-it('should include admin role', () => {
-  expect(user.roles).toContain('admin');
-});
-```
+## BDD: Behavior-Driven Development
 
-### 3. Test Edge Cases and Boundaries
+**Extension of TDD with natural language tests**
 
-**Test pyramid for a single function**:
-1. Happy path (normal input)
-2. Edge cases (empty, null, boundary values)
-3. Error cases (invalid input)
+### Given-When-Then Pattern
 
 ```typescript
-describe('divide', () => {
-  // Happy path
-  it('should divide two positive numbers', () => {
-    expect(calculator.divide(10, 2)).toBe(5);
-  });
-
-  // Edge cases
-  it('should handle division resulting in decimal', () => {
-    expect(calculator.divide(5, 2)).toBe(2.5);
-  });
-
-  it('should handle negative numbers', () => {
-    expect(calculator.divide(-10, 2)).toBe(-5);
-  });
+describe('Shopping Cart', () => {
+  it('should apply 10% discount when total exceeds $100', () => {
+    // Given: A cart with $120 worth of items
+    const cart = new ShoppingCart();
+    cart.addItem({ price: 120, quantity: 1 });
 
-  it('should handle zero dividend', () => {
-    expect(calculator.divide(0, 5)).toBe(0);
-  });
+    // When: Getting the total
+    const total = cart.getTotal();
 
-  // Error case
-  it('should throw error for division by zero', () => {
-    expect(() => calculator.divide(10, 0)).toThrow('Division by zero');
+    // Then: 10% discount applied
+    expect(total).toBe(108); // $120 - $12 (10%)
   });
 });
 ```
 
-### 4. Use Descriptive Test Names
+**BDD Benefits**:
+- Tests readable by non-developers
+- Clear business requirements
+- Better stakeholder communication
+- Executable specifications
 
-**Pattern**: `should [expected behavior] when [condition]`
+---
 
-```typescript
-// ✅ GOOD: Clear and descriptive
-it('should return empty array when no users exist', () => { ... });
-it('should throw ValidationError when email is invalid', () => { ... });
-it('should apply discount when user has premium membership', () => { ... });
-
-// ❌ BAD: Vague and unclear
-it('works', () => { ... });
-it('test user creation', () => { ... });
-it('returns data', () => { ... });
-```
+## TDD Patterns
 
-### 5. Follow AAA Pattern (Arrange-Act-Assert)
+### Pattern 1: Test List
 
-```typescript
-it('should calculate total with discount', () => {
-  // ARRANGE: Set up test data and dependencies
-  const cart = new ShoppingCart();
-  cart.addItem({ name: 'Book', price: 20 });
-  cart.addItem({ name: 'Pen', price: 5 });
-  const discountCode = 'SAVE10';
-
-  // ACT: Execute the behavior under test
-  const total = cart.calculateTotal(discountCode);
-
-  // ASSERT: Verify the result
-  expect(total).toBe(22.5); // 25 * 0.9 = 22.5
-});
+Before coding, list all tests needed:
+
+```markdown
+Calculator Tests:
+- [ ] add two positive numbers
+- [ ] add negative numbers
+- [ ] add zero
+- [ ] add multiple numbers
+- [ ] multiply two numbers
+- [ ] divide two numbers
+- [ ] divide by zero (error)
 ```
 
-### 6. Test Isolation (No Shared State)
+Work through list one by one.
 
-**❌ BAD: Shared state between tests**
-```typescript
-let user: User; // SHARED STATE!
+### Pattern 2: Fake It Till You Make It
 
-beforeAll(() => {
-  user = new User('John'); // Created once
-});
+Start with hardcoded returns, generalize later:
 
-it('should update name', () => {
-  user.updateName('Jane'); // MUTATES SHARED STATE
-  expect(user.name).toBe('Jane');
-});
+```typescript
+// Test 1: add(2, 3) = 5
+add(a, b) { return 5; } // Hardcoded!
 
-it('should have original name', () => {
-  expect(user.name).toBe('John'); // FAILS! Name is 'Jane' from previous test
-});
+// Test 2: add(5, 7) = 12
+add(a, b) { return a + b; } // Generalized
 ```
 
-**✅ GOOD: Isolated tests**
+### Pattern 3: Triangulation
+
+Use multiple tests to force generalization:
+
 ```typescript
-describe('User', () => {
-  let user: User;
+// Test 1
+expect(fizzbuzz(3)).toBe('Fizz');
 
-  beforeEach(() => {
-    user = new User('John'); // FRESH instance for each test
-  });
+// Test 2
+expect(fizzbuzz(5)).toBe('Buzz');
 
-  it('should update name', () => {
-    user.updateName('Jane');
-    expect(user.name).toBe('Jane');
-  });
+// Test 3
+expect(fizzbuzz(15)).toBe('FizzBuzz');
 
-  it('should have original name', () => {
-    expect(user.name).toBe('John'); // PASSES! Fresh instance
-  });
-});
+// Forces complete implementation
 ```
 
-## TDD Workflow Examples
+### Pattern 4: Test Data Builders
 
-### Example 1: Building a User Validator
+Create test helpers for complex objects:
 
-**Step 1: RED - Write failing test**
 ```typescript
-describe('UserValidator', () => {
-  it('should validate email format', () => {
-    const validator = new UserValidator();
-    expect(validator.validateEmail('user@example.com')).toBe(true);
-  });
-});
-```
+class UserBuilder {
+  private user = { name: 'Test', email: 'test@example.com', role: 'user' };
 
-**Step 2: GREEN - Minimal implementation**
-```typescript
-export class UserValidator {
-  validateEmail(email: string): boolean {
-    return true; // Hardcoded! But test passes
+  withName(name: string) {
+    this.user.name = name;
+    return this;
   }
-}
-```
 
-**Step 3: Add negative test (triangulation)**
-```typescript
-it('should reject invalid email', () => {
-  const validator = new UserValidator();
-  expect(validator.validateEmail('invalid')).toBe(false); // Forces real implementation
-});
-```
-
-**Step 4: GREEN - Real implementation**
-```typescript
-export class UserValidator {
-  validateEmail(email: string): boolean {
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+  withRole(role: string) {
+    this.user.role = role;
+    return this;
   }
-}
-```
-
-**Step 5: REFACTOR - Extract regex**
-```typescript
-export class UserValidator {
-  private static EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
-  validateEmail(email: string): boolean {
-    return UserValidator.EMAIL_REGEX.test(email);
+  build() {
+    return this.user;
   }
 }
-```
-
-**Step 6: Add more edge cases**
-```typescript
-it('should reject empty email', () => {
-  expect(validator.validateEmail('')).toBe(false);
-});
 
-it('should reject null email', () => {
-  expect(validator.validateEmail(null as any)).toBe(false);
-});
-
-it('should reject email without domain', () => {
-  expect(validator.validateEmail('user@')).toBe(false);
-});
+// Usage
+const admin = new UserBuilder().withRole('admin').build();
 ```
 
-**Final refactored implementation**:
-```typescript
-export class UserValidator {
-  private static EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-
-  validateEmail(email: string | null | undefined): boolean {
-    if (!email || typeof email !== 'string') {
-      return false;
-    }
-    return UserValidator.EMAIL_REGEX.test(email);
-  }
-}
-```
+---
 
-### Example 2: Building a Shopping Cart
+## Refactoring with Confidence
 
-**RED: Test adding items**
-```typescript
-describe('ShoppingCart', () => {
-  it('should add item to cart', () => {
-    const cart = new ShoppingCart();
-    cart.addItem({ id: 1, name: 'Book', price: 20 });
+**The TDD Safety Net**
 
-    expect(cart.getItemCount()).toBe(1);
-  });
-});
-```
+### Refactoring Types
 
-**GREEN: Minimal implementation**
+**1. Extract Method**:
 ```typescript
-interface CartItem {
-  id: number;
-  name: string;
-  price: number;
+// Before
+function processOrder(order) {
+  const total = order.items.reduce((sum, item) => sum + item.price, 0);
+  const tax = total * 0.1;
+  return total + tax;
 }
 
-export class ShoppingCart {
-  private items: CartItem[] = [];
-
-  addItem(item: CartItem): void {
-    this.items.push(item);
-  }
-
-  getItemCount(): number {
-    return this.items.length;
-  }
+// After (refactored with test safety)
+function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price, 0);
 }
-```
-
-**RED: Test calculating total**
-```typescript
-it('should calculate total price', () => {
-  const cart = new ShoppingCart();
-  cart.addItem({ id: 1, name: 'Book', price: 20 });
-  cart.addItem({ id: 2, name: 'Pen', price: 5 });
-
-  expect(cart.getTotal()).toBe(25);
-});
-```
 
-**GREEN: Implement total**
-```typescript
-export class ShoppingCart {
-  // ... previous code ...
+function calculateTax(total) {
+  return total * 0.1;
+}
 
-  getTotal(): number {
-    return this.items.reduce((sum, item) => sum + item.price, 0);
-  }
+function processOrder(order) {
+  const total = calculateTotal(order.items);
+  const tax = calculateTax(total);
+  return total + tax;
 }
 ```
 
-**RED: Test removing items**
+**2. Remove Duplication**:
 ```typescript
-it('should remove item from cart', () => {
-  const cart = new ShoppingCart();
-  cart.addItem({ id: 1, name: 'Book', price: 20 });
-  cart.removeItem(1);
-
-  expect(cart.getItemCount()).toBe(0);
+// Tests force you to see duplication
+it('should validate email', () => {
+  expect(validateEmail('test@example.com')).toBe(true);
+  expect(validateEmail('invalid')).toBe(false);
 });
-```
 
-**GREEN: Implement remove**
-```typescript
-export class ShoppingCart {
-  // ... previous code ...
+it('should validate phone', () => {
+  expect(validatePhone('+1-555-0100')).toBe(true);
+  expect(validatePhone('invalid')).toBe(false);
+});
 
-  removeItem(itemId: number): void {
-    this.items = this.items.filter(item => item.id !== itemId);
-  }
-}
+// Extract common validation pattern
 ```
 
-**REFACTOR: Extract calculations**
-```typescript
-export class ShoppingCart {
-  private items: CartItem[] = [];
-
-  addItem(item: CartItem): void {
-    this.items.push(item);
-  }
+### Refactoring Workflow
 
-  removeItem(itemId: number): void {
-    this.items = this.items.filter(item => item.id !== itemId);
-  }
-
-  getItemCount(): number {
-    return this.items.length;
-  }
-
-  getTotal(): number {
-    return this.calculateTotal(this.items);
-  }
-
-  private calculateTotal(items: CartItem[]): number {
-    return items.reduce((sum, item) => sum + item.price, 0);
-  }
-
-  isEmpty(): boolean {
-    return this.items.length === 0;
-  }
-}
+```
+1. All tests GREEN? → Continue
+2. Identify code smell
+3. Make small refactoring
+4. Run tests → GREEN? → Continue
+5. Repeat until satisfied
+6. Commit
 ```
 
-## TDD with Mocks and Test Doubles
-
-### Types of Test Doubles
+---
 
-1. **Dummy**: Objects passed but never used
-2. **Stub**: Returns predefined values
-3. **Spy**: Records information about calls
-4. **Mock**: Verifies interactions
-5. **Fake**: Working implementation (simplified)
+## TDD Anti-Patterns
 
-### Example: Testing with Mocks
+### ❌ Testing Implementation Details
 
-**RED: Test user creation with email service**
 ```typescript
-describe('UserService', () => {
-  it('should send welcome email when user created', async () => {
-    const emailService = createMockEmailService();
-    const userService = new UserService(emailService);
-
-    await userService.createUser({ name: 'John', email: 'john@example.com' });
-
-    expect(emailService.sendWelcomeEmail).toHaveBeenCalledWith('john@example.com');
-  });
+// BAD: Testing private method
+it('should call _validateEmail internally', () => {
+  spyOn(service, '_validateEmail');
+  service.createUser({ email: 'test@example.com' });
+  expect(service._validateEmail).toHaveBeenCalled();
 });
-```
 
-**GREEN: Implementation with dependency injection**
-```typescript
-interface EmailService {
-  sendWelcomeEmail(email: string): Promise<void>;
-}
-
-export class UserService {
-  constructor(private emailService: EmailService) {}
-
-  async createUser(userData: { name: string; email: string }): Promise<User> {
-    const user = new User(userData);
-    await this.emailService.sendWelcomeEmail(user.email);
-    return user;
-  }
-}
-
-// Test helper
-function createMockEmailService(): EmailService {
-  return {
-    sendWelcomeEmail: vi.fn().mockResolvedValue(undefined),
-  };
-}
+// GOOD: Testing behavior
+it('should reject invalid email', () => {
+  expect(() => service.createUser({ email: 'invalid' }))
+    .toThrow('Invalid email');
+});
 ```
 
-## TDD and SOLID Principles
-
-TDD naturally leads to SOLID design:
-
-### 1. Single Responsibility Principle (SRP)
-
-**TDD forces SRP** because classes with multiple responsibilities are hard to test.
+### ❌ Writing Tests After Code
 
 ```typescript
-// ❌ BAD: Multiple responsibilities (hard to test!)
-class UserManager {
-  createUser() { /* ... */ }
-  sendEmail() { /* ... */ }
-  saveToDatabase() { /* ... */ }
-  validateInput() { /* ... */ }
-}
+// Wrong order!
+1. Write implementation
+2. Write tests
 
-// ✅ GOOD: Single responsibility (easy to test!)
-class UserCreator {
-  createUser() { /* ... */ }
-}
-
-class EmailSender {
-  sendEmail() { /* ... */ }
-}
-
-class UserRepository {
-  save() { /* ... */ }
-}
-
-class UserValidator {
-  validate() { /* ... */ }
-}
+// Correct TDD:
+1. Write test (RED)
+2. Write implementation (GREEN)
+3. Refactor
 ```
 
-### 2. Open/Closed Principle (OCP)
-
-**TDD encourages extension through abstraction**
+### ❌ Large Tests
 
 ```typescript
-// Extension through interfaces
-interface PaymentProcessor {
-  process(amount: number): Promise<PaymentResult>;
-}
-
-class StripeProcessor implements PaymentProcessor {
-  async process(amount: number): Promise<PaymentResult> {
-    // Stripe implementation
-  }
-}
-
-class PayPalProcessor implements PaymentProcessor {
-  async process(amount: number): Promise<PaymentResult> {
-    // PayPal implementation
-  }
-}
-
-// Tests can easily mock PaymentProcessor
-describe('OrderService', () => {
-  it('should process payment', async () => {
-    const mockProcessor: PaymentProcessor = {
-      process: vi.fn().mockResolvedValue({ success: true }),
-    };
+// BAD: Testing multiple behaviors
+it('should handle user lifecycle', () => {
+  const user = createUser();
+  updateUser(user, { name: 'New Name' });
+  deleteUser(user);
+  // Too much in one test!
+});
 
-    const orderService = new OrderService(mockProcessor);
-    await orderService.completeOrder(100);
+// GOOD: One behavior per test
+it('should create user', () => {
+  const user = createUser();
+  expect(user).toBeDefined();
+});
 
-    expect(mockProcessor.process).toHaveBeenCalledWith(100);
-  });
+it('should update user name', () => {
+  const user = createUser();
+  updateUser(user, { name: 'New Name' });
+  expect(user.name).toBe('New Name');
 });
 ```
 
-### 3. Liskov Substitution Principle (LSP)
-
-**TDD ensures LSP through contract testing**
+### ❌ Skipping Refactor Phase
 
 ```typescript
-// Base class contract
-abstract class Shape {
-  abstract area(): number;
-}
-
-// Implementations must satisfy contract
-class Rectangle extends Shape {
-  constructor(private width: number, private height: number) {
-    super();
-  }
-
-  area(): number {
-    return this.width * this.height;
-  }
-}
-
-class Circle extends Shape {
-  constructor(private radius: number) {
-    super();
-  }
-
-  area(): number {
-    return Math.PI * this.radius ** 2;
-  }
-}
-
-// Test contract for all shapes
-function testShapeContract(createShape: () => Shape) {
-  it('should have positive area', () => {
-    const shape = createShape();
-    expect(shape.area()).toBeGreaterThan(0);
-  });
-
-  it('should return number', () => {
-    const shape = createShape();
-    expect(typeof shape.area()).toBe('number');
-  });
-}
-
-describe('Rectangle', () => {
-  testShapeContract(() => new Rectangle(10, 5));
-});
-
-describe('Circle', () => {
-  testShapeContract(() => new Circle(5));
-});
+// Don't skip refactoring!
+RED → GREEN → REFACTOR → RED → GREEN → REFACTOR
+     ↑________________↑
+     Always refactor!
 ```
 
-### 4. Interface Segregation Principle (ISP)
+---
 
-**TDD reveals when interfaces are too large**
+## Mock-Driven TDD
 
-```typescript
-// ❌ BAD: Fat interface (forces unnecessary mocking)
-interface Worker {
-  work(): void;
-  eat(): void;
-  sleep(): void;
-}
+**When testing with external dependencies**
 
-// Mocking is painful
-const mockWorker: Worker = {
-  work: vi.fn(),
-  eat: vi.fn(),   // Not needed for this test!
-  sleep: vi.fn(), // Not needed for this test!
-};
+### Strategy 1: Dependency Injection
 
-// ✅ GOOD: Segregated interfaces
-interface Workable {
-  work(): void;
-}
+```typescript
+class UserService {
+  constructor(private db: Database) {} // Inject dependency
 
-interface Eatable {
-  eat(): void;
+  async getUser(id: string) {
+    return this.db.query('SELECT * FROM users WHERE id = ?', [id]);
+  }
 }
 
-// Only mock what you need
-const mockWorkable: Workable = {
-  work: vi.fn(),
-};
+// Test with mock
+const mockDb = { query: vi.fn().mockResolvedValue({ id: '123' }) };
+const service = new UserService(mockDb);
 ```
 
-### 5. Dependency Inversion Principle (DIP)
-
-**TDD requires dependency injection (essential for testing)**
+### Strategy 2: Interface-Based Mocking
 
 ```typescript
-// ✅ GOOD: Depends on abstraction
-interface Logger {
-  log(message: string): void;
+interface EmailService {
+  send(to: string, subject: string, body: string): Promise<void>;
 }
 
-class UserService {
-  constructor(private logger: Logger) {} // Injected dependency
+class MockEmailService implements EmailService {
+  sent: any[] = [];
 
-  createUser(name: string) {
-    this.logger.log(`Creating user: ${name}`);
-    // ...
+  async send(to: string, subject: string, body: string) {
+    this.sent.push({ to, subject, body });
   }
 }
 
-// Easy to test with mock
-describe('UserService', () => {
-  it('should log user creation', () => {
-    const mockLogger: Logger = { log: vi.fn() };
-    const service = new UserService(mockLogger);
-
-    service.createUser('John');
-
-    expect(mockLogger.log).toHaveBeenCalledWith('Creating user: John');
-  });
-});
+// Test with mock
+const mockEmail = new MockEmailService();
+const service = new UserService(mockEmail);
+await service.registerUser({ email: 'test@example.com' });
+expect(mockEmail.sent).toHaveLength(1);
 ```
 
-## TDD Anti-Patterns to Avoid
-
-### 1. The Liar (Passing test that doesn't test anything)
-
-**❌ BAD**:
-```typescript
-it('should validate user', () => {
-  const result = true; // Hardcoded!
-  expect(result).toBe(true); // Always passes
-});
-```
+---
 
-### 2. Excessive Setup (Tests too complex)
+## SOLID Principles Through TDD
 
-**❌ BAD**:
-```typescript
-beforeEach(() => {
-  // 50 lines of setup code...
-  database.connect();
-  seedTestData();
-  setupMocks();
-  configureEnvironment();
-  // ...
-});
-```
+**TDD naturally leads to SOLID design**
 
-**✅ GOOD**: Extract to helper or fixture
+### Single Responsibility (SRP)
+Tests reveal when class does too much:
 ```typescript
-beforeEach(() => {
-  testEnv = createTestEnvironment(); // Encapsulated setup
+// Many tests for one class? Split it!
+describe('UserManager', () => {
+  // 20+ tests here → Too many responsibilities
 });
-```
-
-### 3. The Giant (One test testing everything)
 
-**❌ BAD**:
-```typescript
-it('should handle entire user lifecycle', () => {
-  // 200 lines of test code testing create, update, delete, search...
-});
+// Refactor to multiple classes
+describe('UserCreator', () => { /* 5 tests */ });
+describe('UserValidator', () => { /* 5 tests */ });
+describe('UserNotifier', () => { /* 5 tests */ });
 ```
 
-**✅ GOOD**: One test per behavior
+### Open/Closed (OCP)
+Tests enable extension without modification:
 ```typescript
-it('should create user', () => { /* ... */ });
-it('should update user', () => { /* ... */ });
-it('should delete user', () => { /* ... */ });
-```
-
-### 4. The Mockery (Over-mocking)
-
-**❌ BAD**:
-```typescript
-vi.mock('./utils');
-vi.mock('./helpers');
-vi.mock('./validators');
-vi.mock('./formatters');
-// Testing nothing but mocks!
-```
+// Testable, extensible design
+interface PaymentProcessor {
+  process(amount: number): Promise<void>;
+}
 
-**✅ GOOD**: Mock only external dependencies
-```typescript
-vi.mock('./externalApi'); // Mock external API only
-// Test real code integration
+class StripeProcessor implements PaymentProcessor { }
+class PayPalProcessor implements PaymentProcessor { }
 ```
 
-### 5. The Slow Poke (Slow tests)
-
-**❌ BAD**:
+### Dependency Inversion (DIP)
+TDD requires dependency injection:
 ```typescript
-it('should process data', async () => {
-  await sleep(5000); // Hardcoded delays
-  // ...
-});
-```
+// Testable: Depends on abstraction
+class OrderService {
+  constructor(private payment: PaymentProcessor) {}
+}
 
-**✅ GOOD**: Use fake timers
-```typescript
-it('should process data', () => {
-  vi.useFakeTimers();
-  // ...
-  vi.advanceTimersByTime(5000);
-  vi.restoreAllTimers();
-});
+// Easy to test with mocks
+const mockPayment = new MockPaymentProcessor();
+const service = new OrderService(mockPayment);
 ```
 
-## TDD Metrics & Success Indicators
-
-**Good TDD indicators**:
-- ✅ 80%+ code coverage
-- ✅ Tests run in < 1 second (unit tests)
-- ✅ Tests are independent and can run in any order
-- ✅ Tests are readable and self-documenting
-- ✅ Red-Green-Refactor cycle followed consistently
-- ✅ Code is modular and testable
-
-**Warning signs**:
-- ❌ Tests take minutes to run
-- ❌ Tests fail randomly (flakiness)
-- ❌ Hard to write tests (indicates design issues)
-- ❌ Mocking everything (over-mocking)
-- ❌ Tests break on refactoring (testing implementation)
-
-## TDD in Practice: Real-World Tips
-
-### 1. Start Small
-Begin TDD on new features, not legacy code. Retrofit tests gradually.
-
-### 2. Write Test First (Always!)
-Resist urge to code first. The test is your design tool.
-
-### 3. Keep Tests Fast
-Unit tests should run in milliseconds. Slow tests kill TDD.
-
-### 4. Commit Test + Code Together
-Tests are part of the implementation, not afterthought.
-
-### 5. Refactor Relentlessly
-Green doesn't mean done. Refactor for clarity.
-
-### 6. Test Behavior, Not Implementation
-Tests should survive refactoring.
-
-### 7. Use TDD to Drive Design
-Let tests guide your architecture (dependency injection, SOLID).
-
-## TDD Workflow Commands
-
-**Development cycle**:
-```bash
-# 1. Write failing test (RED)
-npm test -- --watch
-
-# 2. Implement (GREEN)
-# Make changes, watch tests turn green
+---
 
-# 3. Refactor
-# Improve code, tests stay green
+## Quick Reference
 
-# 4. Commit
-git add .
-git commit -m "feat: add user validation"
+### TDD Workflow
 ```
-
-**Coverage check**:
-```bash
-npm test -- --coverage
-# Ensure 80%+ coverage
+1. Write test (RED) → Fails ✅
+2. Minimal code (GREEN) → Passes ✅
+3. Refactor → Still passes ✅
+4. Repeat
 ```
 
-## Resources
-
-- **Kent Beck**: "Test-Driven Development by Example"
-- **Robert C. Martin**: "Clean Code" (TDD chapter)
-- **Martin Fowler**: Refactoring patterns
-- **Growing Object-Oriented Software, Guided by Tests** (Freeman & Pryce)
+### Test Smells
+- Test too long (>20 lines)
+- Multiple assertions (>3)
+- Testing implementation
+- Unclear test name
+- Slow tests (>100ms)
+- Flaky tests
 
-## Summary
+### When to Use TDD
+✅ New features
+✅ Bug fixes (add test first)
+✅ Refactoring
+✅ Complex logic
+✅ Public APIs
 
-**TDD Core Rules**:
-1. Write test FIRST (red)
-2. Make it pass MINIMALLY (green)
-3. Refactor RELENTLESSLY (refactor)
-4. Repeat
+❌ Throwaway prototypes
+❌ UI layout (use E2E instead)
+❌ Highly experimental code
 
-**Benefits**:
-- Better design (testable = modular)
-- Living documentation
-- Fearless refactoring
-- Fast feedback loop
-- Higher confidence
+---
 
-**Remember**: TDD is about **design**, not just testing. Tests are a tool to drive better architecture.
+**This skill is self-contained and works in ANY user project.**