# How to Run Tests for OmniRoute: Complete Testing Guide

> Easily run tests for OmniRoute with npm commands. Execute the full suite using npm run test:all or target unit, Vitest, or e2e tests individually for efficient development.

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

---

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

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) (lines 73–82):

1. Install dependencies:
   ```bash
   npm ci
   ```

2. Run core unit tests:
   ```bash
   npm run test:unit
   ```

3. Execute Vitest suite:
   ```bash
   npm run test:vitest
   ```

4. Validate UI workflows:
   ```bash
   npm run test:e2e
   ```

5. Test protocol transports:
   ```bash
   npm run test:protocols:e2e
   ```

6. Check ecosystem compatibility:
   ```bash
   npm run test:ecosystem
   ```

7. Verify coverage gates:
   ```bash
   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`:

```bash
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:

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