How to Run or Test Individual Services in OmniRoute: CLI, Direct Imports, and Test Suites

You can run or test individual OmniRoute services using the CLI (omniroute binary), direct module imports from open-sse/services/, or the unit/integration test suites in tests/unit/services/.

OmniRoute is an open-source AI routing platform that splits functionality into isolated services located in open-sse/services/. Whether you are debugging a provider connection or validating a routing combo, knowing how to run or test individual services of OmniRoute locally is essential for development and CI/CD validation.

Starting the Core Development Server

OmniRoute runs on a Next.js App Router architecture. To exercise services via HTTP endpoints, first launch the local development server.

npm run dev

This starts the application on https://localhost:20128. The server dynamically loads services from open-sse/services/** when requests hit the corresponding API routes. For example, requests to src/app/api/providers/route.ts delegate to the provider service logic defined in open-sse/services/provider.ts.

Testing Services via the Built-in CLI

OmniRoute ships with a unified binary (omniroute) generated from the skill files under skills/. Each sub-command maps directly to a service group, invoking the same internal HTTP client used by the production UI.

Testing Provider Connections

To verify that a provider configuration is valid without deploying, use the provider service defined in open-sse/services/provider.ts.

omniroute providers test <provider-id>

Example: Test a configured OpenAI connection.

omniroute providers test openai

This command is documented in skills/cli-providers/SKILL.md and executes the getProvider function to validate API keys and fetch available models.

Testing Combo Routing Strategies

The combo routing service (open-sse/services/combo.ts) handles intelligent request routing across multiple providers. Test specific combos using JSON payloads.

omniroute combos test \
  -d '{"messages":[{"role":"user","content":"Hello"}],"comboId":"default"}' \
  --json

Refer to skills/omni-combos-routing/SKILL.md for advanced flags and payload structures.

Testing Prompt Compression Engines

Evaluate the RTK compression engine located at open-sse/services/compression/engines/rtk/rtkEngine.ts directly from the command line.

omniroute compression test --model gpt-4o "The quick brown fox jumps over the lazy dog."

This command targets the compressPrompt function and outputs token reduction metrics. Documentation resides in skills/cli-compression/SKILL.md.

Running Unit and Integration Tests

Each service includes dedicated test suites that import the service logic directly, bypassing the HTTP layer for fast, deterministic validation.

Provider Service Unit Tests

The file tests/unit/services/provider.test.ts exercises the getProvider function.

import { getProvider } from '../../../open-sse/services/provider';

test('provider connection returns expected model list', async () => {
  const result = await getProvider('openai');
  expect(result.models).toContain('gpt-4o');
});

Run this specific test suite:

npm run test:unit -- tests/unit/services/provider.test.ts

Combo Routing Unit Tests

Validate routing logic in tests/unit/services/combo.test.ts by importing handleComboChat.

import { handleComboChat } from '../../../open-sse/services/combo';

test('combo routes to the fastest provider', async () => {
  const response = await handleComboChat({ 
    comboId: 'fast', 
    messages: [{ role: 'user', content: 'ping' }] 
  });
  expect(response.provider).toBe('openai');
});

Execute with:

npm run test:unit -- tests/unit/services/combo.test.ts

Compression Engine Tests

Test token reduction algorithms in tests/unit/services/compression.test.ts.

import { compressPrompt } from '../../../open-sse/services/compression/engines/rtk/rtkEngine';

test('RTK reduces token count', async () => {
  const out = await compressPrompt('Long prompt...');
  expect(out.tokens).toBeLessThan(100);
});

Run via:

npm run test:unit -- tests/unit/services/compression.test.ts

Integration Test Suites

For end-to-end validation that exercises the full request pipeline, including HTTP routing and middleware, use the integration test suite:

npm run test:integration

Direct Module Imports for Advanced Scripting

For custom scripts, debugging, or CI pipelines that require bypassing the HTTP server entirely, import the service module directly into a Node.js process.

import { handleComboChat } from './open-sse/services/combo';

(async () => {
  const res = await handleComboChat({ 
    comboId: 'myCombo', 
    messages: [{ role: 'user', content: 'What is AI?' }] 
  });
  console.log(res);
})();

This pattern works for any service under open-sse/services/, including getProvider from open-sse/services/provider.ts and compressPrompt from open-sse/services/compression/engines/rtk/rtkEngine.ts. Direct imports eliminate network overhead and allow you to focus strictly on business logic.

Summary

• Start the server with npm run dev to test services via HTTP endpoints like src/app/api/providers/route.ts.
• Use the CLI (omniroute providers test, omniroute combos test, omniroute compression test) for rapid manual validation.
• Run unit tests with npm run test:unit -- <path> to execute fast, isolated logic tests that import directly from open-sse/services/.
• Import modules directly for custom Node.js scripts, bypassing the HTTP layer entirely.

Frequently Asked Questions

How do I run a single provider test in OmniRoute?

Use the command omniroute providers test <provider-id> (for example, omniroute providers test openai). This invokes the logic in open-sse/services/provider.ts to validate credentials and connectivity without deploying the full application.

What is the fastest way to test a routing combo without the UI?

Run omniroute combos test --json with a JSON payload specifying the comboId and messages. This targets the handleComboChat function in open-sse/services/combo.ts and returns routing decisions immediately.

Can I run OmniRoute services without starting the full Next.js server?

Yes. You can import any service directly from open-sse/services/ into a Node.js script or test file. For example, import { getProvider } from './open-sse/services/provider' allows you to execute service logic without npm run dev running.

Where are the unit tests located for OmniRoute services?

Unit tests reside in tests/unit/services/, with specific files like tests/unit/services/provider.test.ts, tests/unit/services/combo.test.ts, and tests/unit/services/compression.test.ts mapping to their respective service implementations.

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