rabbitmq-tests
Tests RabbitMQ producer/consumer interactions - supports AMQP 0.9.1 and AMQP 1.0 protocols across 6 tutorial patterns (Hello World, Work Queues, Publish/Subscribe, Routing, Topics, RPC) plus Publisher Confirms; consumer ack/nack/requeue patterns; durable queues + persistent messages; quorum vs classic queue; tests via Testcontainers RabbitMQ image or LocalStack-equivalent. Use when the user works with RabbitMQ producers/consumers (pika, amqplib, RabbitMQ.Client, spring-amqp) and needs unit/integration tests.
Install with skills.sh (any agent)
npx skills add testland/qa --skill rabbitmq-testsrabbitmq-tests
Overview
RabbitMQ is the leading OSS AMQP message broker. Per rabbitmq.com/tutorials (opens in new window), the canonical learning path is six tutorials covering progressively more sophisticated patterns:
| Tutorial | Pattern |
|---|---|
| Hello World! | Single producer → single consumer |
| Work Queues | Producer → multiple competing consumers (round-robin) |
| Publish/Subscribe | Fanout exchange → multiple consumers (broadcast) |
| Routing | Direct exchange with routing keys |
| Topics | Topic exchange with wildcard routing patterns |
| RPC | Request-reply via reply-to + correlation-id |
All six tutorials exist in both AMQP 0.9.1 and AMQP 1.0 variants per rmq-tut (opens in new window); AMQP 0.9.1 also has a 7th tutorial - Publisher Confirms - for delivery guarantees.
Per rmq-tut (opens in new window): "Executable versions of these tutorials are open source (opens in new window)."
When to use
Step 1 - Test approach
Three approaches:
| Approach | Pros | Cons |
|---|---|---|
| Mock the AMQP client (pika.BlockingConnection, amqplib Channel) | Fast, no broker dep | Doesn't catch protocol-level behavior (ack races, requeue ordering) |
| Testcontainers RabbitMQ (Docker image per test class) | Full AMQP semantics, isolated | Slower; container startup cost |
| Shared dev RabbitMQ instance | Fast | Test interference; queue cleanup discipline required |
Pick Testcontainers for integration tests; mocking for pure producer-logic unit tests.
Step 2 - Testcontainers setup (Python)
from testcontainers.rabbitmq import RabbitMqContainer
import pika
@pytest.fixture(scope="session")
def rabbitmq():
with RabbitMqContainer("rabbitmq:3-management") as rmq:
yield rmq
@pytest.fixture
def channel(rabbitmq):
conn = pika.BlockingConnection(pika.URLParameters(rabbitmq.get_connection_url()))
ch = conn.channel()
yield ch
conn.close()(Testcontainers cleans up the container automatically when the fixture scope ends.)
Step 3 - Hello World pattern (basic publish + consume)
Producer side:
def publish_order(channel, order_data):
channel.queue_declare(queue='orders', durable=True)
channel.basic_publish(
exchange='',
routing_key='orders',
body=json.dumps(order_data),
properties=pika.BasicProperties(delivery_mode=2), # persistent
)Test:
def test_publish_order(channel):
publish_order(channel, {"id": 1})
method, props, body = channel.basic_get(queue='orders', auto_ack=True)
assert method is not None
assert json.loads(body) == {"id": 1}Step 4 - Test consumer ack / nack / requeue
def consume_order(channel):
method, props, body = channel.basic_get(queue='orders')
if method is None:
return None
try:
process(body)
channel.basic_ack(method.delivery_tag)
return body
except TransientError:
channel.basic_nack(method.delivery_tag, requeue=True) # requeue for retry
raise
except PermanentError:
channel.basic_nack(method.delivery_tag, requeue=False) # to DLX if configured
raiseTest the requeue path:
def test_consumer_requeues_on_transient_error(channel, mocker):
channel.queue_declare(queue='orders', durable=True)
channel.basic_publish(exchange='', routing_key='orders', body='msg-1')
mocker.patch('proj.consumer.process', side_effect=TransientError)
with pytest.raises(TransientError):
consume_order(channel)
# Message should be back in the queue:
method, _, body = channel.basic_get(queue='orders', auto_ack=True)
assert body == b'msg-1'Step 5 - Test dead-letter exchange (DLX)
channel.exchange_declare(exchange='dlx', exchange_type='direct', durable=True)
channel.queue_declare(queue='orders-dlq', durable=True)
channel.queue_bind(queue='orders-dlq', exchange='dlx', routing_key='orders')
channel.queue_declare(
queue='orders',
durable=True,
arguments={
'x-dead-letter-exchange': 'dlx',
'x-dead-letter-routing-key': 'orders',
},
)After basic_nack(requeue=False) or message TTL expiry, the message routes to orders-dlq. Test by consuming from the DLQ.
Step 6 - Publisher Confirms
Per the AMQP 0.9.1 Publisher Confirms tutorial (per rmq-tut (opens in new window)):
channel.confirm_delivery()
try:
channel.basic_publish(
exchange='',
routing_key='orders',
body='order-1',
mandatory=True,
properties=pika.BasicProperties(delivery_mode=2),
)
# If the broker can't route or persist, raises pika.exceptions.UnroutableError
# or NackError. Otherwise the message was confirmed.
except pika.exceptions.UnroutableError:
raiseFor tests asserting publisher confirms succeed, simply enable confirm mode and assert no exception.
Step 7 - Quorum queue testing
Quorum queues (since RabbitMQ 3.8) replace mirrored classic queues for HA. Test pattern is identical to classic queues at the API level; the difference is in arguments:
channel.queue_declare(
queue='orders',
durable=True,
arguments={'x-queue-type': 'quorum'},
)Quorum-specific testing (e.g., partition-tolerance) requires multi-node clusters - Jepsen-style; out of scope for typical integration tests.
Step 8 - CI integration
services:
rabbitmq:
image: rabbitmq:3-management
ports: [5672:5672, 15672:15672]
options: >-
--health-cmd "rabbitmq-diagnostics ping"
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- run: pytest tests/integration/amqp/ -vThe :management tag includes the management UI on port 15672 for debugging in CI logs.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
Use auto_ack=True for tests of error paths | Message ack-ed before processing → no requeue test possible | auto_ack=False (Step 4) |
Test publisher without confirm_delivery() | Can't assert delivery happened - broker may have dropped the message | Enable confirm mode (Step 6) |
| Skip queue cleanup between tests | Stale messages cause flaky assertions | queue_purge or per-test queue names |
Use durable=False on production-mirrored queues in tests | Tests pass; production loses messages on broker restart | Match production queue config in tests |
Limitations
References
Related skills
bullmq-tests
Authors and runs BullMQ job tests in TypeScript / JavaScript - `Queue` and `Worker` patterns, processor mocking, retry/backoff/repeat-job assertions, FlowProducer for parent-child job dependencies, QueueEvents listeners; tests use a real Redis instance (Docker / Testcontainers / `ioredis-mock` for stricter unit-test isolation). Use when the user works with BullMQ in Node.js services and needs unit / integration tests for queue producers, worker processors, or flow orchestration.
celery-tests
Authors and runs Celery task tests in Python - `pytest-celery` fixtures (`celery_app`, `celery_worker` per-test, `celery_session_worker` per-session); `task_always_eager` config NOT recommended for unit tests; `apply()` for synchronous test invocation; mock-and-patch retry patterns via `unittest.mock.patch` on `task.retry`. Use when the user works with Celery task workers and needs unit / integration tests across function-style or class-style tasks.
cron-job-test-author
Build-an-X for cron / scheduler job tests - cron-expression validation patterns (5-field standard `min hour day-month month day-week` + 6-field with seconds + named-list extensions), DST + leap-day edge cases, missed-execution detection (machine downtime catch-up), overlapping-run protection (lock + stale-lock recovery), timezone semantics. Use when authoring tests for cron jobs, Kubernetes CronJobs, BullMQ repeat-jobs, Sidekiq schedulers, or any time-based job runner.
idempotency-test-author
Build-an-X for idempotency tests in any async/job/API context - idempotency-key handling (per Stripe / AWS prescriptive guidance pattern), retry-safe semantics (exactly-once vs at-least-once vs at-most-once), side-effect commutativity verification, fingerprint-based dedup, idempotency-window tuning. Use when authoring tests for any system where the same input could be processed twice (SQS Standard at-least-once, RabbitMQ requeue, retry-on-error logic, webhook redelivery, browser double-click, mobile-network retry).
kafka-consumer-tests
Tests Apache Kafka consumer and producer logic across KafkaJS (Node.js), kafka-go (Go), and Spring Kafka (Java) - spins up a real broker via the Testcontainers Kafka module, asserts offset management and consumer-group rebalance behavior, distinguishes at-least-once from exactly-once (EOS / transactions), validates idempotent producer configuration, and routes unprocessable messages to a dead-letter topic. Use when the user works with Kafka producers or consumers in any language and needs integration or unit tests that exercise delivery semantics, offset commits, rebalance handling, or dead-letter routing.
sidekiq-tests
Authors and runs Sidekiq job tests in Ruby - three Sidekiq::Testing modes (`fake!` jobs accumulate in arrays, `inline!` runs jobs immediately, `disable!` enqueues to Redis as normal); RSpec + Minitest helper patterns; clears jobs between tests via `Sidekiq::Worker.clear_all`; assertion patterns on `MyWorker.jobs.size` and `MyWorker.jobs.first[:args]`. Use when the user works with Sidekiq workers and needs unit / integration tests for job enqueueing, scheduling, retry behavior, or unique-job semantics.
sqs-tests
Tests AWS SQS queue interactions - Standard (at-least-once delivery, near-unlimited throughput) vs FIFO (exactly-once processing, ordered) queue semantics; visibility-timeout interaction model; dead-letter queue (DLQ) for poison-message isolation; message retention period (default 4 days, configurable 60s - 1209600s); test patterns via LocalStack or `aws-sdk-client-mock` (TypeScript) / `moto` (Python). Use when the user works with AWS SQS producers/consumers and needs unit/integration tests for queue interactions.