Test Coverage

Purpose: Ensure test coverage for changed code Phases: Analyze → Design → Write → Run → Report Usage: /test-coverage [scope flags]

Iron Laws

1. •EVERY CHANGED FUNCTION NEEDS A TEST — No exceptions for "simple" code. Simple code that breaks causes the worst outages because nobody thought to test it.
2. •TESTS MUST BE INDEPENDENT — No shared mutable state, no test ordering dependencies. Every test must pass when run alone.
3. •TEST BEHAVIOR, NOT IMPLEMENTATION — Test what the code does, not how it does it. Refactoring should not break tests.

When to Use

• •After implementing a feature (post /implement)
• •When adding tests to existing uncovered code
• •Before submitting a PR to ensure coverage
• •When a bug fix needs regression tests

When NOT to Use

• •Writing tests before code → /tdd
• •Debugging a test failure → /debug
• •Full CI validation → /validate

Constraints

• •Create test files (.spec.ts, .test.ts) freely
• •Do not modify non-test source files without approval
• •Scope tests to changes — don't run full suites unless necessary
• •Every test file MUST include a test plan as a comment

Note: Command examples use npm as default. Adapt to the project's package manager per ai-assistant-protocol — Project Commands.

Scope Flags

Test Quality Criteria

Don't Test

• •Types / interfaces — no runtime behavior
• •Trivial getters/setters — one-line property access with no logic
• •Framework internals — React rendering, Express routing itself
• •Constants / enums — static values
• •Generated code — Prisma client, GraphQL codegen

Test Smell Detection

Coverage Targets

Workflow

Step 1: Analyze Changes

MAIN_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
git diff --name-only $MAIN_BRANCH..HEAD

Step 2: Categorize and Identify Missing Coverage

Step 3: Design Test Plans

For each file needing tests:

## Test Plan: [ModuleName]

| Function | Behaviors | Edge Cases |
|----------|-----------|------------|
| `functionA` | happy path, error path | null input, empty array |

Step 4: Write Tests

Required test plan (Gherkin) as comment:

/**
 * Test Plan: ModuleName
 *
 * Scenario: Brief description
 *   Given [initial state]
 *   When [action]
 *   Then [expected outcome]
 */

Test structure:

describe('ModuleName', () => {
  describe('functionName', () => {
    it('should [expected behavior] when [condition]', () => {
      // Arrange
      // Act
      // Assert
    });
  });
});

Coverage priorities: Happy path → Edge cases (null, empty, boundary) → Error conditions → Async operations

For utilities with well-defined contracts, consider property-based testing (e.g., with fast-check) to catch edge cases that example-based tests miss.

Step 5: Run and Fix

npm run test -- path/to/file.spec.ts

If failures: fix mocks, assertions, missing await, or isolation issues. Re-run until green.

Step 6: Report

## Test Coverage Report

### Tests Created
- utility.spec.ts — 8 tests, all passing
- service.spec.ts — 5 tests, all passing

### Skipped (No Tests Needed)
- types.ts — type definitions only

### Test Quality Check
| Criterion | Status |
|-----------|--------|
| Independent | ✓ |
| Fast | ✓ |
| Focused | ✓ |
| Deterministic | ✓ |

Quick Reference