test-driven

TDD methodology for production-quality tests. Write tests FIRST driven by PRD, Tech Spec, Implementation Plan. Covers minimal mocking, realistic test data, strong assertions, test independence.

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026

When & Why to Use This Skill

This Claude skill implements a comprehensive Test-Driven Development (TDD) methodology designed to produce production-quality software through a 'test-first' approach. By strictly aligning tests with PRDs, Tech Specs, and Implementation Plans, it guides developers in building a robust test pyramid—spanning unit, integration, and GUI/E2E layers. It emphasizes realistic data, minimal mocking, and strong assertions to ensure code reliability, facilitate safe refactoring, and minimize technical debt.

Use Cases

  • Requirement-Driven Development: Automatically generating test cases directly from PRDs and Technical Specifications to ensure 100% feature coverage before a single line of production code is written.
  • API Contract Testing: Establishing rigorous integration tests for backend services to validate API responses, status codes, and data schemas against technical designs.
  • Automated E2E User Flows: Utilizing DevTools MCP to script and execute complex frontend tests, such as multi-step login processes and dashboard navigations, ensuring a seamless user experience.
  • Database Integration Validation: Implementing repository-level tests with real database instances (e.g., Prisma/PostgreSQL) to verify data integrity, unique constraints, and complex query logic.
  • Safe Refactoring and Maintenance: Leveraging the Red-Green-Refactor cycle to modernize legacy codebases while ensuring existing functionality remains intact through a comprehensive automated test suite.
nametest-driven
descriptionTDD methodology for production-quality tests. Write tests FIRST driven by PRD, Tech Spec, Implementation Plan. Covers minimal mocking, realistic test data, strong assertions, test independence.

Test-Driven Development Skill

Write tests FIRST, driven by project documents.

Critical: Document-Driven Testing

Before writing any test:

  1. Read latest PRD: docs/prd/[latest].md
  2. Read latest Tech Spec: docs/tech-spec/[latest].md
  3. Read Implementation Plan: docs/implementation-plan/[latest].md
  4. CONFIRM with user: "Is [filename] the current document?"

Test Pyramid

        GUI (E2E)       <- DevTools MCP (slow)
      Integration       <- Real DB, APIs (medium)
     Unit (Backend)     <- Fast, isolated

MORE tests at bottom, FEWER at top
Type Location Tools Speed Tests
Unit tests/unit/ Jest, Vitest Fast Functions, logic
Integration tests/integration/ Supertest, real DB Medium APIs, DB
GUI/E2E tests/e2e/ DevTools MCP Slow User flows

TDD Cycle

RED (Write failing test) -> GREEN (Make pass) -> REFACTOR (Clean up) -> REPEAT
Phase Action Rule
RED Write failing test MUST fail first
GREEN Minimal code to pass No extra features
REFACTOR Clean up Tests still pass

API Contract Testing (from Tech Spec)

describe('POST /api/auth/login', () => {
  test('accepts valid credentials', async () => {
    const response = await request(app)
      .post('/api/auth/login')
      .send({ email: 'user@example.com', password: 'SecurePass123!' })
      .expect(200);

    expect(response.body).toEqual({
      token: expect.stringMatching(/^eyJ/),
      user: { id: expect.stringMatching(/^usr_/), email: 'user@example.com' },
      expiresIn: 3600
    });
  });

  test('returns 401 for invalid password', async () => {
    await request(app)
      .post('/api/auth/login')
      .send({ email: 'user@example.com', password: 'wrong' })
      .expect(401);
  });
});

Database Integration Testing

describe('UserRepository', () => {
  beforeEach(async () => { await prisma.user.deleteMany(); });

  test('creates user with required fields', async () => {
    const user = await userRepository.create({ email: 'new@example.com', name: 'New User' });
    const dbUser = await prisma.user.findUnique({ where: { id: user.id } });
    expect(dbUser?.email).toBe('new@example.com');
  });

  test('enforces unique email', async () => {
    await userRepository.create({ email: 'existing@example.com' });
    await expect(userRepository.create({ email: 'existing@example.com' }))
      .rejects.toThrow('Email already exists');
  });
});

Unit Testing (Business Logic)

describe('calculateTotal', () => {
  test('applies percentage discount', () => {
    const items = [{ price: 100, quantity: 2 }, { price: 50, quantity: 1 }];
    expect(calculateTotal(items, { discountPercent: 10 })).toBe(225);
  });

  test('handles empty cart', () => {
    expect(calculateTotal([], {})).toBe(0);
  });
});

GUI Testing (DevTools MCP)

describe('Login Page', () => {
  test('successful login redirects to dashboard', async () => {
    await mcp.devtools.navigate('http://localhost:3000/login');
    await mcp.devtools.type('#email', 'user@example.com');
    await mcp.devtools.type('#password', 'SecurePass123!');
    await mcp.devtools.click('#submit-btn');
    await mcp.devtools.waitForNavigation();
    expect(await mcp.devtools.getCurrentUrl()).toBe('http://localhost:3000/dashboard');
  });

  test('shows error for invalid credentials', async () => {
    await mcp.devtools.navigate('http://localhost:3000/login');
    await mcp.devtools.type('#password', 'wrong');
    await mcp.devtools.click('#submit-btn');
    await mcp.devtools.waitForSelector('.error-message');
    expect(await mcp.devtools.getText('.error-message')).toBe('Invalid email or password');
  });
});

Test File Organization

tests/
  unit/services/, utils/, models/
  integration/api/, repositories/
  e2e/flows/, visual/, accessibility/
  factories/
  setup/database.ts, mcp.ts

Document-to-Test Mapping

PRD Section Test Type
User Stories E2E flow tests
Requirements Feature tests
Success Metrics Performance tests
Tech Spec Section Test Type
API Design Contract tests
Data Model DB integration
Error Handling Error scenarios

Commands

npm test                           # All tests
npm test -- --testPathPattern=unit # Unit only
npm test -- --testPathPattern=integration
npm run test:e2e                   # GUI tests
npm test -- --coverage

Checklist Before Writing Tests

  • Found latest PRD, Tech Spec, Plan
  • Confirmed with user
  • Extracted user stories (GUI tests)
  • Extracted API contracts (Backend tests)
  • Extracted error scenarios
  • Identified test phases

Anti-Patterns

Anti-Pattern Problem Fix
Testing implementation Brittle Test behavior/outcomes
Unrealistic mock data Miss edge cases Use realistic factories
Only happy path Miss errors Test edge cases & errors
Order-dependent tests Flaky Make independent
Over-mocking Miss bugs Real integrations (<20% mocking)
Weak assertions False positives Assert exact values