learning_ai_common_plat/AI.dev/PROMPTS/test-gap-analysis.md

---
name: test-gap-analysis
description: 'Identify test coverage gaps in a repo, prioritize by risk, and generate targeted tests for the most critical uncovered code.'
argument-hint: 'Repo name or path, e.g. "learning_ai_efforise", "learning_ai_flowmonk backend only", "all product backends"'
agent: agent
---

# Test Gap Analysis Prompt

Audit test coverage in a ByteLyst repo, identify the riskiest gaps, and generate high-value tests.

## Context — ByteLyst Testing Conventions

- **Runner:** Vitest for all TypeScript code
- **Pattern:** Tests live in `__tests__/` or alongside source as `<module>.test.ts`
- **Helpers:** `buildTestApp()` via `src/test-helpers.ts` for Fastify inject testing
- **Mocks:** `@bytelyst/testing` for shared mock utilities
- **Coverage targets:** Backend 80%, Web 70%, Shared packages 90%

## Analysis Protocol

### Step 1: Inventory

Scan the repo and build a map:

```
Source files:      N files
Test files:        M files
Coverage ratio:    M/N (% of source files with tests)
```

For each source module, classify:
- ✅ Has tests
- ⚠️ Has partial tests (some functions uncovered)
- ❌ No tests
- 🔒 Low risk (config, types-only, re-exports)
- 🔴 High risk (business logic, data mutations, auth)

### Step 2: Prioritize Gaps

Rank uncovered code by risk:

| Priority | Category | Why |
|----------|----------|-----|
| **P0** | Auth/security logic | Vulnerabilities if broken |
| **P0** | Data mutation (repository.ts) | Data corruption if broken |
| **P1** | Business logic (services, engines) | Core features break |
| **P1** | API routes with validation | Contract violations |
| **P2** | Utility functions | Indirect failures |
| **P3** | UI components (rendering) | Visual but not critical |
| **P4** | Config, types, re-exports | Very low risk |

### Step 3: Generate Tests

For each P0/P1 gap, generate tests following this structure:

```typescript
import { describe, it, expect, beforeEach, vi } from 'vitest';

describe('<Module>', () => {
  // Setup
  beforeEach(() => {
    // Fresh state for each test
  });

  // Happy path
  it('should <expected behavior> when <condition>', async () => {
    // Arrange
    // Act
    // Assert
  });

  // Validation
  it('should reject invalid input', async () => {
    // Test Zod schema validation
  });

  // Auth
  it('should enforce user ownership', async () => {
    // Test that user A cannot access user B's data
  });

  // Edge cases
  it('should handle <edge case>', async () => {
    // Empty arrays, null values, missing fields
  });

  // Error paths
  it('should throw NotFoundError for missing <entity>', async () => {
    // Test error handling
  });
});
```

### Step 4: Run & Validate

```bash
pnpm test --coverage
pnpm typecheck
```

### Step 5: Report

Output a coverage gap report:

```markdown
## Test Gap Analysis: <Repo>

### Summary
- Source files: N
- Test files: M (before) → M+K (after)
- Coverage: X% → Y%

### Gaps Filled (this session)
| Module | Tests Added | Risk Level |
|--------|-------------|------------|

### Remaining Gaps
| Module | Risk Level | Effort | Suggested Next Step |
|--------|------------|--------|---------------------|

### Recommendations
1. ...
2. ...
```

### Step 6: Commit

```bash
git add .
git commit -m "test(<scope>): fill coverage gaps in <modules>

- Added N tests across M modules
- Coverage: X% → Y%
- Focus: <P0/P1 risk areas addressed>"
git push
```

## Anti-Patterns to Avoid

- ❌ Don't write snapshot tests for API responses (too brittle)
- ❌ Don't test private implementation details (test behavior, not internals)
- ❌ Don't mock the thing you're testing (mock dependencies only)
- ❌ Don't write tests that always pass regardless of code changes
- ❌ Don't chase 100% coverage — focus on high-risk code