# How to Run Tests in OmniRoute: Complete Guide to Unit, E2E, and Coverage Validation > Master OmniRoute testing with our guide. Learn to run unit, E2E, and coverage validation using specific NPM commands. Empower your development workflow today. - Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - Tags: how-to-guide - Published: 2026-07-29 --- **Run `npm run test:all` to execute the complete OmniRoute test suite, or use individual commands like `npm run test:unit`, `npm run test:vitest`, and `npm run test:e2e` to target specific layers of the codebase.** OmniRoute is an open-source routing and orchestration framework that ships with a comprehensive validation suite covering over 21,000 test cases. Knowing how to run tests in OmniRoute ensures that modifications to the core routing logic, MCP servers, or protocol transports do not introduce regressions before deployment. All test commands are defined in the top-level [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) (lines 100–105) and orchestrated through npm scripts. ## Understanding OmniRoute's Test Architecture The repository organizes validation into six distinct categories: Node.js unit tests, Vitest-based integration tests, Playwright end-to-end tests, protocol-level transport tests, ecosystem compatibility checks, and code coverage validation. Each category serves a specific purpose in verifying that `src/` core logic, MCP implementations, and third-party integrations function correctly across different environments. ## Running Individual Test Suites ### Execute Unit Tests with Node.js Use `npm run test:unit` to execute approximately 21,000 Node.js-based unit tests covering the TypeScript codebase in `src/` plus the Open-SSE workspace. This command automatically disables SQLite auto-backup to maximize execution speed. Run this before any code change or commit to ensure core logic remains intact. ```bash npm run test:unit ``` ### Validate MCP and Routing with Vitest Run `npm run test:vitest` to execute the Vitest suite, which specifically validates the MCP server implementation, auto-combo routing algorithms, and caching layers. Use this when you modify MCP tools, adjust routing strategies, or refactor cache implementations. ```bash npm run test:vitest ``` ### Run End-to-End UI Tests with Playwright Execute `npm run test:e2e` to launch Playwright and run the browser-based tests located under `tests/e2e/`. This validates complete user workflows in a real browser environment and should be run after any UI changes. ```bash npm run test:e2e ``` ### Test Protocol Transports Use `npm run test:protocols:e2e` to execute protocol-level end-to-end tests for the A2A and MCP server transports located in `tests/protocols/`. Run this command when you touch the transport layer or modify server communication protocols. ```bash npm run test:protocols:e2e ``` ### Verify Ecosystem Compatibility Run `npm run test:ecosystem` to execute compatibility tests that exercise OmniRoute against a matrix of provider SDKs and external services. Execute this after updating provider configurations or third-party integrations to ensure ecosystem compatibility. ```bash npm run test:ecosystem ``` ### Generate Coverage Reports Execute `npm run test:coverage` to generate a c8 coverage report and enforce the minimum threshold of **60%** across statements, lines, functions, and branches. Run this before releases to verify coverage gates are met, as required by the Release Checklist in [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) (lines 73–82). ```bash npm run test:coverage ``` ## Running the Complete Test Suite ### Execute All Tests Sequentially Run `npm run test:all` to orchestrate the full validation pipeline in the correct order: unit tests → Vitest → UI E2E → protocols → ecosystem. This command ensures comprehensive validation before merging a Pull Request. ```bash npm run test:all ``` ### Quick Development Shortcut Use `npm run test` as a convenience alias that runs unit tests, Vitest, and E2E tests (skipping protocol and ecosystem tests). This provides rapid feedback during iterative development without the overhead of full compatibility testing. ```bash npm run test ``` ## CI/CD Integration Example Integrate OmniRoute testing into your continuous integration pipeline by following the sequence documented in the release checklist. Here is a complete GitHub Actions workflow example: ```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 - Use `npm run test:unit` for fast feedback on core logic changes, covering 21,000+ test cases with SQLite auto-backup disabled for speed. - Execute `npm run test:vitest` when modifying MCP server tools, auto-combo routing, or caching layers. - Run `npm run test:e2e` to validate browser-based user flows using Playwright tests in `tests/e2e/`. - Trigger `npm run test:protocols:e2e` for transport layer changes affecting A2A and MCP protocols. - Verify `npm run test:coverage` meets the 60% gate enforced by c8 before releases. - Use `npm run test:all` for comprehensive pre-merge validation as specified in [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md). ## Frequently Asked Questions ### What is the fastest way to run tests in OmniRoute during development? Run `npm run test:unit` for the quickest feedback on core logic changes, completing approximately 21,000 assertions in seconds. Alternatively, use `npm run test` to include Vitest and E2E validation without the overhead of protocol and ecosystem suites. ### Where are the test files located in the OmniRoute repository? Unit tests reside in `tests/unit/`, Playwright E2E tests are located in `tests/e2e/`, and protocol-level tests are stored in `tests/protocols/`. Quality assurance helpers and coverage scripts are maintained in `scripts/quality/`. ### What code coverage threshold does OmniRoute require? The project enforces a **60%** coverage gate across statements, lines, functions, and branches using c8. The configuration is defined in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), and the `npm run test:coverage` command fails the build if this threshold is not met. ### Do I need to install dependencies before running the test suite? Yes, execute `npm ci` to install the locked dependency tree before running any test commands. The test suite requires Node.js 22 and the specific package versions defined in [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json) to ensure consistent behavior across unit, Vitest, and Playwright tests.