Testurio

A declarative E2E/integration testing framework for distributed systems with multi-protocol support.

Warning This project is currently a work in progress. The API is not stable and may change without notice. Use at your own risk in production environments.

Read the full documentation

Features

• Multi-Protocol Support - HTTP, gRPC (Unary & Streaming), WebSocket, TCP
• Message Queue Support - Publisher/Subscriber for Kafka, RabbitMQ, Redis Pub/Sub
• DataSource Integration - Direct SDK access to Redis, PostgreSQL, MongoDB
• Declarative API - Write tests in execution order with clear, readable syntax
• Component-Based - Define clients, mocks, proxies, publishers, subscribers, and data sources as reusable components
• Type-Safe - Full TypeScript support with automatic type inference
• Flow Testing - Test complete request flows through your distributed system
• Flexible Mocking - Mock responses, add delays, drop messages, or proxy through
• Schema Generation CLI - Auto-generate Zod schemas and service interfaces from OpenAPI and .proto files

Installation

npm install testurio --save-dev

Quick Start

import { TestScenario, testCase, Client, Server, HttpProtocol } from 'testurio';

// Define components with protocol
const httpClient = new Client('client', {
  protocol: new HttpProtocol(),
  targetAddress: { host: 'localhost', port: 3000 },
});

const httpServer = new Server('mock', {
  protocol: new HttpProtocol(),
  listenAddress: { host: 'localhost', port: 3000 },
});

// Create scenario
const scenario = new TestScenario({ name: 'User API Test' });

// Write test cases
const tc = testCase('Get user by ID', (test) => {
  const client = test.use(httpClient);
  const mock = test.use(httpServer);

  client.request('getUsers', { method: 'GET', path: '/users' });

  mock
    .onRequest('getUsers', { method: 'GET', path: '/users' })
    .mockResponse(() => ({
      code: 200,
      body: [{ id: 1, name: 'Alice', email: '[email protected]' }],
    }));

  client
    .onResponse('getUsers')
    .assert((res) => res.body[0].id === 1);
});

// Run the test
const result = await scenario.run(tc);
console.log(result.passed); // true

Packages

| Package | Description | | ---------------------------------------------------------------------------------------- | ------------------------------------ | | testurio | Core framework with HTTP protocol | | @testurio/protocol-grpc | gRPC unary & streaming protocol | | @testurio/protocol-ws | WebSocket protocol | | @testurio/protocol-tcp | TCP protocol | | @testurio/adapter-kafka | Kafka adapter | | @testurio/adapter-rabbitmq | RabbitMQ adapter | | @testurio/adapter-redis | Redis adapter (Pub/Sub + DataSource) | | @testurio/adapter-pg | PostgreSQL adapter | | @testurio/adapter-mongo | MongoDB adapter | | @testurio/reporter-allure | Allure reporter | | @testurio/cli | CLI for schema generation |

Roadmap

See the Roadmap for upcoming features.

License

MIT