Test Coverage Plan

Last updated: 2026-06-28

Status measured on 2026-05-13: lines 82.58%, statements 82.58%, functions 84.23%, branches 75.22%. Phases 1-5 are complete. Current focus is Phase 6 (>=85%) and Phase 7 (>=90%).

Baseline

There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful.

The recommended baseline is the number to optimize against.

Rules

• Coverage targets apply to source files, not to tests/**.
• open-sse/** is part of the product and must remain in scope.
• New code should not reduce coverage in touched areas.
• Prefer testing behavior and branch outcomes over implementation details.
• Prefer temp SQLite databases and small fixtures over broad mocks for src/lib/db/**.

Current command set

• npm run test:coverage
  • Main source coverage gate for the unit test suite
  • Generates text-summary, html, json-summary, and lcov
• npm run coverage:report
  • Detailed file-by-file report from the latest run
• npm run test:coverage:legacy
  • Historical comparison only

Milestones

Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines.

Priority hotspots

These files have the lowest line coverage today (< 60%) and offer the best return for Phases 6-7. Generated from coverage/coverage-summary.json on 2026-05-13:

Themes for Phases 6-7:

• open-sse/services/compression/** is the densest cluster of low coverage and dominates the remaining gap.
• Batch and rerank API routes (src/app/api/v1/batches/**, src/app/api/v1/rerank/route.ts) need handler-level tests.
• Cloud agent adapters (src/lib/cloudAgent/agents/jules.ts, codex.ts) and tierResolver.ts need scenario tests.
• Docs UI components and src/mitm/systemCommands.ts are lower priority but cheap branch wins.

Execution checklist

Phase 1: 56.95% -> 60%

• Fix coverage metric so it reflects source code instead of test files
• Keep a legacy coverage script for comparison
• Record the baseline and hotspots in-repo
• Add focused tests for low-risk utilities:
  • src/shared/utils/upstreamError.ts
  • src/shared/utils/fetchTimeout.ts
  • src/lib/api/errorResponse.ts
  • src/shared/utils/apiAuth.ts
  • src/lib/display/names.ts
• Add route tests for:
  • src/app/api/settings/require-login/route.ts
  • src/app/api/providers/[id]/models/route.ts

Phase 2: 60% -> 65%

• Add DB-backed tests for:
  • src/lib/db/modelComboMappings.ts
  • src/lib/db/settings.ts
  • src/lib/db/registeredKeys.ts
• Cover branch behavior in:
  • src/lib/providers/validation.ts
  • src/app/api/v1/embeddings/route.ts
  • src/app/api/v1/moderations/route.ts

Phase 3: 65% -> 70%

• Add usage analytics tests for:
  • src/lib/usage/usageHistory.ts
  • src/lib/usage/usageStats.ts
  • src/lib/usage/costCalculator.ts
• Expand route coverage for proxy management and settings branches

Phase 4: 70% -> 75%

• Cover translator helpers and central translation paths:
  • open-sse/translator/index.ts
  • open-sse/translator/helpers/*
  • open-sse/translator/request/*
  • open-sse/translator/response/*

Phase 5: 75% -> 80%

• Add handler-level tests for:
  • open-sse/handlers/chatCore.ts
  • open-sse/handlers/responsesHandler.js
  • open-sse/handlers/imageGeneration.js
  • open-sse/handlers/embeddings.js
• Add executor branch coverage for provider-specific auth, retries, and endpoint overrides

Phase 6: 80% -> 85%

• Merge more edge-case suites into the main coverage path
• Increase function coverage for DB modules with weak constructor/helper coverage
• Close branch gaps in settings.ts, registeredKeys.ts, validation.ts, and translator helpers

Phase 7: 85% -> 90%

• Treat the remaining low-coverage files as blockers
• Add regression tests for every uncovered production bug fixed during the push to 90%
• Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs

Ratchet policy

Update npm run test:coverage thresholds only after the project actually exceeds the next milestone with a comfortable buffer.

Current gate: npm run test:coverage enforces 60 statements / 60 lines / 60 functions / 60 branches (the metric was rebased in Quality-Gates Fase 6A.1 — the earlier 82.58% baseline was inflated because it counted test files and excluded open-sse). The test:coverage:legacy command preserves the old 50/50/50 metric for historical comparison.

For ad-hoc threshold checks against the latest report use:

node scripts/check/test-report-summary.mjs --threshold 75

Recommended ratchet sequence (order is statements-lines / branches / functions):

1. 55/60/55
2. 60/62/58
3. 65/64/62
4. 70/66/66
5. 75/70/72 <-- current gate (75/70/75)
6. 80/75/78
7. 85/80/84
8. 90/85/88

Next ratchet target is 80/75/78 once branch coverage holds above 78% for two consecutive runs.

Known gap

The current coverage command measures the main Node unit suite and includes source reached from it, including open-sse. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb.