Skip to content

ilandahan/AID / skills/pipeline-orchestrator/references/standards/test-driven

test-driven

Verified

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.

SKILL.extended.md

View on GitHub
---
name: test-driven
description: Comprehensive TDD (Test-Driven Development) methodology for writing production-quality tests. Use this skill when writing tests before implementation, reviewing test quality, ensuring comprehensive coverage, avoiding test anti-patterns, or when asked about testing best practices. Covers minimal mocking strategies, realistic test data, strong assertions, and test independence.
---

# Test-Driven Development Skill

Write tests FIRST, driven by project documents (PRD, Tech Spec, Implementation Plan).

## 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?"    │
└─────────────────────────────────────────────────────────────────┘
```

### Document Workflow

```
User Request: "Write tests for feature X"
     │
     ├─► Step 1: FIND DOCUMENTS
     │        │
     │        ├─► ls docs/prd/ → Find latest PRD
     │        ├─► ls docs/tech-spec/ → Find latest Tech Spec
     │        └─► ls docs/implementation-plan/ → Find latest Plan
     │
     ├─► Step 2: CONFIRM WITH USER
     │        │
     │        └─► "I found these documents for feature X:
     │             - PRD: 2024-06-15-feature-x.md
     │             - Tech Spec: 2024-06-16-feature-x.md
     │             - Plan: 2024-06-17-feature-x.md
     │             Are these the current documents?"
     │
     ├─► Step 3: READ & EXTRACT
     │        │
     │        ├─► From PRD: User stories, requirements
     │        ├─► From Tech Spec: API contracts, schemas, errors
     │        └─► From Plan: Test strategy, phases
     │
     └─► Step 4: WRITE TESTS
              │
              ├─► Backend/API Tests (Unit + Integration)
              └─► GUI Tests (DevTools MCP)
```

## Test Types Separation

```
┌─────────────────────────────────────────────────────────────────┐
│                    TEST PYRAMID (Updated)                       │
│                                                                 │
│                       ┌───────────┐                             │
│                       │  Cucumber │  ← FROM PRD (Phase 1)       │
│                       │ Acceptance│    (.feature files)         │
│                     ┌─┴───────────┴─┐                           │
│                     │   GUI/E2E     │  ← DevTools MCP           │
│                     │   Tests       │    (Visual, Flows)        │
│                   ┌─┴───────────────┴─┐                         │
│                   │   Integration     │  ← Real DB, APIs        │
│                   │      Tests        │    (supertest, etc.)    │
│                 ┌─┴───────────────────┴─┐                       │
│                 │      Unit Tests       │  ← Fast, isolated     │
│                 │      (Backend)        │    (jest, vitest)     │
│                 └───────────────────────┘                       │
│                                                                 │
│  MORE tests at bottom, FEWER at top                             │
└─────────────────────────────────────────────────────────────────┘
```

| Layer | Source | Location | Tools | Speed | What to Test |
|-------|--------|----------|-------|-------|--------------|
| **Cucumber** | PRD feature files | `features/` | Cucumber.js | Slow | Acceptance criteria |
| **GUI/E2E** | Test plan | `tests/e2e/` | DevTools MCP | Slow | User flows, visual |
| **Integration** | Tech spec APIs | `tests/integration/` | Supertest, real DB | Medium | APIs, DB operations |
| **Unit** | Implementation | `tests/unit/` | Jest, Vitest | Fast | Functions, classes, logic |

> **Key Principle:** Cucumber tests ARE your acceptance criteria from PRD. The `.feature` files from Phase 1 become executable tests. Your job in Phase 4 is implementing the step definitions.

## The TDD Cycle

```
┌─────────────────────────────────────────────────────┐
│                                                     │
│    1. RED      →    2. GREEN    →    3. REFACTOR   │
│    Write test       Make it          Clean up      │
│    (fails)          pass             (tests pass)  │
│                                                     │
│         ↑                                 │        │
│         └─────────────────────────────────┘        │
│                     REPEAT                         │
└─────────────────────────────────────────────────────┘
```

| Phase | Action | Rule |
|-------|--------|------|
| **RED** | Write failing test | Test MUST fail first |
| **GREEN** | Write minimal code to pass | No extra features |
| **REFACTOR** | Clean up code | Tests still pass |

## Part 1: Backend & API Testing

### API Contract Testing (from Tech Spec)

```typescript
// Read from Tech Spec: API Design section
// docs/tech-spec/2024-06-15-user-auth.md

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

    // From Tech Spec: Response Schema
    expect(response.body).toEqual({
      token: expect.stringMatching(/^eyJ/),
      user: {
        id: expect.stringMatching(/^usr_/),
        email: 'user@example.com',
        role: expect.stringMatching(/^(admin|user)$/)
      },
      expiresIn: 3600
    });
  });

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

    expect(response.body).toEqual({
      error: 'INVALID_CREDENTIALS',
      message: 'Invalid email or password'
    });
  });

  // From Tech Spec: Rate Limiting
  test('returns 429 after 5 failed attempts', async () => {
    for (let i = 0; i < 5; i++) {
      await request(app)
        .post('/api/auth/login')
        .send({ email: 'user@example.com', password: 'wrong' });
    }

    const response = await request(app)
      .post('/api/auth/login')
      .send({ email: 'user@example.com', password: 'wrong' })
      .expect(429);

    expect(response.body.error).toBe('RATE_LIMITED');
  });
});
```

### Database Integration Testing

```typescript
// tests/integration/user.integration.test.ts
import { prisma } from '../setup/database';

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

  // From PRD: User Stories
  test('creates user with all required fields', async () => {
    const user = await userRepository.create({
      email: 'new@example.com',
      name: 'New User',
      password: '<test-password>'
    });

    // Verify in database
    const dbUser = await prisma.user.findUnique({
      where: { id: user.id }
    });

    expect(dbUser).not.toBeNull();
    expect(dbUser?.email).toBe('new@example.com');
    expect(dbUser?.passwordHash).not.toBe('SecurePass123!'); // Hashed!
  });

  // From Tech Spec: Data Constraints
  test('enforces unique email constraint', async () => {
    await userRepository.create({
      email: 'existing@example.com',
      name: 'First User'
    });

    await expect(userRepository.create({
      email: 'existing@example.com',
      name: 'Second User'
    })).rejects.toThrow('Email already exists');
  });
});
```

### Unit Testing (Business Logic)

```typescript
// tests/unit/orderCalculator.test.ts

describe('OrderCalculator', () => {
  // From PRD: Business Rules
  describe('calculateTotal', () => {
    test('applies percentage discount correctly', () => {
      const items = [
        { price: 100, quantity: 2 },
        { price: 50, quantity: 1 }
      ];

      const total = calculateTotal(items, { discountPercent: 10 });

      expect(total).toBe(225); // (200 + 50) * 0.9
    });

    // From Tech Spec: Edge Cases
    test('handles empty cart', () => {
      expect(calculateTotal([], {})).toBe(0);
    });

    test('rounds to 2 decimal places', () => {
      const items = [{ price: 10.333, quantity: 3 }];
      expect(calculateTotal(items, {})).toBe(31.00);
    });
  });
});
```

## Part 2: GUI Testing (DevTools MCP)

### DevTools MCP Integration

GUI tests use the **Chrome DevTools MCP** server for:
- Visual regression testing
- User flow testing
- Accessibility testing
- Performance monitoring

### GUI Test Structure

```typescript
// tests/e2e/login.e2e.test.ts
// Uses DevTools MCP for browser automation

describe('Login Page', () => {
  // From PRD: User Story - "As a user, I can log in"
  test('successful login redirects to dashboard', async () => {
    // DevTools MCP: Navigate to page
    await mcp.devtools.navigate('http://localhost:3000/login');

    // DevTools MCP: Fill form
    await mcp.devtools.type('#email', 'user@example.com');
    await mcp.devtools.type('#password', 'SecurePass123!');
    await mcp.devtools.click('#submit-btn');

    // DevTools MCP: Wait for navigation
    await mcp.devtools.waitForNavigation();

    // DevTools MCP: Verify URL
    const url = await mcp.devtools.getCurrentUrl();
    expect(url).toBe('http://localhost:3000/dashboard');

    // DevTools MCP: Verify element visible
    const welcomeText = await mcp.devtools.getText('.welcome-message');
    expect(welcomeText).toContain('Welcome');
  });

  // From PRD: Error handling
  test('shows error message for invalid credentials', async () => {
    await mcp.devtools.navigate('http://localhost:3000/login');
    await mcp.devtools.type('#email', 'user@example.com');
    await mcp.devtools.type('#password', 'wrong');
    await mcp.devtools.click('#submit-btn');

    // DevTools MCP: Wait for error
    await mcp.devtools.waitForSelector('.error-message');

    const errorText = await mcp.devtools.getText('.error-message');
    expect(errorText).toBe('Invalid email or password');
  });

  // Visual regression test
  test('login form matches design', async () => {
    await mcp.devtools.navigate('http://localhost:3000/login');

    // DevTools MCP: Take screenshot
    const screenshot = await mcp.devtools.screenshot();

    // Compare with baseline
    expect(screenshot).toMatchImageSnapshot();
  });
});
```

### Accessibility Testing (DevTools MCP)

```typescript
describe('Accessibility', () => {
  test('login page passes accessibility audit', async () => {
    await mcp.devtools.navigate('http://localhost:3000/login');

    // DevTools MCP: Run Lighthouse accessibility audit
    const audit = await mcp.devtools.runAccessibilityAudit();

    expect(audit.score).toBeGreaterThanOrEqual(90);
    expect(audit.violations).toHaveLength(0);
  });

  test('all form inputs have labels', async () => {
    await mcp.devtools.navigate('http://localhost:3000/login');

    const inputs = await mcp.devtools.querySelectorAll('input');
    for (const input of inputs) {
      const label = await mcp.devtools.getAttribute(input, 'aria-label');
      const labelledBy = await mcp.devtools.getAttribute(input, 'aria-labelledby');
      expect(label || labelledBy).toBeTruthy();
    }
  });
});
```

## Cucumber Integration Patterns

### Playwright + Cucumber (Browser Testing)

```typescript
// features/support/hooks.ts
import { Before, After, BeforeAll, AfterAll } from '@cucumber/cucumber';
import { chromium, Browser, Page } from 'playwright';

let browser: Browser;

BeforeAll(async function() {
  browser = await chromium.launch({ headless: true });
});

AfterAll(async function() {
  await browser.close();
});

Before(async function() {
  this.page = await browser.newPage();
});

After(async function(scenario) {
  // Screenshot on failure
  if (scenario.result?.status === 'FAILED') {
    const screenshot = await this.page.screenshot({ fullPage: true });
    this.attach(screenshot, 'image/png');
  }
  await this.page.close();
});
```

### API Testing + Cucumber

```typescript
// features/step-definitions/api.steps.ts
import { Given, When, Then } from '@cucumber/cucumber';
import request from 'supertest';
import { app } from '../../src/app';

When('I send a POST request to {string} with:', async function(endpoint: string, body: string) {
  this.response = await request(app)
    .post(endpoint)
    .send(JSON.parse(body))
    .set('Authorization', `Bearer ${this.token}`);
});

Then('the response status should be {int}', function(status: number) {
  expect(this.response.status).toBe(status);
});
```

### Database Hooks for Cucumber

```typescript
// features/support/database.ts
import { BeforeAll, Before, After } from '@cucumber/cucumber';
import { prisma } from '../../src/db';

BeforeAll(async function() {
  await prisma.$connect();
});

Before('@database', async function() {
  // Start transaction for test isolation
  await prisma.$executeRaw`BEGIN`;
});

After('@database', async function() {
  // Rollback to keep DB clean
  await prisma.$executeRaw`ROLLBACK`;
});
```

## Test File Organization

```
features/                         # Cucumber acceptance tests (FROM PRD)
├── auth/
│   └── login.feature
├── checkout/
│   └── cart.feature
├── step-definitions/
│   ├── auth.steps.ts
│   └── common.steps.ts
└── support/
    ├── world.ts
    └── hooks.ts

tests/
├── unit/                          # Fast, isolated tests
│   ├── services/
│   │   ├── userService.test.ts
│   │   └── orderService.test.ts
│   ├── utils/
│   │   └── validators.test.ts
│   └── models/
│       └── user.test.ts
│
├── integration/                   # API & DB tests
│   ├── api/
│   │   ├── auth.integration.test.ts
│   │   └── users.integration.test.ts
│   └── repositories/
│       └── userRepository.integration.test.ts
│
├── e2e/                          # GUI tests (DevTools MCP)
│   ├── flows/
│   │   ├── login.e2e.test.ts
│   │   ├── registration.e2e.test.ts
│   │   └── checkout.e2e.test.ts
│   ├── visual/
│   │   └── components.visual.test.ts
│   └── accessibility/
│       └── audit.a11y.test.ts
│
├── factories/                     # Test data factories
│   ├── userFactory.ts
│   └── orderFactory.ts
│
└── setup/
    ├── database.ts               # Test DB setup
    ├── mcp.ts                    # DevTools MCP setup
    └── jest.setup.ts

reports/                          # Cucumber reports
├── cucumber-report.html
└── cucumber-report.json
```

## Document-to-Test Mapping (Gherkin-First)

### From PRD → Cucumber Tests (Phase 1)

| PRD Artifact | Test Type | File Location | Created In |
|--------------|-----------|---------------|------------|
| User Stories | **Cucumber feature files** | `features/*.feature` | Phase 1 (PRD) |
| Acceptance Criteria | **Cucumber scenarios** | Inside `.feature` files | Phase 1 (PRD) |
| Error Scenarios | @error-handling scenarios | Inside `.feature` files | Phase 1 (PRD) |
| Edge Cases | @edge-case scenarios | Inside `.feature` files | Phase 1 (PRD) |

> **Key Insight:** You don't write acceptance test specs in Phase 4—they already exist! The `.feature` files from Phase 1 ARE your tests. Implement step definitions to make them pass.

### From Tech Spec → Backend Tests (Phase 4)

| Tech Spec Section | Test Type | File Location |
|-------------------|-----------|---------------|
| API Design | Contract tests |
| Data Model | DB integration tests |
| Error Handling | Error scenario tests |
| Security | Security tests |

### From Implementation Plan → Test Phases

| Plan Phase | Test Focus |
|------------|------------|
| Phase 1 | Unit tests for core logic |
| Phase 2 | Integration tests |
| Phase 3 | E2E tests |
| Phase 4 | Performance/load tests |

## Quick Commands

```bash
# Run all tests
npm test

# Run only unit tests
npm test -- --testPathPattern=unit

# Run only integration tests
npm test -- --testPathPattern=integration

# Run only E2E tests (requires DevTools MCP)
npm run test:e2e

# Run with coverage
npm test -- --coverage

# Run specific file
npm test -- path/to/test.ts
```

## Checklist Before Writing Tests

- [ ] Found latest PRD in `docs/prd/`
- [ ] Found latest Tech Spec in `docs/tech-spec/`
- [ ] Found latest Implementation Plan in `docs/implementation-plan/`
- [ ] Confirmed with user these are current documents
- [ ] Extracted user stories (→ GUI tests)
- [ ] Extracted API contracts (→ Backend tests)
- [ ] Extracted error scenarios (→ Error tests)
- [ ] Identified test phases from plan

## Anti-Patterns to Avoid

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

---

## Learning Mode Integration

### Decision Transparency Triggers
- **Test strategy choices**: Explain why specific test distribution chosen
- **Coverage decisions**: Show reasoning for coverage targets
- **Mock vs real**: Document when mocking is appropriate

### Debate Invitations
- **Test type balance**: When unit vs integration vs E2E trade-offs exist
- **Coverage targets**: When "good enough" vs "comprehensive" is unclear
- **Test data approach**: Factories vs fixtures vs inline data

### Feedback Requests
- After test suite written: Validate coverage completeness
- After test strategy defined: Confirm approach is appropriate
- At phase gate: Overall test quality rating (1-5)

### Example Transparency Block for Testing
```markdown
<decision-transparency>
**Decision:** Testing Trophy approach - 40% unit, 40% integration, 20% E2E

**Reasoning:**
- **CI time**: Full E2E would exceed 10 min target
- **Coverage balance**: Integration tests catch most real bugs
- **E2E focus**: Critical checkout path only

**Alternatives Considered:**
1. Heavy E2E (40%) - Rejected: CI too slow, tests too brittle
2. Heavy unit (80%) - Rejected: Misses integration issues

**Confidence:** High - Proven pattern for this type of app

**Open to Debate:** Yes - If CI time constraint changes
</decision-transparency>
```

### Example Debate Invitation for Testing
```markdown
<debate-invitation>
**Topic:** Test data strategy for user tests

**Option A: Inline Test Data**
- ✅ Pros: Easy to read, explicit
- ❌ Cons: Repetitive, hard to maintain

**Option B: Factory Functions**
- ✅ Pros: DRY, realistic data
- ❌ Cons: Slight indirection

**My Lean:** Option B - Factories produce realistic data consistently

**Your Input Needed:** Does team have factory pattern experience?
</debate-invitation>
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall