How to Run Tests for OmniRoute: Complete Testing Guide

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

The OmniRoute repository (diegosouzapw/OmniRoute) ships with a multi-layered testing infrastructure that validates everything from core routing logic to protocol-level integrations. Learning how to run tests for OmniRoute is essential for contributors who need to verify changes across approximately 21,000 unit tests, Vitest-based integration layers, and Playwright end-to-end workflows.

Available Test Commands

As configured in diegosouzapw/OmniRoute's package.json (lines 100–105), the test commands are orchestrated through npm scripts. Each script targets a specific layer of the application:

Unit Tests

npm run test:unit executes approximately 21,000 Node.js-based unit tests using the built-in test runner. This command covers the core TypeScript codebase in src/ and the Open-SSE workspace, with SQLite auto-backup disabled for performance.

npm run test:unit

Vitest Integration Tests

npm run test:vitest runs the Vitest suite located in the test directories, which validates the MCP server implementation, auto-combo routing algorithms, and caching layers.

npm run test:vitest

End-to-End UI Tests

npm run test:e2e starts Playwright and executes browser-based tests located under tests/e2e/. Use this when modifying UI components or user workflows.

npm run test:e2e

Protocol-Level Tests

npm run test:protocols:e2e executes end-to-end tests for the A2A (Agent-to-Agent) and MCP (Model Context Protocol) transport layers. Run this when you modify protocol handlers in tests/protocols/ or server configurations.

npm run test:protocols:e2e

Ecosystem Compatibility

npm run test:ecosystem runs compatibility tests against a matrix of provider SDKs and external services to ensure third-party integrations remain functional.

npm run test:ecosystem

Coverage Validation

npm run test:coverage generates a coverage report using c8 and enforces a minimum threshold of 60% for statements, lines, functions, and branches. The helper utilities in scripts/quality/ support the coverage measurement logic used by this command.

npm run test:coverage

Running the Complete Test Workflow

For a comprehensive validation before merging changes, follow this execution order as specified in docs/ops/RELEASE_CHECKLIST.md (lines 73–82):

1. Install dependencies:

   npm ci

2. Run core unit tests:

   npm run test:unit

3. Execute Vitest suite:

   npm run test:vitest

4. Validate UI workflows:

   npm run test:e2e

5. Test protocol transports:

   npm run test:protocols:e2e

6. Check ecosystem compatibility:

   npm run test:ecosystem

7. Verify coverage gates:

   npm run test:coverage

Alternatively, use the convenience script npm run test:all to execute the full sequence automatically (unit → Vitest → UI → protocol → ecosystem).

Quick Testing Shortcut

For rapid validation during development, use npm run test, which acts as an alias for npm run test:unit && npm run test:vitest && npm run test:e2e:

npm run test

This shortcut excludes protocol-level and ecosystem tests, making it suitable for quick feedback loops on core functionality.

CI/CD Integration

When configuring continuous integration pipelines, execute the critical test paths to ensure code quality:

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

• npm run test:unit validates core logic with ~21,000 test cases in tests/unit/
• npm run test:vitest tests MCP servers and routing strategies
• npm run test:e2e runs Playwright browser tests from tests/e2e/
• npm run test:protocols:e2e checks A2A and MCP transport layers in tests/protocols/
• npm run test:ecosystem verifies third-party SDK compatibility
• npm run test:coverage enforces 60% coverage minimums using c8
• npm run test:all executes the complete suite in the correct order

Frequently Asked Questions

What is the difference between unit tests and Vitest tests in OmniRoute?

Unit tests (npm run test:unit) focus on core Node.js logic and TypeScript utilities in src/ using the built-in test runner, while Vitest tests (npm run test:vitest) specifically validate the MCP server implementation, auto-combo routing mechanisms, and caching layers using the Vitest framework.

How do I run only the UI end-to-end tests?

Execute npm run test:e2e to run only the Playwright-based browser tests located in the tests/e2e/ directory. This is useful when you have modified frontend components and need to verify user workflows without running the full suite.

What coverage threshold must be met for OmniRoute?

According to the source code in package.json, OmniRoute enforces a 60% coverage gate for statements, lines, functions, and branches. Run npm run test:coverage to generate reports and verify that your changes meet these requirements before release.

Is there a shortcut to run all tests at once?

Yes, use npm run test:all to execute the complete testing sequence: unit tests → Vitest tests → UI E2E tests → protocol tests → ecosystem tests. For a quicker check that skips protocol and ecosystem validation, use npm run test instead, which runs only the core unit, Vitest, and E2E tests.

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