How to Run Tests in OmniRoute: Complete Guide to Unit, E2E, and Coverage Validation

Run npm run test:all to execute the complete OmniRoute test suite, or use individual commands like npm run test:unit, npm run test:vitest, and npm run test:e2e to target specific layers of the codebase.

OmniRoute is an open-source routing and orchestration framework that ships with a comprehensive validation suite covering over 21,000 test cases. Knowing how to run tests in OmniRoute ensures that modifications to the core routing logic, MCP servers, or protocol transports do not introduce regressions before deployment. All test commands are defined in the top-level package.json (lines 100–105) and orchestrated through npm scripts.

Understanding OmniRoute's Test Architecture

The repository organizes validation into six distinct categories: Node.js unit tests, Vitest-based integration tests, Playwright end-to-end tests, protocol-level transport tests, ecosystem compatibility checks, and code coverage validation. Each category serves a specific purpose in verifying that src/ core logic, MCP implementations, and third-party integrations function correctly across different environments.

Running Individual Test Suites

Execute Unit Tests with Node.js

Use npm run test:unit to execute approximately 21,000 Node.js-based unit tests covering the TypeScript codebase in src/ plus the Open-SSE workspace. This command automatically disables SQLite auto-backup to maximize execution speed. Run this before any code change or commit to ensure core logic remains intact.

npm run test:unit

Validate MCP and Routing with Vitest

Run npm run test:vitest to execute the Vitest suite, which specifically validates the MCP server implementation, auto-combo routing algorithms, and caching layers. Use this when you modify MCP tools, adjust routing strategies, or refactor cache implementations.

npm run test:vitest

Run End-to-End UI Tests with Playwright

Execute npm run test:e2e to launch Playwright and run the browser-based tests located under tests/e2e/. This validates complete user workflows in a real browser environment and should be run after any UI changes.

npm run test:e2e

Test Protocol Transports

Use npm run test:protocols:e2e to execute protocol-level end-to-end tests for the A2A and MCP server transports located in tests/protocols/. Run this command when you touch the transport layer or modify server communication protocols.

npm run test:protocols:e2e

Verify Ecosystem Compatibility

Run npm run test:ecosystem to execute compatibility tests that exercise OmniRoute against a matrix of provider SDKs and external services. Execute this after updating provider configurations or third-party integrations to ensure ecosystem compatibility.

npm run test:ecosystem

Generate Coverage Reports

Execute npm run test:coverage to generate a c8 coverage report and enforce the minimum threshold of 60% across statements, lines, functions, and branches. Run this before releases to verify coverage gates are met, as required by the Release Checklist in docs/ops/RELEASE_CHECKLIST.md (lines 73–82).

npm run test:coverage

Running the Complete Test Suite

Execute All Tests Sequentially

Run npm run test:all to orchestrate the full validation pipeline in the correct order: unit tests → Vitest → UI E2E → protocols → ecosystem. This command ensures comprehensive validation before merging a Pull Request.

npm run test:all

Quick Development Shortcut

Use npm run test as a convenience alias that runs unit tests, Vitest, and E2E tests (skipping protocol and ecosystem tests). This provides rapid feedback during iterative development without the overhead of full compatibility testing.

npm run test

CI/CD Integration Example

Integrate OmniRoute testing into your continuous integration pipeline by following the sequence documented in the release checklist. Here is a complete GitHub Actions workflow example:

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

Summary

• Use npm run test:unit for fast feedback on core logic changes, covering 21,000+ test cases with SQLite auto-backup disabled for speed.
• Execute npm run test:vitest when modifying MCP server tools, auto-combo routing, or caching layers.
• Run npm run test:e2e to validate browser-based user flows using Playwright tests in tests/e2e/.
• Trigger npm run test:protocols:e2e for transport layer changes affecting A2A and MCP protocols.
• Verify npm run test:coverage meets the 60% gate enforced by c8 before releases.
• Use npm run test:all for comprehensive pre-merge validation as specified in docs/ops/RELEASE_CHECKLIST.md.

Frequently Asked Questions

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

Run npm run test:unit for the quickest feedback on core logic changes, completing approximately 21,000 assertions in seconds. Alternatively, use npm run test to include Vitest and E2E validation without the overhead of protocol and ecosystem suites.

Where are the test files located in the OmniRoute repository?

Unit tests reside in tests/unit/, Playwright E2E tests are located in tests/e2e/, and protocol-level tests are stored in tests/protocols/. Quality assurance helpers and coverage scripts are maintained in scripts/quality/.

What code coverage threshold does OmniRoute require?

The project enforces a 60% coverage gate across statements, lines, functions, and branches using c8. The configuration is defined in package.json, and the npm run test:coverage command fails the build if this threshold is not met.

Do I need to install dependencies before running the test suite?

Yes, execute npm ci to install the locked dependency tree before running any test commands. The test suite requires Node.js 22 and the specific package versions defined in package-lock.json to ensure consistent behavior across unit, Vitest, and Playwright tests.

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