RabbitMQ Integration Testing

Quick References: See quick-ref/spring-rabbit-test.md for @SpringRabbitTest details, quick-ref/testcontainers-rabbitmq.md for Testcontainers patterns.

Testing Approach Selection

| Approach | Speed | Fidelity | Best For | |----------|-------|----------|----------| | @SpringRabbitTest + Harness | Fast (no broker) | Medium (spy/capture) | Testing listener logic with Spring context | | TestRabbitTemplate | Fast (no broker) | Low (no routing) | Testing send/receive without real broker | | Testcontainers RabbitMQContainer | Slow (~5s startup) | Highest (real broker) | Full integration tests, exchange/queue routing |

Decision rule: Use @SpringRabbitTest for unit-testing listeners in Spring context. Use Testcontainers for end-to-end message flow with real routing.

Java/Spring: @SpringRabbitTest + RabbitListenerTestHarness

Dependencies

<dependency>
    <groupId>org.springframework.amqp</groupId>
    <artifactId>spring-rabbit-test</artifactId>
    <scope>test</scope>
</dependency>

Spy Pattern — Verify Listener Called

@SpringBootTest
@SpringRabbitTest
class OrderConsumerSpyTest {

    @Autowired
    private RabbitListenerTestHarness harness;

    @Autowired
    private RabbitTemplate rabbitTemplate;

    @Test
    void shouldInvokeListener() throws Exception {
        OrderConsumer spy = harness.getSpy("orderListener");
        assertThat(spy).isNotNull();

        LatchCountDownAndCallRealMethodAnswer answer =
            harness.getLatchAnswerFor("orderListener", 1);

        rabbitTemplate.convertAndSend("orders.exchange", "orders.created",
            new OrderEvent("123", "CREATED"));

        assertThat(answer.await(10)).isTrue();
        verify(spy).handleOrder(argThat(e -> e.getOrderId().equals("123")));
    }
}

Capture Pattern — Inspect Invocation Data

@SpringBootTest
@SpringRabbitTest
class OrderConsumerCaptureTest {

    @Autowired
    private RabbitListenerTestHarness harness;

    @Autowired
    private RabbitTemplate rabbitTemplate;

    @Test
    void shouldCaptureInvocationData() throws Exception {
        rabbitTemplate.convertAndSend("orders.exchange", "orders.created",
            new OrderEvent("456", "PAID"));

        InvocationData data = harness.getNextInvocationDataFor(
            "orderListener", 10, TimeUnit.SECONDS);

        assertThat(data).isNotNull();
        OrderEvent captured = (OrderEvent) data.getArguments()[0];
        assertThat(captured.getOrderId()).isEqualTo("456");
        assertThat(captured.getStatus()).isEqualTo("PAID");
    }
}

Request-Reply Test

@SpringBootTest
@SpringRabbitTest
class OrderServiceReplyTest {

    @Autowired
    private RabbitTemplate rabbitTemplate;

    @Test
    void shouldReturnOrderResponse() {
        OrderRequest request = new OrderRequest("item-1", 2);

        OrderResponse response = (OrderResponse) rabbitTemplate.convertSendAndReceive(
            "orders.exchange", "orders.create", request);

        assertThat(response).isNotNull();
        assertThat(response.getStatus()).isEqualTo("CREATED");
    }
}

Java/Spring: TestRabbitTemplate

For testing without a running broker:

@SpringBootTest
@SpringRabbitTest
class NoBrokerTest {

    @Autowired
    private TestRabbitTemplate testRabbitTemplate;

    @Test
    void shouldSendWithoutBroker() {
        testRabbitTemplate.convertAndSend("orders.exchange", "orders.created",
            new OrderEvent("789", "CREATED"));

        // TestRabbitTemplate routes directly to @RabbitListener methods
        // Verify side effects (database writes, service calls, etc.)
    }
}

Java/Spring: Testcontainers RabbitMQContainer

With @ServiceConnection (Spring Boot 3.1+)

@SpringBootTest
@Testcontainers
class RabbitIntegrationTest {

    @Container
    @ServiceConnection
    static RabbitMQContainer rabbit = new RabbitMQContainer("rabbitmq:3.13-management");

    @Autowired
    private RabbitTemplate rabbitTemplate;

    @Autowired
    private OrderRepository orderRepository;

    @Test
    void shouldProduceAndConsumeOrder() {
        rabbitTemplate.convertAndSend("orders.exchange", "orders.created",
            new OrderEvent("123", "CREATED"));

        await().atMost(Duration.ofSeconds(10))
            .untilAsserted(() -> {
                Optional<Order> order = orderRepository.findById("123");
                assertThat(order).isPresent();
                assertThat(order.get().getStatus()).isEqualTo("CREATED");
            });
    }
}

Pre-Provisioned Exchanges and Queues

static RabbitMQContainer rabbit = new RabbitMQContainer("rabbitmq:3.13-management")
    .withExchange("orders.exchange", "direct")
    .withQueue("orders.queue")
    .withBinding("orders.exchange", "orders.queue",
        Map.of(), "orders.created", "queue");

With @DynamicPropertySource (pre-3.1)

@DynamicPropertySource
static void rabbitProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.rabbitmq.host", rabbit::getHost);
    registry.add("spring.rabbitmq.port", rabbit::getAmqpPort);
    registry.add("spring.rabbitmq.username", rabbit::getAdminUsername);
    registry.add("spring.rabbitmq.password", rabbit::getAdminPassword);
}

Node.js: amqplib + Testcontainers

import { RabbitMQContainer } from "@testcontainers/rabbitmq";
import amqp from "amqplib";

describe("RabbitMQ Integration", () => {
  let container: StartedTestContainer;
  let connection: amqp.Connection;

  beforeAll(async () => {
    container = await new RabbitMQContainer("rabbitmq:3.13-management").start();
    connection = await amqp.connect(container.getAmqpUrl());
  }, 60_000);

  afterAll(async () => {
    await connection.close();
    await container.stop();
  });

  it("should produce and consume messages", async () => {
    const channel = await connection.createChannel();
    const queue = "test-queue";
    await channel.assertQueue(queue, { durable: false });

    const message = { orderId: "123", status: "CREATED" };
    channel.sendToQueue(queue, Buffer.from(JSON.stringify(message)));

    const received = await new Promise<any>((resolve) => {
      channel.consume(queue, (msg) => {
        if (msg) resolve(JSON.parse(msg.content.toString()));
      });
    });

    expect(received.orderId).toBe("123");
    await channel.close();
  });
});

Python: pika + Testcontainers

import pytest
import pika
import json
from testcontainers.rabbitmq import RabbitMqContainer

@pytest.fixture(scope="module")
def rabbitmq():
    with RabbitMqContainer("rabbitmq:3.13-management") as container:
        yield container

def test_produce_and_consume(rabbitmq):
    params = pika.ConnectionParameters(
        host=rabbitmq.get_container_host_ip(),
        port=rabbitmq.get_exposed_port(5672),
        credentials=pika.PlainCredentials("guest", "guest"),
    )
    connection = pika.BlockingConnection(params)
    channel = connection.channel()
    channel.queue_declare(queue="test-queue")

    message = {"orderId": "123", "status": "CREATED"}
    channel.basic_publish(exchange="", routing_key="test-queue",
                          body=json.dumps(message))

    method, props, body = channel.basic_get(queue="test-queue", auto_ack=True)
    assert method is not None
    assert json.loads(body)["orderId"] == "123"

    connection.close()

Anti-Patterns

| Anti-Pattern | Problem | Solution | |--------------|---------|----------| | Not using @SpringRabbitTest | Manual harness setup | Annotation auto-configures harness and template | | Ignoring InvocationData timeout | Flaky or hanging tests | Always pass timeout to getNextInvocationDataFor() | | Hardcoded exchange/queue names in tests | Coupling to production config | Use constants or test-specific names | | No await() for async consumers | Assertions run before consumption | Use Awaitility or CountDownLatch | | Starting broker per test method | Extremely slow | Use static container shared across tests |

Quick Troubleshooting

| Problem | Cause | Solution | |---------|-------|----------| | Harness returns null spy | Listener ID mismatch | Verify @RabbitListener(id = "...") matches harness call | | "No queue bound" error | Exchange/queue not declared | Use @QueueBinding or pre-provision in container | | Message not received | Wrong routing key | Verify exchange type and binding key match | | Connection refused in tests | Container not ready | Use @ServiceConnection or wait for port | | TestRabbitTemplate silent failure | No listener found | Ensure @RabbitListener is in Spring context |

Reference Documentation

• Spring AMQP Testing
• Testcontainers RabbitMQ Module

Cross-reference: For Spring AMQP producer/consumer patterns, see spring-amqp skill. For generic Testcontainers patterns, see testcontainers skill.