claude-autopm 2.8.2 → 2.8.3

package/packages/plugin-testing/rules/test-coverage-requirements.md

@@ -0,0 +1,581 @@
+# Test Coverage Requirements Rule
+
+**Rule Name**: test-coverage-requirements
+**Priority**: High
+**Applies To**: commands, agents
+**Enforces On**: frontend-testing-engineer
+
+## Description
+
+Test coverage thresholds and quality metrics enforcement. This rule defines mandatory coverage requirements for all code changes and ensures coverage metrics meet industry standards based on Context7-verified best practices.
+
+## Context7 Documentation Sources
+
+**MANDATORY:** Coverage requirements based on these Context7 sources:
+
+- `/vitest-dev/vitest` - Coverage configuration and thresholds
+- `/testing-library/testing-library-docs` - Test quality metrics
+- `/istanbul/istanbuljs` - Coverage reporting standards
+- `/c8/c8` - V8 coverage provider patterns
+
+## Coverage Thresholds
+
+### Global Thresholds (MANDATORY)
+
+**All new code must meet these minimum thresholds:**
+
+```javascript
+// vitest.config.js or jest.config.js
+export default {
+  test: {
+    coverage: {
+      provider: 'v8', // or 'istanbul'
+
+      // MANDATORY minimum thresholds
+      thresholds: {
+        lines: 80,        // 80% of lines must be covered
+        functions: 80,    // 80% of functions must be tested
+        branches: 75,     // 75% of branches must be covered
+        statements: 80    // 80% of statements must be executed
+      },
+
+      // Fail tests if thresholds not met
+      reporter: ['text', 'json', 'html', 'lcov'],
+
+      // Include only source code
+      include: ['src/**/*.{js,jsx,ts,tsx}'],
+
+      // Exclude non-testable code
+      exclude: [
+        'node_modules/',
+        'test/',
+        '**/*.config.js',
+        '**/*.spec.js',
+        '**/*.test.js',
+        'src/main.{js,ts}',
+        'src/index.{js,ts}',
+        'src/**/*.d.ts'
+      ]
+    }
+  }
+};
+```
+
+### Per-Directory Thresholds (RECOMMENDED)
+
+**Critical directories require higher coverage:**
+
+```javascript
+// Higher thresholds for critical code
+coverage: {
+  thresholds: {
+    // Global minimum
+    global: {
+      lines: 80,
+      functions: 80,
+      branches: 75,
+      statements: 80
+    },
+
+    // Critical business logic - higher standards
+    './src/services/': {
+      lines: 90,
+      functions: 90,
+      branches: 85,
+      statements: 90
+    },
+
+    // UI components - focus on user interactions
+    './src/components/': {
+      lines: 85,
+      functions: 85,
+      branches: 80,
+      statements: 85
+    },
+
+    // Utilities - comprehensive coverage
+    './src/utils/': {
+      lines: 95,
+      functions: 95,
+      branches: 90,
+      statements: 95
+    }
+  }
+}
+```
+
+## Coverage Quality Standards
+
+### Lines vs. Branches
+
+```
+Understanding Coverage Metrics:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Line Coverage: Were all lines executed?
+   - ✅ Good indicator of basic coverage
+   - ❌ Doesn't ensure all paths tested
+
+📊 Branch Coverage: Were all code paths tested?
+   - ✅ Tests if/else, switch, ternary operators
+   - ✅ Better indicator of thorough testing
+   - ⚠️  More important than line coverage
+
+📊 Function Coverage: Were all functions called?
+   - ✅ Ensures no dead code
+   - ✅ Validates all exports are used
+
+📊 Statement Coverage: Were all statements executed?
+   - ✅ Similar to line coverage
+   - ✅ More granular (multiple statements per line)
+
+💡 Priority: Branch > Functions > Lines > Statements
+```
+
+### Example: Why Branch Coverage Matters
+
+```javascript
+// Function with 100% line coverage but poor branch coverage
+function processUser(user) {
+  if (user.isActive) {
+    return user.name;  // Line covered ✓
+  } else {
+    return 'Inactive'; // Line NOT covered ✗
+  }
+}
+
+// ❌ INSUFFICIENT: Only 50% branch coverage
+test('returns name for active user', () => {
+  expect(processUser({ isActive: true, name: 'John' })).toBe('John');
+  // Only tests the 'if' branch, not 'else'
+});
+
+// ✅ CORRECT: 100% branch coverage
+test('returns name for active user', () => {
+  expect(processUser({ isActive: true, name: 'John' })).toBe('John');
+});
+
+test('returns "Inactive" for inactive user', () => {
+  expect(processUser({ isActive: false, name: 'John' })).toBe('Inactive');
+});
+```
+
+## Mandatory Coverage Checks
+
+### Pre-Commit Hook (MANDATORY)
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Run tests with coverage
+npm run test:coverage > /dev/null 2>&1
+
+# Extract coverage percentage
+COVERAGE=$(node -e "
+  const data = require('./coverage/coverage-summary.json');
+  console.log(data.total.lines.pct);
+")
+
+# Check threshold
+THRESHOLD=80
+
+if (( $(echo "$COVERAGE < $THRESHOLD" | bc -l) )); then
+  echo "❌ Coverage $COVERAGE% is below $THRESHOLD% threshold"
+  echo "   Run 'npm run test:coverage' for details"
+  exit 1
+fi
+
+echo "✅ Coverage: $COVERAGE%"
+exit 0
+```
+
+### Pull Request Check (MANDATORY)
+
+```yaml
+# .github/workflows/coverage.yml
+name: Coverage Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold
+        run: |
+          LINES=$(node -e "console.log(require('./coverage/coverage-summary.json').total.lines.pct)")
+          BRANCHES=$(node -e "console.log(require('./coverage/coverage-summary.json').total.branches.pct)")
+
+          echo "Lines: $LINES%"
+          echo "Branches: $BRANCHES%"
+
+          if (( $(echo "$LINES < 80" | bc -l) )); then
+            echo "❌ Line coverage below 80%"
+            exit 1
+          fi
+
+          if (( $(echo "$BRANCHES < 75" | bc -l) )); then
+            echo "❌ Branch coverage below 75%"
+            exit 1
+          fi
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: true
+
+      - name: Comment PR with coverage
+        uses: romeovs/lcov-reporter-action@v0.3.1
+        with:
+          lcov-file: ./coverage/lcov.info
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          filter-changed-files: true
+```
+
+## Coverage Exceptions
+
+### When to Exclude Code
+
+**Legitimate exclusions (must be documented):**
+
+```javascript
+// ✅ CORRECT: Exclude defensive error handling for impossible cases
+function processData(data) {
+  /* istanbul ignore next */
+  if (!data) {
+    throw new Error('Data is required'); // Can't happen in practice
+  }
+
+  return data.map(item => item.value);
+}
+
+// ✅ CORRECT: Exclude debug-only code
+function debugLog(message) {
+  /* istanbul ignore if */
+  if (process.env.NODE_ENV === 'development') {
+    console.log(message); // Not covered in test environment
+  }
+}
+
+// ✅ CORRECT: Exclude type guards that TypeScript ensures
+function isString(value: unknown): value is string {
+  /* istanbul ignore next */
+  return typeof value === 'string'; // TypeScript handles this
+}
+```
+
+**Invalid exclusions (not allowed):**
+
+```javascript
+// ❌ WRONG: Excluding untested business logic
+function calculateDiscount(price, user) {
+  /* istanbul ignore next */
+  if (user.isPremium) {
+    return price * 0.8; // Should be tested!
+  }
+
+  return price;
+}
+
+// ❌ WRONG: Excluding error handling
+async function fetchUser(id) {
+  try {
+    return await api.getUser(id);
+  } catch (error) {
+    /* istanbul ignore next */
+    throw new Error('Failed to fetch user'); // Should be tested!
+  }
+}
+```
+
+## Coverage Reporting Standards
+
+### Required Reports (MANDATORY)
+
+```javascript
+coverage: {
+  reporter: [
+    'text',        // Terminal output (for developers)
+    'text-summary',// Quick summary
+    'json',        // Machine-readable (for CI)
+    'json-summary',// Quick machine-readable
+    'html',        // Visual report (for deep dive)
+    'lcov'         // For coverage services (Codecov, Coveralls)
+  ],
+
+  // Report directory
+  reportsDirectory: './coverage',
+
+  // Always clean before new run
+  clean: true
+}
+```
+
+### Coverage Trend Tracking
+
+```javascript
+// scripts/track-coverage.js
+import { readFileSync, writeFileSync } from 'fs';
+
+const summary = JSON.parse(
+  readFileSync('./coverage/coverage-summary.json', 'utf-8')
+);
+
+const trend = {
+  date: new Date().toISOString(),
+  lines: summary.total.lines.pct,
+  branches: summary.total.branches.pct,
+  functions: summary.total.functions.pct,
+  statements: summary.total.statements.pct
+};
+
+// Append to history
+const history = JSON.parse(
+  readFileSync('./coverage/history.json', 'utf-8')
+);
+history.push(trend);
+
+writeFileSync(
+  './coverage/history.json',
+  JSON.stringify(history, null, 2)
+);
+
+// Check if coverage decreased
+const previous = history[history.length - 2];
+if (previous && trend.lines < previous.lines) {
+  console.error(`❌ Coverage decreased from ${previous.lines}% to ${trend.lines}%`);
+  process.exit(1);
+}
+```
+
+## Coverage for Different Code Types
+
+### Components (85% minimum)
+
+```javascript
+// ✅ REQUIRED: Test all component states
+describe('LoadingButton', () => {
+  test('shows button text when not loading', () => {
+    render(<LoadingButton>Submit</LoadingButton>);
+    expect(screen.getByRole('button', { name: 'Submit' })).toBeInTheDocument();
+  });
+
+  test('shows spinner when loading', () => {
+    render(<LoadingButton loading>Submit</LoadingButton>);
+    expect(screen.getByRole('status')).toBeInTheDocument();
+  });
+
+  test('is disabled when loading', () => {
+    render(<LoadingButton loading>Submit</LoadingButton>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  test('is disabled when disabled prop is true', () => {
+    render(<LoadingButton disabled>Submit</LoadingButton>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  test('calls onClick when clicked', async () => {
+    const onClick = vi.fn();
+    render(<LoadingButton onClick={onClick}>Submit</LoadingButton>);
+
+    await userEvent.click(screen.getByRole('button'));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Services/API (90% minimum)
+
+```javascript
+// ✅ REQUIRED: Test all API methods and error cases
+describe('UserService', () => {
+  test('fetches user by ID', async () => {
+    const user = await UserService.getUser(1);
+    expect(user).toEqual({ id: 1, name: 'Test User' });
+  });
+
+  test('creates new user', async () => {
+    const newUser = await UserService.createUser({ name: 'John' });
+    expect(newUser).toHaveProperty('id');
+    expect(newUser.name).toBe('John');
+  });
+
+  test('updates existing user', async () => {
+    const updated = await UserService.updateUser(1, { name: 'Jane' });
+    expect(updated.name).toBe('Jane');
+  });
+
+  test('deletes user', async () => {
+    await expect(UserService.deleteUser(1)).resolves.toBeUndefined();
+  });
+
+  test('handles network errors', async () => {
+    server.use(
+      rest.get('/api/user/:id', (req, res, ctx) => {
+        return res(ctx.status(500));
+      })
+    );
+
+    await expect(UserService.getUser(1)).rejects.toThrow('Network error');
+  });
+
+  test('handles validation errors', async () => {
+    await expect(
+      UserService.createUser({ name: '' })
+    ).rejects.toThrow('Name is required');
+  });
+});
+```
+
+### Utilities (95% minimum)
+
+```javascript
+// ✅ REQUIRED: Test all utility functions and edge cases
+describe('formatCurrency', () => {
+  test('formats positive numbers', () => {
+    expect(formatCurrency(1234.56)).toBe('$1,234.56');
+  });
+
+  test('formats zero', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+
+  test('formats negative numbers', () => {
+    expect(formatCurrency(-1234.56)).toBe('-$1,234.56');
+  });
+
+  test('rounds to 2 decimal places', () => {
+    expect(formatCurrency(1234.567)).toBe('$1,234.57');
+  });
+
+  test('handles very large numbers', () => {
+    expect(formatCurrency(1234567890.12)).toBe('$1,234,567,890.12');
+  });
+
+  test('handles very small numbers', () => {
+    expect(formatCurrency(0.01)).toBe('$0.01');
+  });
+
+  test('throws error for invalid input', () => {
+    expect(() => formatCurrency('invalid')).toThrow('Invalid number');
+    expect(() => formatCurrency(NaN)).toThrow('Invalid number');
+    expect(() => formatCurrency(null)).toThrow('Invalid number');
+  });
+});
+```
+
+## Mutation Testing (RECOMMENDED)
+
+```bash
+# Install Stryker mutation testing
+npm install -D @stryker-mutator/core @stryker-mutator/vitest-runner
+
+# stryker.config.json
+{
+  "testRunner": "vitest",
+  "coverageAnalysis": "perTest",
+  "mutate": [
+    "src/**/*.{js,jsx,ts,tsx}",
+    "!src/**/*.{spec,test}.{js,jsx,ts,tsx}"
+  ],
+  "thresholds": {
+    "high": 80,
+    "low": 60,
+    "break": 50
+  }
+}
+
+# Run mutation testing
+npx stryker run
+```
+
+**Why Mutation Testing:**
+- Validates test quality, not just coverage
+- Finds weak tests that don't catch bugs
+- Mutates code and checks if tests fail
+- Higher mutation score = better tests
+
+## Enforcement Checklist
+
+Before merging code, verify:
+
+- [ ] Overall coverage meets 80% minimum
+- [ ] Branch coverage meets 75% minimum
+- [ ] No decrease in coverage from previous commit
+- [ ] All new files have corresponding tests
+- [ ] Coverage report generated and reviewed
+- [ ] Critical paths have 90%+ coverage
+- [ ] Error handling is tested
+- [ ] Edge cases are covered
+- [ ] Coverage exclusions are documented
+- [ ] CI/CD coverage check passes
+
+## Validation Commands
+
+```bash
+# Generate coverage report
+npm run test:coverage
+
+# Check coverage thresholds (fails if below)
+npm run test:coverage -- --reporter=json
+
+# View detailed HTML report
+open coverage/index.html
+
+# Track coverage trend
+node scripts/track-coverage.js
+```
+
+## Coverage Improvement Strategies
+
+### Identify Low Coverage Areas
+
+```bash
+# Find files with < 80% coverage
+node -e "
+  const data = require('./coverage/coverage-summary.json');
+  Object.entries(data)
+    .filter(([file, d]) => d.lines.pct < 80 && file !== 'total')
+    .forEach(([file, d]) => console.log(\`\${file}: \${d.lines.pct}%\`));
+"
+```
+
+### Prioritize High-Impact Tests
+
+1. **Critical Business Logic** (highest priority)
+2. **Error Handling** (prevents crashes)
+3. **Edge Cases** (prevents bugs)
+4. **Happy Path** (ensures core functionality)
+
+## Related Rules
+
+- `testing-standards` - Test quality and patterns
+- `code-quality-standards` - General code quality
+- `ci-cd-requirements` - CI/CD integration rules
+
+## Support
+
+For coverage questions:
+- Review Context7 documentation for coverage tools
+- Run `/test:coverage` command for detailed analysis
+- Consult frontend-testing-engineer agent