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

> Easily run and test individual OmniRoute services via CLI, direct imports from open-sse/services/, or test suites in tests/unit/services/. Learn efficient OmniRoute service testing.

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

---

**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.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/providers/route.ts) delegate to the **provider service** logic defined in [`open-sse/services/provider.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/provider.ts).

```bash
omniroute providers test <provider-id>

```

*Example*: Test a configured OpenAI connection.

```bash
omniroute providers test openai

```

This command is documented in [`skills/cli-providers/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) handles intelligent request routing across multiple providers. Test specific combos using JSON payloads.

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

```

Refer to [`skills/omni-combos-routing/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engines/rtk/rtkEngine.ts) directly from the command line.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/services/provider.test.ts) exercises the `getProvider` function.

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

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

```

### Combo Routing Unit Tests

Validate routing logic in [`tests/unit/services/combo.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/services/combo.test.ts) by importing `handleComboChat`.

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

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

```

### Compression Engine Tests

Test token reduction algorithms in [`tests/unit/services/compression.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/services/compression.test.ts).

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

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

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

```ts
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/provider.ts) and `compressPrompt` from [`open-sse/services/compression/engines/rtk/rtkEngine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/services/provider.test.ts), [`tests/unit/services/combo.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/services/combo.test.ts), and [`tests/unit/services/compression.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/services/compression.test.ts) mapping to their respective service implementations.