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.
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:
- Message producers — services that call
RabbitTemplate.convertAndSend() - Message listeners —
@RabbitListener-annotated methods that process incoming messages - 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.