@amqp-contract/testing

Testing utilities for AMQP contracts using testcontainers.


📖 Full documentation →

Features

- 🐳 Automatically starts RabbitMQ container for tests
- ✅ Works with Vitest globalSetup
- 🚀 Fast and reliable integration testing
- 📊 Includes RabbitMQ management console

Installation

``bash
pnpm add -D @amqp-contract/testing
`

Usage

$3

Add to your vitest.config.ts:

`typescript
import { defineConfig } from "vitest/config";

export default defineConfig({
test: {
globalSetup: ["@amqp-contract/testing/global-setup"],
},
});
`

$3

For TypeScript projects, reference the type definitions in your tsconfig.json:

`json
{
"compilerOptions": {
"types": ["@amqp-contract/testing/types/vitest"]
}
}
`

Or add a triple-slash reference in your test files:

`typescript
///
`

This provides type-safe access to the test container context variables.

$3

The package provides a Vitest extension that automatically manages RabbitMQ connections:

`typescript
import { describe, expect } from "vitest";
import { it } from "@amqp-contract/testing/extension";

describe("Order Processing", () => {
it("should publish and consume messages", async ({ amqpConnection }) => {
// amqpConnection is automatically provided and cleaned up
// Your test code here using amqpConnection
});
});
`

The extension provides:

- vhost: A unique virtual host created for test isolation (automatically cleaned up after the test)
- amqpConnectionUrl: A connection URL pre-configured with the test vhost
- amqpConnection: An established connection to the RabbitMQ testcontainer
- amqpChannel: A channel for AMQP operations
- publishMessage: Helper function for publishing test messages
- initConsumer: Helper function for setting up test consumers
- Automatic connection and vhost cleanup after each test

What It Does

Global Setup:

1. Starts a RabbitMQ container with management plugin
2. Waits for RabbitMQ to be healthy
3. Provides connection details to your tests
4. Cleans up the container after tests complete

Test Extension:

1. Creates a unique virtual host (vhost) for each test to ensure complete isolation
2. Provides pre-configured connections and helpers for interacting with RabbitMQ
3. Automatically cleans up the vhost and connections after each test completes

Container Details

- Image: rabbitmq:4.2.1-management-alpine (default)
- Can be configured via RABBITMQ_IMAGE environment variable
- Ports:
- 5672 (AMQP)
- 15672 (Management console)
- Credentials:
- User: guest
- Password: guest

Environment Variables

$3

- RABBITMQ_IMAGE - Docker image to use for the RabbitMQ container
- Default: rabbitmq:4.2.1-management-alpine
- Can be set to any compatible RabbitMQ image with management plugin

$3

The following variables are provided to tests:

- __TESTCONTAINERS_RABBITMQ_IP__ - Container host IP
- __TESTCONTAINERS_RABBITMQ_PORT_5672__ - Mapped AMQP port
- __TESTCONTAINERS_RABBITMQ_PORT_15672__` - Mapped management port

Documentation

📖 Read the full documentation →

License

MIT