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

> Learn how to run various tests in OmniRoute use npm scripts including unit E2E protocol and coverage commands Accelerate your development with efficient testing

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-20

---

**Run tests in OmniRoute using the npm scripts defined in the top-level [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.