Test Coverage

Test Coverage

Purpose: Ensure test coverage for changed code Phases: Analyze → Discover → Baseline → Design → Write → Run → Measure → 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=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
git diff --name-only $MAIN_BRANCH..HEAD

Step 2: Categorize and Identify Missing Coverage

Early exit: If all changed files are type-only (interfaces, type definitions, enums, constants), config-only, or already have adequate test coverage, report this and exit:

## Nothing to Test

All changed files are either type-only definitions or already have adequate coverage:
- `types/user.ts` — type definitions only (skip)
- `services/auth.service.ts` — existing tests cover changes (skip)

No new tests needed.

Step 3: Discover Test Patterns

Before writing any tests, discover where existing tests live and what patterns they use:

1. File naming: Search for *.spec.ts, *.test.ts, *.spec.tsx, *.test.tsx to determine the project convention
2. Directory structure: Check if tests are co-located with source files or in separate __tests__/ directories
3. Import patterns: Note how modules under test are imported (relative paths, aliases, barrel imports)
4. Mock patterns: Identify how dependencies are mocked (manual mocks, vi.mock(), jest.mock(), dependency injection)

Read 1-2 existing test files that are closest to the files being tested (same directory or same file type) and adopt their:

• describe/it nesting structure
• Setup/teardown patterns (beforeEach, afterEach, factories)
• Assertion style (expect().toBe(), expect().toEqual(), custom matchers)
• Mock approach (inline mocks, shared fixtures, mock factories)

If no existing test files are found, use the default structure in Step 6.

Step 4: Measure Coverage Baseline

Check if the project has coverage tooling configured:

1. Look for coverage configuration in vitest.config.*, jest.config.*, package.json (jest/vitest sections), or .nycrc
2. Check package.json scripts for a coverage command (e.g., test:coverage, coverage)

If coverage tooling is available, run coverage on affected files to establish a baseline:

# Vitest example
npm run test -- --coverage --run <affected-pattern>

# Jest example
npm run test -- --coverage --collectCoverageFrom='<affected-pattern>' --forceExit

Record the baseline coverage percentages for affected files. If no coverage tooling exists, note this in the final report and proceed without numeric measurements.

Step 5: 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 6: Write Tests

Required test plan (Gherkin) as comment:

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

Test structure (default — override with patterns discovered in Step 3):

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 7: 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 8: Measure Coverage After

If coverage tooling was available in Step 4, re-run coverage to show improvement:

npm run test -- --coverage --run <affected-pattern>

Compare before vs after for each affected file. Record the delta.

If coverage tooling is not available, skip this step — the report in Step 9 will note that numeric coverage was not measurable.

Step 9: Report and Approve

Present the coverage report and wait for user approval before committing.

## Test Coverage Report

### Coverage Summary (if measurable)
| File | Before | After | Delta |
|------|--------|-------|-------|
| `services/user.service.ts` | 12% | 85% | +73% |
| `utils/validator.ts` | 0% | 92% | +92% |

### Tests Created
- `user.service.spec.ts` — 8 tests, all passing
- `validator.spec.ts` — 5 tests, all passing

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

### Remaining Gaps
- `user.service.ts` line 45-52: error recovery branch (edge case, low risk)

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

GATE: Do NOT commit until user responds with explicit approval. See ai-assistant-protocol for valid approval terms and invalid responses.

Acceptance Tests

Quick Reference

Converted and distributed by TomeVault — claim your Tome and manage your conversions.