How to Run Tests in OmniRoute: Complete Guide to Unit, Vitest, E2E, and Protocol Testing

Run tests in OmniRoute using npm scripts defined in package.json, including npm run test:unit for core unit tests, npm run test:vitest for MCP and routing validation, and npm run test:all to execute the full suite.

Testing in OmniRoute is orchestrated through a comprehensive npm script system that covers every layer of the application. The repository, maintained at diegosouzapw/OmniRoute, ships with approximately 21,000 test cases spanning unit tests, Vitest-based integration tests, Playwright end-to-end tests, and protocol-level validation for A2A and MCP transports. Understanding how to run tests in OmniRoute ensures code quality before any deployment.

Available Test Scripts in package.json

All test commands are defined in package.json around lines 100–105. Each script targets a specific testing concern:

Script	Purpose	When to Use
npm run test:unit	Executes Node.js unit tests (~21,000 cases) with SQLite auto-backup disabled for speed	Before any code change or commit
npm run test:vitest	Runs Vitest suite for MCP server, auto-combo routing, and caching layers	When modifying MCP tools or routing strategies
npm run test:e2e	Launches Playwright for UI end-to-end tests in tests/e2e/	After UI changes or browser workflow updates
npm run test:protocols:e2e	Tests A2A and MCP transport layers at protocol level	When touching transport or protocol code
npm run test:ecosystem	Validates compatibility against provider SDK matrices	After third-party integration updates
npm run test:coverage	Generates c8 coverage report with 60% threshold gate	Before releases to verify coverage compliance
npm run test:all	Sequential full suite: unit → Vitest → UI → protocols → ecosystem	Complete PR validation
npm run test	Quick alias: unit + Vitest + E2E only	Fast sanity checks

Step-by-Step Test Workflow

Follow this sequence to run tests in OmniRoute comprehensively:

1. Install dependencies

   npm ci

2. Run core unit tests

   npm run test:unit

3. Execute Vitest integration suite

   npm run test:vitest

4. Validate UI with Playwright

   npm run test:e2e

5. Test protocol transports

   npm run test:protocols:e2e

6. Check ecosystem compatibility

   npm run test:ecosystem

7. Verify coverage thresholds

   npm run test:coverage

Quick Commands for Common Scenarios

Fast Development Feedback

# Minimal check during active development

npm run test

Pre-Release Validation

The Release Checklist at docs/ops/RELEASE_CHECKLIST.md (lines 73–82) mandates running the full suite before any release:

npm run test:all
npm run test:coverage

CI Pipeline Example

# .github/workflows/test.yml

steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3
    with:
      node-version: 22
  - run: npm ci
  - run: npm run test:unit
  - run: npm run test:vitest
  - run: npm run test:e2e
  - run: npm run test:coverage

Key Test Directories and Files

Path	Contents
tests/unit/**	Core TypeScript unit tests for src/
tests/e2e/**	Playwright browser automation tests
tests/protocols/**	A2A and MCP transport layer tests
scripts/quality/**	Test selection helpers and coverage measurement utilities

Understanding Coverage Requirements

OmniRoute enforces a 60% coverage gate across statements, lines, functions, and branches. The test:coverage script uses c8 to generate reports and fails the build if thresholds are not met. Run this command before any release to ensure compliance.

Summary

• Use npm run test:unit for rapid feedback on core logic (~21,000 test cases)
• Use npm run test:vitest when working with MCP, routing, or caching code
• Use npm run test:all for complete validation before merging PRs
• Maintain 60% coverage via npm run test:coverage as required by the release checklist
• Reference docs/ops/RELEASE_CHECKLIST.md for authoritative test requirements

Frequently Asked Questions

What is the fastest way to run tests in OmniRoute during development?

Use npm run test as a shorthand for the essential three layers: unit tests, Vitest integration tests, and Playwright E2E tests. This skips protocol and ecosystem tests for faster feedback while catching most regressions.

How do I run only the protocol-level tests for A2A and MCP?

Execute npm run test:protocols:e2e to validate transport layer behavior specifically. This is ideal when modifying src/protocols/ or any code handling agent-to-agent communication.

What Node.js version does OmniRoute require for testing?

OmniRoute targets Node.js 22 as specified in CI configurations. Run node -v to verify your environment matches before executing the test suite.

Where are test scripts defined and configured?

All npm test scripts reside in package.json at the repository root (lines 100–105), including concurrency settings, memory limits, and environment flags like SQLITE_BACKUP=0 for unit test speed optimization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}