# How to Run Tests in OmniRoute: Complete Guide to Unit, Vitest, E2E, and Protocol Testing

> Learn to run tests in OmniRoute with this guide. Execute unit, Vitest, E2E, and protocol tests using simple npm scripts for comprehensive validation.

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

---

**Run tests in OmniRoute using npm scripts defined in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), including `npm run test:unit` for core unit tests, `npm run test:vitest` for MCP and routing validation, and `npm run test:all` to execute the full suite.**

Testing in **OmniRoute** is orchestrated through a comprehensive npm script system that covers every layer of the application. The repository, maintained at `diegosouzapw/OmniRoute`, ships with approximately 21,000 test cases spanning unit tests, Vitest-based integration tests, Playwright end-to-end tests, and protocol-level validation for A2A and MCP transports. Understanding how to run tests in OmniRoute ensures code quality before any deployment.

## Available Test Scripts in package.json

All test commands are defined in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) around lines 100–105. Each script targets a specific testing concern:

| Script | Purpose | When to Use |
|--------|---------|-------------|
| `npm run test:unit` | Executes Node.js unit tests (~21,000 cases) with SQLite auto-backup disabled for speed | Before any code change or commit |
| `npm run test:vitest` | Runs Vitest suite for MCP server, auto-combo routing, and caching layers | When modifying MCP tools or routing strategies |
| `npm run test:e2e` | Launches Playwright for UI end-to-end tests in `tests/e2e/` | After UI changes or browser workflow updates |
| `npm run test:protocols:e2e` | Tests A2A and MCP transport layers at protocol level | When touching transport or protocol code |
| `npm run test:ecosystem` | Validates compatibility against provider SDK matrices | After third-party integration updates |
| `npm run test:coverage` | Generates c8 coverage report with **60% threshold gate** | Before releases to verify coverage compliance |
| `npm run test:all` | Sequential full suite: unit → Vitest → UI → protocols → ecosystem | Complete PR validation |
| `npm run test` | Quick alias: unit + Vitest + E2E only | Fast sanity checks |

## Step-by-Step Test Workflow

Follow this sequence to run tests in OmniRoute comprehensively:

1. **Install dependencies**

   ```bash
   npm ci
   ```

2. **Run core unit tests**

   ```bash
   npm run test:unit
   ```

3. **Execute Vitest integration suite**

   ```bash
   npm run test:vitest
   ```

4. **Validate UI with Playwright**

   ```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 thresholds**

   ```bash
   npm run test:coverage
   ```

## Quick Commands for Common Scenarios

### Fast Development Feedback

```bash

# Minimal check during active development

npm run test

```

### Pre-Release Validation

The **Release Checklist** at [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) (lines 73–82) mandates running the full suite before any release:

```bash
npm run test:all
npm run test:coverage

```

### CI Pipeline Example

```yaml

# .github/workflows/test.yml

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

| Path | Contents |
|------|----------|
| `tests/unit/**` | Core TypeScript unit tests for `src/` |
| `tests/e2e/**` | Playwright browser automation tests |
| `tests/protocols/**` | A2A and MCP transport layer tests |
| `scripts/quality/**` | Test selection helpers and coverage measurement utilities |

## Understanding Coverage Requirements

OmniRoute enforces a **60% coverage gate** across statements, lines, functions, and branches. The `test:coverage` script uses **c8** to generate reports and fails the build if thresholds are not met. Run this command before any release to ensure compliance.

## Summary

- **Use `npm run test:unit`** for rapid feedback on core logic (~21,000 test cases)
- **Use `npm run test:vitest`** when working with MCP, routing, or caching code
- **Use `npm run test:all`** for complete validation before merging PRs
- **Maintain 60% coverage** via `npm run test:coverage` as required by the release checklist
- **Reference [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md)** for authoritative test requirements

## Frequently Asked Questions

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

Use `npm run test` as a shorthand for the essential three layers: unit tests, Vitest integration tests, and Playwright E2E tests. This skips protocol and ecosystem tests for faster feedback while catching most regressions.

### How do I run only the protocol-level tests for A2A and MCP?

Execute `npm run test:protocols:e2e` to validate transport layer behavior specifically. This is ideal when modifying `src/protocols/` or any code handling agent-to-agent communication.

### What Node.js version does OmniRoute require for testing?

OmniRoute targets **Node.js 22** as specified in CI configurations. Run `node -v` to verify your environment matches before executing the test suite.

### Where are test scripts defined and configured?

All npm test scripts reside in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) at the repository root (lines 100–105), including concurrency settings, memory limits, and environment flags like `SQLITE_BACKUP=0` for unit test speed optimization.