Testing RabbitMQ with Spring AMQP Test Support

RabbitMQ occupies a different niche from Kafka — it excels at task queues, request-reply patterns, and routing scenarios where Kafka would be overkill.

Testing RabbitMQ with Spring AMQP Test Support

RabbitMQ occupies a different niche from Kafka — it excels at task queues, request-reply patterns, and routing scenarios where Kafka would be overkill. Spring AMQP provides excellent abstractions for working with RabbitMQ, but testing those abstractions correctly requires careful setup. The wrong approach leads to tests that pass in isolation but fail when message ordering, exchange routing, or dead-letter behavior matters.

This guide covers the full spectrum of Spring AMQP testing: unit testing with mocks, integration testing with Testcontainers, and testing complex patterns like dead letter exchanges, retry policies, and request-reply messaging.

Testing Layers in Spring AMQP Applications

A typical Spring AMQP application has three distinct testable layers:

  1. Message producers — services that call RabbitTemplate.convertAndSend()
  2. Message listeners — @RabbitListener-annotated methods that process incoming messages
  3. Exchange/queue topology — bindings, routing keys, DLX configuration

Each layer needs a different testing strategy. Mock-based unit tests are appropriate for producer business logic; Testcontainers integration tests are necessary for topology validation and end-to-end flows.

Unit Testing Producers with Mocks

For producer unit tests, you do not need a real broker. Mock the RabbitTemplate and verify the correct exchange, routing key, and message content:

@ExtendWith(MockitoExtension.class)
class OrderEventPublisherTest {

    @Mock
    private RabbitTemplate rabbitTemplate;

    @InjectMocks
    private OrderEventPublisher publisher;

    @Test
    void shouldPublishOrderCreatedEventToCorrectExchange() {
        OrderCreatedEvent event = new OrderCreatedEvent("ORD-001", "CUST-123",
            new BigDecimal("149.99"));

        publisher.publishOrderCreated(event);

        ArgumentCaptor<OrderCreatedEvent> messageCaptor =
            ArgumentCaptor.forClass(OrderCreatedEvent.class);
        verify(rabbitTemplate).convertAndSend(
            eq("orders.exchange"),
            eq("orders.created"),
            messageCaptor.capture()
        );

        OrderCreatedEvent captured = messageCaptor.getValue();
        assertThat(captured.orderId()).isEqualTo("ORD-001");
        assertThat(captured.amount()).isEqualByComparingTo(new BigDecimal("149.99"));
    }

    @Test
    void shouldPropagateAmqpExceptionOnBrokerUnavailable() {
        doThrow(new AmqpException("Broker unavailable"))
            .when(rabbitTemplate).convertAndSend(anyString(), anyString(), any());

        assertThatThrownBy(() -> publisher.publishOrderCreated(
            new OrderCreatedEvent("ORD-002", "CUST-456", BigDecimal.TEN)))
            .isInstanceOf(AmqpException.class);
    }
}

Integration Testing with Testcontainers

For full integration tests with real queue and exchange behavior:

@SpringBootTest
@Testcontainers
public abstract class RabbitMQIntegrationTestBase {

    @Container
    static final RabbitMQContainer rabbitMQ = new RabbitMQContainer(
            DockerImageName.parse("rabbitmq:3.13-management"))
        .withReuse(true);

    @DynamicPropertySource
    static void rabbitMQProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.rabbitmq.host", rabbitMQ::getHost);
        registry.add("spring.rabbitmq.port", rabbitMQ::getAmqpPort);
        registry.add("spring.rabbitmq.username", () -> "guest");
        registry.add("spring.rabbitmq.password", () -> "guest");
    }
}

The rabbitmq:3.13-management image includes the management plugin, exposing the HTTP API for inspecting queue stats from tests.

Setting Up Topology in Test Configuration

Define exchanges, queues, and bindings explicitly so topology is validated by tests:

@TestConfiguration
public class RabbitMQTestConfig {

    public static final String ORDERS_EXCHANGE = "orders.exchange";
    public static final String ORDERS_QUEUE = "orders.queue";
    public static final String ORDERS_DLX = "orders.dlx";
    public static final String ORDERS_DLQ = "orders.dlq";

    @Bean
    public TopicExchange ordersExchange() {
        return new TopicExchange(ORDERS_EXCHANGE);
    }

    @Bean
    public DirectExchange deadLetterExchange() {
        return new DirectExchange(ORDERS_DLX);
    }

    @Bean
    public Queue ordersQueue() {
        return QueueBuilder.durable(ORDERS_QUEUE)
            .withArgument("x-dead-letter-exchange", ORDERS_DLX)
            .withArgument("x-dead-letter-routing-key", "dead.orders")
            .withArgument("x-message-ttl", 30000)
            .build();
    }

    @Bean
    public Queue deadLetterQueue() {
        return QueueBuilder.durable(ORDERS_DLQ).build();
    }

    @Bean
    public Binding ordersBinding(Queue ordersQueue, TopicExchange ordersExchange) {
        return BindingBuilder.bind(ordersQueue)
            .to(ordersExchange).with("orders.#");
    }

    @Bean
    public Binding deadLetterBinding(Queue deadLetterQueue,
                                      DirectExchange deadLetterExchange) {
        return BindingBuilder.bind(deadLetterQueue)
            .to(deadLetterExchange).with("dead.orders");
    }
}

Testing Message Consumption

@Service
public class OrderEventListener {

    private final List<OrderCreatedEvent> processedOrders = new CopyOnWriteArrayList<>();
    private final CountDownLatch latch = new CountDownLatch(1);

    @RabbitListener(queues = RabbitMQTestConfig.ORDERS_QUEUE)
    public void onOrderCreated(OrderCreatedEvent event) {
        processedOrders.add(event);
        latch.countDown();
    }

    public List<OrderCreatedEvent> getProcessedOrders() {
        return Collections.unmodifiableList(processedOrders);
    }

    public CountDownLatch getLatch() { return latch; }
}
class OrderEventListenerTest extends RabbitMQIntegrationTestBase {

    @Autowired
    private RabbitTemplate rabbitTemplate;

    @Autowired
    private OrderEventListener listener;

    @Test
    void shouldConsumeOrderCreatedEvent() throws Exception {
        OrderCreatedEvent event = new OrderCreatedEvent("ORD-001", "CUST-123",
            new BigDecimal("199.99"));

        rabbitTemplate.convertAndSend(
            RabbitMQTestConfig.ORDERS_EXCHANGE, "orders.created", event);

        boolean consumed = listener.getLatch().await(10, TimeUnit.SECONDS);
        assertThat(consumed).isTrue();
        assertThat(listener.getProcessedOrders()).hasSize(1);

        OrderCreatedEvent received = listener.getProcessedOrders().get(0);
        assertThat(received.orderId()).isEqualTo("ORD-001");
        assertThat(received.amount()).isEqualByComparingTo(new BigDecimal("199.99"));
    }

    @Test
    void shouldRouteWildcardRoutingKeyToOrdersQueue() throws Exception {
        OrderCreatedEvent event = new OrderCreatedEvent("ORD-002", "CUST-456",
            new BigDecimal("49.99"));

        // "orders.created.express" matches "orders.#" wildcard
        rabbitTemplate.convertAndSend(
            RabbitMQTestConfig.ORDERS_EXCHANGE, "orders.created.express", event);

        assertThat(listener.getLatch().await(10, TimeUnit.SECONDS)).isTrue();
        assertThat(listener.getProcessedOrders()).hasSize(1);
    }
}

Testing Dead Letter Exchange Behavior

DLX testing is among the most valuable integration tests. A misconfigured DLX silently swallows rejected messages:

@Test
void shouldRouteRejectedMessageToDeadLetterQueue() throws Exception {
    List<Message> deadLetterMessages = new CopyOnWriteArrayList<>();
    CountDownLatch dlqLatch = new CountDownLatch(1);

    // Consume from DLQ to observe dead-lettered messages
    rabbitTemplate.execute(channel -> {
        channel.basicConsume(RabbitMQTestConfig.ORDERS_DLQ, true,
            (tag, delivery) -> {
                deadLetterMessages.add(
                    new Message(delivery.getBody(), new MessageProperties()));
                dlqLatch.countDown();
            },
            tag -> {});
        return null;
    });

    // Configure a listener that always rejects
    SimpleMessageListenerContainer container =
        new SimpleMessageListenerContainer(connectionFactory);
    container.setQueueNames(RabbitMQTestConfig.ORDERS_QUEUE);
    container.setMessageListener((MessageListener) message -> {
        throw new AmqpRejectAndDontRequeueException("Always reject");
    });
    container.start();

    // Send a message that will be rejected
    OrderCreatedEvent event = new OrderCreatedEvent("ORD-FAIL", "CUST-999",
        new BigDecimal("1.00"));
    rabbitTemplate.convertAndSend(
        RabbitMQTestConfig.ORDERS_EXCHANGE, "orders.created", event);

    // Assert dead-lettered message appears on DLQ
    assertThat(dlqLatch.await(15, TimeUnit.SECONDS)).isTrue();
    assertThat(deadLetterMessages).hasSize(1);

    container.stop();
}

Testing Retry Policies

Spring AMQP's retry interceptor should be tested to verify the correct number of attempts:

@Configuration
public class RetryConfig {

    @Bean
    public SimpleRabbitListenerContainerFactory rabbitListenerContainerFactory(
            ConnectionFactory connectionFactory) {
        SimpleRabbitListenerContainerFactory factory =
            new SimpleRabbitListenerContainerFactory();
        factory.setConnectionFactory(connectionFactory);

        factory.setAdviceChain(RetryInterceptorBuilder.stateless()
            .maxAttempts(3)
            .backOffOptions(500, 2.0, 5000)
            .recoverer(new RejectAndDontRequeueRecoverer())
            .build());

        return factory;
    }
}
@Test
void shouldRetryExactlyThreeTimesBeforeDeadLettering() throws Exception {
    AtomicInteger processAttempts = new AtomicInteger(0);
    CountDownLatch dlqLatch = new CountDownLatch(1);

    SimpleMessageListenerContainer container =
        new SimpleMessageListenerContainer(connectionFactory);
    container.setQueueNames(RabbitMQTestConfig.ORDERS_QUEUE);
    container.setAdviceChain(RetryInterceptorBuilder.stateless()
        .maxAttempts(3)
        .backOffOptions(100, 1.0, 100)  // Fast for tests
        .recoverer(new RejectAndDontRequeueRecoverer())
        .build());

    container.setMessageListener((MessageListener) message -> {
        processAttempts.incrementAndGet();
        throw new RuntimeException("Simulated failure");
    });
    container.start();

    // DLQ listener
    rabbitTemplate.execute(channel -> {
        channel.basicConsume(RabbitMQTestConfig.ORDERS_DLQ, true,
            (tag, delivery) -> dlqLatch.countDown(), tag -> {});
        return null;
    });

    rabbitTemplate.convertAndSend(
        RabbitMQTestConfig.ORDERS_EXCHANGE, "orders.created",
        new OrderCreatedEvent("ORD-RETRY", "CUST-1", BigDecimal.ONE));

    assertThat(dlqLatch.await(20, TimeUnit.SECONDS)).isTrue();
    assertThat(processAttempts.get()).isEqualTo(3);

    container.stop();
}

Testing Request-Reply (RPC) Pattern

RabbitMQ's request-reply pattern via convertSendAndReceive is common for synchronous messaging over AMQP:

@Service
public class InventoryService {

    private final RabbitTemplate rabbitTemplate;

    public InventoryResponse checkStock(String productId, int quantity) {
        InventoryRequest request = new InventoryRequest(productId, quantity);
        return (InventoryResponse) rabbitTemplate.convertSendAndReceive(
            "inventory.exchange", "inventory.check", request);
    }
}
@Test
void shouldReceiveInventoryResponseFromRpcCall() throws Exception {
    // Start a responder that simulates the inventory microservice
    SimpleMessageListenerContainer responder =
        new SimpleMessageListenerContainer(connectionFactory);
    responder.setQueueNames("inventory.queue");
    responder.setMessageListener((ChannelAwareMessageListener) (message, channel) -> {
        byte[] responseBody = objectMapper.writeValueAsBytes(
            new InventoryResponse(true, 50));

        AMQP.BasicProperties replyProps = new AMQP.BasicProperties.Builder()
            .correlationId(message.getMessageProperties().getCorrelationId())
            .build();

        channel.basicPublish("",
            message.getMessageProperties().getReplyTo(),
            replyProps, responseBody);
    });
    responder.start();

    // Act
    InventoryResponse response = inventoryService.checkStock("PROD-001", 10);

    // Assert
    assertThat(response).isNotNull();
    assertThat(response.inStock()).isTrue();
    assertThat(response.availableQuantity()).isEqualTo(50);

    responder.stop();
}

Testing Queue Properties via Management HTTP API

The management plugin lets you verify queue topology programmatically:

@Test
void shouldCreateOrdersQueueWithDeadLetterExchangeConfigured() throws Exception {
    String managementUrl = String.format("http://%s:%d/api",
        rabbitMQ.getHost(), rabbitMQ.getMappedPort(15672));

    RestTemplate rest = new RestTemplate();
    HttpHeaders headers = new HttpHeaders();
    headers.setBasicAuth("guest", "guest");

    ResponseEntity<Map> response = rest.exchange(
        managementUrl + "/queues/%2F/" + RabbitMQTestConfig.ORDERS_QUEUE,
        HttpMethod.GET,
        new HttpEntity<>(headers),
        Map.class);

    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    Map<?, ?> body = response.getBody();
    assertThat(body).isNotNull();
    assertThat(body.get("durable")).isEqualTo(true);

    Map<?, ?> args = (Map<?, ?>) body.get("arguments");
    assertThat(args).containsEntry("x-dead-letter-exchange", RabbitMQTestConfig.ORDERS_DLX);
    assertThat(args).containsEntry("x-dead-letter-routing-key", "dead.orders");
}

Testing Manual Acknowledgment

Verifying that your listener correctly acknowledges messages in MANUAL ack mode prevents ghost messages — messages that are stuck in unacked state on the broker:

@Test
void shouldManuallyAcknowledgeMessageAfterSuccessfulProcessing() throws Exception {
    CountDownLatch ackLatch = new CountDownLatch(1);
    List<Long> ackedTags = new CopyOnWriteArrayList<>();

    SimpleMessageListenerContainer container =
        new SimpleMessageListenerContainer(connectionFactory);
    container.setQueueNames(RabbitMQTestConfig.ORDERS_QUEUE);
    container.setAcknowledgeMode(AcknowledgeMode.MANUAL);
    container.setMessageListener((ChannelAwareMessageListener) (message, channel) -> {
        long tag = message.getMessageProperties().getDeliveryTag();
        channel.basicAck(tag, false);
        ackedTags.add(tag);
        ackLatch.countDown();
    });
    container.start();

    rabbitTemplate.convertAndSend(
        RabbitMQTestConfig.ORDERS_EXCHANGE, "orders.created",
        new OrderCreatedEvent("ORD-ACK", "CUST-1", BigDecimal.TEN));

    assertThat(ackLatch.await(10, TimeUnit.SECONDS)).isTrue();
    assertThat(ackedTags).hasSize(1);

    container.stop();
}

Key Takeaways

Spring AMQP testing requires all three layers working together:

  • Mock-based unit tests for producer business logic — fast and isolated
  • Testcontainers integration tests for routing, topology, and end-to-end flows with a real broker
  • Management API assertions for verifying queue configuration such as DLX settings and TTL

The dead letter exchange test is the highest-value test you can add to a RabbitMQ-backed application. Teams routinely deploy DLX configurations that look correct but have a wrong routing key or missing binding — messages get rejected and vanish silently. An integration test that confirms rejected messages appear on the DLQ is the only reliable way to catch this before production.

Read more

Start now free