Skip to content

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

test-driven

Unverified

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.

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 (Updated)

      ┌─────────────────┐
      │    Cucumber     │  ← FROM PRD (Phase 1) - Acceptance tests
      │   Acceptance    │  ← Fewest tests, slowest
      │  .feature files │  ← Highest business value
    ┌─┴─────────────────┴─┐
    │   GUI / E2E Tests   │  ← DevTools MCP
    │  (Visual, Flows)    │  ← User journey tests
  ┌─┴─────────────────────┴─┐
  │   Integration Tests     │  ← Real DB, APIs
  │   (API, Database)       │  ← Medium speed
┌─┴─────────────────────────┴─┐
│       Unit Tests            │  ← Fast, isolated
│   (Functions, Logic)        │  ← Most tests
└─────────────────────────────┘

MORE tests at bottom, FEWER at top
LayerSourceLocationToolsSpeed
CucumberPRD feature filesfeatures/Cucumber.jsSlow
GUI/E2ETest plantests/e2e/DevTools MCPSlow
IntegrationTech spec APIstests/integration/Supertest, real DBMedium
UnitImplementationtests/unit/Jest, VitestFast

Key Principle: Cucumber tests ARE your acceptance criteria. The .feature files from PRD are your tests. Your job in Phase 4 is to implement the step definitions.

TDD Cycle

RED (Write failing test) -> GREEN (Make pass) -> REFACTOR (Clean up) -> REPEAT
PhaseActionRule
REDWrite failing testMUST fail first
GREENMinimal code to passNo extra features
REFACTORClean upTests still pass

BDD Test Execution (Cucumber)

Cucumber executes the acceptance criteria written during Phase 1 (PRD). Each .feature file in features/ becomes an executable test.

Commands

CommandWhen to UseWhat It Does
npm run cucumberLocal developmentRuns all features with progress bar
npm run cucumber:dryAfter writing featuresValidates Gherkin syntax, shows undefined steps
npm run test:bddBefore PRRuns all + generates HTML report
npm run test:smokeQuick checkRuns only @smoke tagged scenarios
npm run test:criticalRelease gateRuns only @critical scenarios

TDD with Cucumber

1. Write feature (Phase 1 - PRD)  → features/auth/login.feature
2. Run dry-run                    → npm run cucumber:dry → See undefined steps
3. Implement steps                → features/step-definitions/auth.steps.ts
4. Run tests                      → npm run cucumber → Should pass
5. Generate report                → npm run test:bdd → Review HTML report

Note: Feature files should already exist from Phase 1 PRD. Your job in Phase 4 is to implement the step definitions that make them pass.

Tag Filtering

# Run scenarios by tag
npx cucumber-js --tags "@critical"
npx cucumber-js --tags "@smoke or @critical"
npx cucumber-js --tags "not @wip and not @manual"

# Run specific feature file
npx cucumber-js features/auth/login.feature

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: '<test-password>' })
      .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 (Gherkin-First)

PRD → Tests

PRD ArtifactTest TypeFile LocationCreated In
User StoriesCucumber feature filesfeatures/*.featurePhase 1 (PRD)
Acceptance CriteriaCucumber scenariosInside .feature filesPhase 1 (PRD)
Error Scenarios@error-handling scenariosInside .feature filesPhase 1 (PRD)
Edge Cases@edge-case scenariosInside .feature filesPhase 1 (PRD)

Tech Spec → Tests

Tech Spec ArtifactTest TypeFile LocationCreated In
API ContractsIntegration teststests/integration/api/Phase 4 (Dev)
Database SchemaDB integration teststests/integration/db/Phase 4 (Dev)
Error ResponsesError scenario teststests/integration/errors/Phase 4 (Dev)
Business LogicUnit teststests/unit/Phase 4 (Dev)

Key Insight

You don't write acceptance test specs in Phase 4—they already exist!

The .feature files created in Phase 1 (PRD) ARE your acceptance tests. In Phase 4, you implement the step definitions to make them pass. This is the power of Gherkin: requirements = tests.

Commands

# Cucumber (BDD Acceptance Tests)
npm run cucumber                   # Run all features
npm run cucumber:dry               # Validate Gherkin syntax
npm run test:bdd                   # Run + generate HTML report
npm run test:smoke                 # Run @smoke scenarios
npm run test:critical              # Run @critical scenarios

# Unit/Integration Tests
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

Cucumber (from PRD)

  • Feature files exist in features/ directory
  • npm run cucumber:dry shows undefined steps to implement
  • Research backing comments in feature files
  • Appropriate @tags on all scenarios

Other Tests

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

Anti-Patterns

Anti-PatternProblemFix
Testing implementationBrittleTest behavior/outcomes
Unrealistic mock dataMiss edge casesUse realistic factories
Only happy pathMiss errorsTest edge cases & errors
Order-dependent testsFlakyMake independent
Over-mockingMiss bugsReal integrations (<20% mocking)
Weak assertionsFalse positivesAssert exact values
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall