How to Test OmniRoute: A Complete Guide to Unit, E2E, and Protocol Testing

OmniRoute ships with a comprehensive test suite executed via npm scripts defined in package.json, covering approximately 21,000 unit tests, Vitest-based integration tests, Playwright E2E tests, protocol-level A2A/MCP validation, and ecosystem compatibility checks.

OmniRoute is an open-source routing framework that requires rigorous validation across its core TypeScript logic, transport protocols, and browser-based UI. This guide explains how to test OmniRoute using the standardized npm scripts located in the repository root, ensuring you can verify code changes from fast unit checks to full integration workflows.

Prerequisites and Installation

Before executing any tests, install the project dependencies using a CI-compatible approach. OmniRoute supports both npm and pnpm, though the documentation emphasizes npm ci for reproducible builds.

# Install dependencies (recommended for CI)

npm ci

# Or using pnpm

pnpm install

All test commands are orchestrated from the top-level package.json (lines 100–105), which defines specific scripts for each testing layer.

Running the Core Test Suites

OmniRoute organizes its validation into distinct layers, allowing you to run targeted checks based on which components you modified.

Unit Tests with Node.js

The unit test suite executes approximately 21,000 test cases using Node.js's built-in test runner. This covers the core code in src/ plus the Open-SSE workspace, with SQLite auto-backup disabled to maximize execution speed.

# Run core unit tests (~21,000 cases)

npm run test:unit

Use this command before any code change or commit to ensure core logic remains correct.

Vitest Integration Tests

The Vitest suite validates the MCP server implementation, auto-combo routing algorithms, and caching layers. Run this when you modify MCP tools, routing strategies, or cache implementations.

# Run Vitest suite (MCP, auto-combo, cache layers)

npm run test:vitest

End-to-End UI Tests with Playwright

For browser workflow validation, OmniRoute uses Playwright to execute tests located under tests/e2e/. This requires the UI to be built or served before execution.

# Run Playwright E2E tests

npm run test:e2e

Run these after UI changes or when verifying full browser-based workflows.

Specialized Testing Workflows

Beyond the core suites, OmniRoute provides targeted scripts for protocol validation and third-party compatibility.

Protocol-Level Testing for A2A and MCP

The protocol end-to-end tests exercise the A2A (Agent-to-Agent) and MCP (Model Context Protocol) transport layers. These tests are located in tests/protocols/ and validate server implementations at the wire level.

# Run A2A and MCP protocol tests

npm run test:protocols:e2e

Execute this command when you touch the A2A or MCP transport implementations.

Ecosystem Compatibility Validation

The ecosystem tests exercise OmniRoute against a matrix of provider SDKs and external services. This ensures compatibility across different AI provider implementations.

# Run provider SDK compatibility matrix

npm run test:ecosystem

Run these after updating provider configurations or third-party integrations to catch breaking changes in external APIs.

Coverage Reporting and Enforcement

OmniRoute enforces a 60% coverage gate across statements, lines, functions, and branches using c8. The coverage script generates detailed reports and fails if thresholds are not met.

# Generate coverage report and enforce 60% gate

npm run test:coverage

According to the docs/ops/RELEASE_CHECKLIST.md (lines 73–82), this step is mandatory before any release to ensure quality standards are maintained.

Running the Complete Test Suite

The All-In-One Command

For comprehensive validation, use the test:all script, which orchestrates the full suite in dependency order: unit → Vitest → UI → protocol → ecosystem.

# Run the complete test suite

npm run test:all

Alternatively, the shortcut npm run test runs a quick sanity check executing unit tests, Vitest, and E2E tests only (skipping protocol and ecosystem layers).

CI/CD Integration Example

Integrate OmniRoute testing into your GitHub Actions pipeline using the following configuration:

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

For local development, the scripts/quality/ directory contains helpers for selecting impacted tests and measuring incremental coverage.

Summary

• Unit tests (npm run test:unit) validate ~21,000 core logic cases with SQLite optimizations for speed.
• Vitest tests (npm run test:vitest) cover MCP servers, routing, and caching implementations.
• E2E tests (npm run test:e2e) use Playwright to verify browser workflows in tests/e2e/.
• Protocol tests (npm run test:protocols:e2e) validate A2A and MCP transport layers.
• Ecosystem tests (npm run test:ecosystem) ensure compatibility across provider SDKs.
• Coverage (npm run test:coverage) enforces a mandatory 60% threshold using c8.
• All scripts are defined in package.json (lines 100–105) and documented in docs/ops/RELEASE_CHECKLIST.md.

Frequently Asked Questions

What is the fastest way to test OmniRoute during development?

Run npm run test (an alias for test:unit && test:vitest && test:e2e) for a quick sanity check that validates core logic, MCP components, and UI workflows without executing the slower protocol and ecosystem suites. This takes significantly less time than the full test:all command while catching most regressions.

How do I test only the MCP server and routing logic?

Use npm run test:vitest, which specifically targets the Vitest suite containing MCP server validation, auto-combo routing algorithms, and caching layer tests. This is faster than running the full unit test suite when you are only modifying routing strategies or tool implementations.

What coverage threshold does OmniRoute require?

OmniRoute requires 60% coverage across statements, lines, functions, and branches as enforced by the c8 coverage tool. The test:coverage script will fail if your changes drop coverage below this threshold, a gate that must pass before any release according to the docs/ops/RELEASE_CHECKLIST.md.

Where are the protocol tests for A2A and MCP located?

Protocol-level tests reside in tests/protocols/ and are executed via npm run test:protocols:e2e. These tests validate the transport layers for both Agent-to-Agent (A2A) and Model Context Protocol (MCP) servers, ensuring correct wire-level behavior independent of the UI or business logic layers.

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