OmniRoute/docs/COVERAGE_PLAN.md

Test Coverage Plan

Last updated: 2026-03-28

Baseline

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

Metric	Scope	Statements / Lines	Branches	Functions	Notes
Legacy	Old npm run test:coverage	79.42%	75.15%	67.94%	Inflated: counts test files and excludes open-sse
Diagnostic	Source-only, excluding tests and excluding open-sse	68.16%	63.55%	64.06%	Useful only to isolate src/**
Recommended baseline	Source-only, excluding tests and including open-sse	56.95%	66.05%	57.80%	This is the project-wide baseline to improve

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

Phase	Target	Focus
Phase 1	60% statements / lines	Quick wins and low-risk utility coverage
Phase 2	65% statements / lines	DB and route foundations
Phase 3	70% statements / lines	Provider validation and usage analytics
Phase 4	75% statements / lines	open-sse translators and helpers
Phase 5	80% statements / lines	open-sse handlers and executor branches
Phase 6	85% statements / lines	Harder edge cases, branch debt, regression suites
Phase 7	90% statements / lines	Final sweep, gap closure, strict ratchet

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

Priority hotspots

These files or areas offer the best return for the next phases:

1. open-sse/handlers
   • chatCore.ts at 7.57%
   • Overall directory at 29.07%
2. open-sse/translator/request
   • Overall directory at 36.39%
   • Many translators are still near single-digit coverage
3. open-sse/translator/response
   • Overall directory at 8.07%
4. open-sse/executors
   • Overall directory at 36.62%
5. src/lib/db
   • models.ts at 20.66%
   • registeredKeys.ts at 34.46%
   • modelComboMappings.ts at 36.25%
   • settings.ts at 46.40%
   • webhooks.ts at 33.33%
6. src/lib/usage
   • usageHistory.ts at 21.12%
   • usageStats.ts at 9.56%
   • costCalculator.ts at 30.00%
7. src/lib/providers
   • validation.ts at 41.16%
8. Low-risk utility and API files for early gains
   • src/shared/utils/upstreamError.ts
   • src/shared/utils/apiAuth.ts
   • src/lib/api/errorResponse.ts
   • src/app/api/settings/require-login/route.ts
   • src/app/api/providers/[id]/models/route.ts

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.

Recommended ratchet sequence:

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

Order is statements-lines / branches / functions.

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.