Probitas Packages

Monorepo containing core framework packages and client libraries for the Probitas scenario-based testing framework.

This repository combines both the framework implementation (builder, runner, reporter, etc.) and multi-protocol client libraries (HTTP, gRPC, SQL, Redis, etc.) under a unified workspace for streamlined development and testing.

Highlights

• Framework Packages: Type-safe scenario builder, execution engine, reporters, and expectation library
• Multi-Protocol Clients: HTTP, ConnectRPC/gRPC/gRPC-Web, GraphQL, SQL (Postgres/MySQL/SQLite/DuckDB), MongoDB, Redis, RabbitMQ, and SQS
• Shared Error Model: Consistent ClientError hierarchy across all clients for uniform error handling
• Resource Management: AsyncDisposable-aware clients for automatic cleanup in scenarios
• Built for Bun: Published on npm under @probitas-test/*, with a JSR mirror under @probitas/*

Packages

Framework Packages

Package	npm	JSR	Description
@probitas-test/builder			Type-safe scenario definition API
@probitas-test/runner			Scenario execution engine
@probitas-test/reporter			Output formatters (List, JSON)
@probitas-test/core			Scenario loading and filtering
@probitas-test/discover			File discovery with glob patterns
@probitas-test/expect			Expectation library

Client Packages

Package	npm	JSR	Description
@probitas-test/client			Core options and error base types shared by all clients
@probitas-test/client-http			HTTP client with buffered responses and cookie support
@probitas-test/client-connectrpc			ConnectRPC client supporting Connect, gRPC, and gRPC-Web protocols
@probitas-test/client-grpc			gRPC client (thin wrapper over client-connectrpc)
@probitas-test/client-graphql			GraphQL client with data/error helpers
@probitas-test/client-sql			Shared SQL result/transaction types
@probitas-test/client-sql-postgres			PostgreSQL client built on the shared SQL types
@probitas-test/client-sql-mysql			MySQL client built on the shared SQL types
@probitas-test/client-sql-sqlite			SQLite client built on the shared SQL types
@probitas-test/client-sql-duckdb			DuckDB client built on the shared SQL types
@probitas-test/client-mongodb			MongoDB client with session/transaction helpers
@probitas-test/client-redis			Redis client for command execution
@probitas-test/client-sqs			SQS client targeting ElasticMQ for integration testing
@probitas-test/client-rabbitmq			RabbitMQ client with channel lifecycle management

Quick Start

This repository is intended for contributors developing the Probitas framework itself. For using Probitas in your projects, refer to @probitas-test/probitas - the main framework package with unified API for writing scenarios.

Development

Prerequisites

• Nix (nix develop, or copy .envrc.sample to .envrc for direnv), which provides Bun 1.4+ and just
• Docker Compose (for integration testing services)

Setup

# Clone the repository
git clone https://github.com/probitas-test/probitas-packages.git
cd probitas-packages

# Enter the development environment
nix develop

# Install dependencies
just install

# Start integration test services
docker compose up -d

Tasks

# Run everything CI checks (recommended before committing)
just ci

# Individual tasks
just fmt              # Format code (dprint, nixfmt)
just lint             # Lint code (Biome)
just typecheck        # Type check (tsc)
just test             # Run tests

# Coverage (lcov report in .coverage/)
just coverage

Integration Services

compose.yaml provides local dependencies for testing:

Service	Port	Docker Image
echo-http	8080	ghcr.io/probitas-test/echo-http
echo-connectrpc	8090	ghcr.io/probitas-test/echo-connectrpc
echo-grpc	50051	ghcr.io/probitas-test/echo-grpc
echo-graphql	8100	ghcr.io/probitas-test/echo-graphql
postgres	5432	postgres:latest
mysql	3306	mysql:latest
redis	6379	redis:latest
mongodb	27017	mongo:latest
rabbitmq	5672	rabbitmq:latest
elasticmq	9324	softwaremill/elasticmq-native

Architecture

Framework Layers

1. Discovery (@probitas-test/discover) - File pattern matching and scenario discovery
2. Core (@probitas-test/core) - Scenario loading, filtering, and type definitions
3. Builder (@probitas-test/builder) - Fluent API for defining scenarios with type-safe step chaining
4. Runner (@probitas-test/runner) - Execution engine with concurrency control, retries, and resource lifecycle
5. Reporter (@probitas-test/reporter) - Output formatting (List, JSON)
6. Expect (@probitas-test/expect) - Protocol-specific expectation matchers

Client Design Principles

• Minimal Dependencies: Client packages avoid depending on framework packages to prevent circular dependencies
• Shared Error Model: All clients extend ClientError from @probitas-test/client with typed kind discriminators
• Resource Lifecycle: Clients implement AsyncDisposable for automatic cleanup in scenario resources
• Protocol Consistency: Similar operations (queries, commands) share API patterns across clients

Contributing

This repository uses Conventional Commits:

# Single package
feat(builder): add retry option to step execution
fix(client-http): handle connection pooling correctly

# Multiple packages
fix(runner,core): fix shared type definitions

# All packages
docs(*): update copyright headers

Important:

• Scopes are package names without the registry scope (e.g., expect, client-http)
• feat: → minor bump, fix:/docs:/refactor: → patch bump
• BREAKING: → major bump (except for /unstable scopes, always patch)
• Run just ci before committing

See .claude/rules/repository.md for detailed contribution guidelines.

Related Repositories

• @probitas-test/probitas - Main framework package with unified API

License

See LICENSE for details.