How to Run Tests in OmniRoute: Unit, E2E, Protocol, and Coverage Commands

Run tests in OmniRoute using the npm scripts defined in the top-level package.json, such as npm run test:unit for core logic, npm run test:vitest for MCP and routing layers, and npm run test:all for the complete pre-merge suite.

OmniRoute ships with a comprehensive, multi-layered test suite that validates everything from core TypeScript logic to Playwright browser workflows and protocol-level server interactions. The repository diegosouzapw/OmniRoute orchestrates these checks through a set of discrete npm scripts located in package.json around lines 100–105. Whether you are patching a provider integration or refactoring the auto-combo router, knowing how to run tests in OmniRoute ensures your changes do not break existing behavior.

Available Test Scripts

The package.json file defines granular scripts so developers can run exactly the layer they need.

Unit Tests with npm run test:unit

npm run test:unit executes roughly 21,000 Node.js-based unit tests using the built-in test runner. According to the source configuration, this script targets the core code under src/ plus the Open-SSE workspace, with SQLite auto-backup disabled for faster execution. Run this command before any commit to verify that foundational logic remains intact.

Vitest Suite with npm run test:vitest

npm run test:vitest spins up the Vitest suite, which focuses on the MCP server implementation, auto-combo routing, and caching layers. Use this script whenever you modify tools, routing strategies, or cache implementations in the OmniRoute codebase.

UI End-to-End Tests with npm run test:e2e

npm run test:e2e starts Playwright and executes the browser-based end-to-end tests stored under tests/e2e/. This command is essential after any UI change or when you need to validate the full user workflow in a real browser environment.

Protocol E2E Tests with npm run test:protocols:e2e

npm run test:protocols:e2e runs protocol-level end-to-end tests against the A2A and MCP servers. Invoke this script after touching transport-layer code to confirm that protocol handshakes and message formatting still conform to specification.

Ecosystem Compatibility with npm run test:ecosystem

npm run test:ecosystem exercises OmniRoute against a matrix of provider SDKs and external services. Run this check after updating third-party integrations or provider configurations to catch upstream breaking changes early.

Coverage Validation with npm run test:coverage

npm run test:coverage generates a report via c8 and enforces a minimum threshold of 60 % across statements, lines, functions, and branches. The script is documented in the source as a required step before releases.

Full Suite with npm run test:all

npm run test:all is a convenience script that runs the complete validation pipeline in order: unit → Vitest → UI → protocol → ecosystem. It provides a single command for a comprehensive sanity check before merging a pull request.

Typical Test Workflow

A standard local validation follows this sequence:

1. Install dependencies with npm ci (or pnpm install if you prefer pnpm).

2. Run the core unit tests with npm run test:unit.

3. Validate MCP and routing layers with npm run test:vitest.

4. Check browser workflows with npm run test:e2e.

5. Confirm transport protocols with npm run test:protocols:e2e.

6. Verify external compatibility with npm run test:ecosystem.

7. Audit coverage with npm run test:coverage.

If you only need a quick sanity check, the alias npm run test—equivalent to running unit, Vitest, and e2e sequentially—is also available.

Example Commands

Install once, then execute the exact layer you need:

# CI-compatible dependency install

npm ci

# Core unit tests (~21,000 cases, SQLite auto-backup disabled)

npm run test:unit

# Vitest: MCP server, auto-combo routing, and cache layers

npm run test:vitest

# Complete pre-merge validation

npm run test:all

# Coverage report with 60% gate enforcement

npm run test:coverage

Continuous Integration Setup

You can replicate the local workflow in GitHub Actions using Node.js 22. The example below mirrors the steps recommended in the repository:

# Example CI script (GitHub Actions)

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 Files and Directories

Understanding the repository layout helps you select the right command:

• package.json — Defines all npm scripts, concurrency flags, and memory limits for the test runners.
• tests/unit/ — Houses the core TypeScript unit tests that test:unit executes.
• tests/e2e/ — Contains Playwright browser tests for UI workflows.
• tests/protocols/ — Holds the A2A and MCP transport-layer end-to-end tests.
• scripts/quality/ — Provides helpers for selecting impacted tests and measuring coverage.
• docs/ops/RELEASE_CHECKLIST.md — Documents the required test commands before a release (see lines 73–82).

Summary

• Run tests in OmniRoute through purpose-built npm scripts defined in package.json.
• npm run test:unit covers ~21,000 core cases with the Node.js built-in runner.
• npm run test:vitest validates MCP tooling, routing, and caching logic.
• npm run test:e2e launches Playwright against tests/e2e/ for browser validation.
• npm run test:protocols:e2e verifies A2A and MCP server transports.
• npm run test:ecosystem checks compatibility across provider SDKs.
• npm run test:coverage enforces a 60 % c8 threshold before release.
• npm run test:all runs the entire pipeline in the correct order for pre-merge confidence.

Frequently Asked Questions

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

Use npm run test as a shortcut. It executes the unit, Vitest, and UI end-to-end suites in sequence, giving you rapid feedback on core logic and rendering without the overhead of ecosystem or protocol tests.

Which test command should I run after modifying MCP routing or caching logic?

Run npm run test:vitest. This script specifically targets the MCP server, auto-combo routing, and caching layers, ensuring that changes to those subsystems do not regress existing behavior.

How do I check if my changes meet the code coverage requirements?

Execute npm run test:coverage. This command generates a c8 report and enforces a minimum 60 % coverage gate across statements, lines, functions, and branches. It is listed as a required step in docs/ops/RELEASE_CHECKLIST.md before any release.

Where are the protocol end-to-end tests for A2A and MCP located?

The protocol-level tests live under tests/protocols/ in the repository. You can execute them with npm run test:protocols:e2e, which spins up the relevant servers and validates transport-layer compliance.

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