IBM MQ Testing: JMS Unit Tests, IBM MQ Dev Container, and Spring JMS Integration
```tldr IBM MQ testing uses three approaches: JMS mocks (ActiveMQ Artemis or Mockito) for fast unit tests, the IBM MQ Developer Docker image for realistic integration tests, and Spring JMS test utilities for Spring-based applications. The IBM MQ Developer container is free, starts in under 30 seconds, and supports the full MQ feature set. ```
```takeaways The IBM MQ Developer Docker image (icr.io/ibm-messaging/mq) is free for development and testing. It includes a pre-configured queue manager and supports the full JMS 2.0 API.
Use ActiveMQ Artemis as an IBM MQ stub for unit tests. It's JMS-compatible and starts in milliseconds — no Docker needed for pure unit tests.
Spring JMS's JmsTemplate and @JmsListener are both testable with EmbeddedActiveMQ. The IBM-specific features (MQMD headers, MQ message properties) require the real container.
XA transactions (two-phase commit) require a real IBM MQ broker. No stub supports XA — use the Docker container for XA transaction tests.
Test message selectors explicitly. Selectors filter messages by JMS properties — verify that your consumer only receives intended message types. ```
Approach 1: JMS Mock With ActiveMQ Artemis
For unit tests that don't need IBM MQ-specific features, Artemis provides a JMS 2.0-compatible broker:
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>artemis-jms-server</artifactId>
<version>2.34.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.ibm.mq</groupId>
<artifactId>com.ibm.mq.allclient</artifactId>
<version>9.3.4.1</version>
</dependency>import org.apache.activemq.artemis.jms.server.embedded.EmbeddedJMS;
class MessageSenderTest {
private EmbeddedJMS server;
private javax.jms.ConnectionFactory connectionFactory;
@BeforeEach
void startServer() throws Exception {
server = new EmbeddedJMS().start();
connectionFactory = (ConnectionFactory) server.lookup("ConnectionFactory");
}
@AfterEach
void stopServer() throws Exception {
server.stop();
}
@Test
void sendMessage_putsMsgOnQueue() throws Exception {
String queueName = "DEV.QUEUE.1";
MessageSender sender = new MessageSender(connectionFactory);
sender.send(queueName, "test payload");
try (Connection conn = connectionFactory.createConnection();
Session session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE)) {
conn.start();
Queue queue = session.createQueue(queueName);
MessageConsumer consumer = session.createConsumer(queue);
TextMessage msg = (TextMessage) consumer.receive(2000);
assertNotNull(msg);
assertEquals("test payload", msg.getText());
}
}
}Approach 2: IBM MQ Developer Docker Container
# docker-compose.yml
services:
ibm-mq:
image: icr.io/ibm-messaging/mq:latest
ports:
- "1414:1414" # MQ listener
- "9443:9443" # MQ Console (HTTPS)
environment:
LICENSE: accept
MQ_QMGR_NAME: QM1
MQ_APP_PASSWORD: passw0rd
MQ_ADMIN_PASSWORD: passw0rdDefault pre-created queues: DEV.QUEUE.1, DEV.QUEUE.2, DEV.QUEUE.3, DEV.DEAD.LETTER.QUEUE.
Connect With IBM MQ JMS Client
import com.ibm.mq.jms.MQConnectionFactory;
import com.ibm.msg.client.wmq.WMQConstants;
MQConnectionFactory factory = new MQConnectionFactory();
factory.setHostName("localhost");
factory.setPort(1414);
factory.setQueueManager("QM1");
factory.setChannel("DEV.APP.SVRCONN");
factory.setTransportType(WMQConstants.WMQ_CM_CLIENT);
Connection conn = factory.createConnection("app", "passw0rd");
conn.start();Testcontainers Integration
@Testcontainers
class IbmMqIntegrationTest {
@Container
static GenericContainer<?> ibmMq = new GenericContainer<>("icr.io/ibm-messaging/mq:latest")
.withEnv("LICENSE", "accept")
.withEnv("MQ_QMGR_NAME", "QM1")
.withEnv("MQ_APP_PASSWORD", "passw0rd")
.withExposedPorts(1414)
.waitingFor(Wait.forLogMessage(".*Started queue manager.*", 1)
.withStartupTimeout(Duration.ofSeconds(90)));
@Test
void sendAndReceive() throws Exception {
MQConnectionFactory factory = new MQConnectionFactory();
factory.setHostName("localhost");
factory.setPort(ibmMq.getMappedPort(1414));
factory.setQueueManager("QM1");
factory.setChannel("DEV.APP.SVRCONN");
factory.setTransportType(WMQConstants.WMQ_CM_CLIENT);
try (Connection conn = factory.createConnection("app", "passw0rd");
Session session = conn.createSession(false, Session.AUTO_ACKNOWLEDGE)) {
conn.start();
Queue queue = session.createQueue("DEV.QUEUE.1");
session.createProducer(queue).send(session.createTextMessage("hello MQ"));
TextMessage received = (TextMessage) session.createConsumer(queue).receive(5000);
assertNotNull(received);
assertEquals("hello MQ", received.getText());
}
}
}Spring JMS Testing
@SpringBootTest
@EnableJms
class OrderJmsListenerTest {
@Autowired
private JmsTemplate jmsTemplate;
@Autowired
private OrderRepository orderRepository;
@Test
void listenerProcessesIncomingOrder() throws Exception {
CountDownLatch latch = new CountDownLatch(1);
// assume listener calls latch.countDown() on success
jmsTemplate.convertAndSend("DEV.QUEUE.1", "{\"orderId\":\"O-001\",\"amount\":150.00}");
assertTrue(latch.await(10, TimeUnit.SECONDS));
assertTrue(orderRepository.findById("O-001").isPresent());
}
}Message Selector Testing
Selectors filter messages by JMS property:
@Test
void selectorFiltersMessagesByProperty() throws Exception {
Queue queue = session.createQueue("DEV.QUEUE.2");
// Publish messages with different types
Message orderMsg = session.createTextMessage("order event");
orderMsg.setStringProperty("eventType", "ORDER");
producer.send(queue, orderMsg);
Message paymentMsg = session.createTextMessage("payment event");
paymentMsg.setStringProperty("eventType", "PAYMENT");
producer.send(queue, paymentMsg);
// Consumer with selector — only receives ORDER type
MessageConsumer consumer = session.createConsumer(queue, "eventType = 'ORDER'");
conn.start();
TextMessage received = (TextMessage) consumer.receive(3000);
assertEquals("order event", received.getText());
// No more messages matching selector
assertNull(consumer.receive(500));
}Testing MQMD Headers
IBM MQ Message Descriptor (MQMD) headers carry routing and audit information:
@Test
void mqmdHeadersArePreserved() throws Exception {
MQQueue mqQueue = ((MQSession) session).createQueue("DEV.QUEUE.1");
MQQueueSender sender = ((MQSession) session).createSender(mqQueue);
MQMessage mqMsg = ((MQSession) session).createMessage();
((com.ibm.mq.jms.MQTextMessage) mqMsg).setText("payload");
// Set MQMD fields via JMS extension
mqMsg.setJMSCorrelationIDAsBytes(
"corr-id-bytes".getBytes(StandardCharsets.UTF_8)
);
sender.send(mqMsg, DeliveryMode.PERSISTENT, 4, 0); // priority 4
MQQueueReceiver receiver = ((MQSession) session).createReceiver(mqQueue);
conn.start();
Message received = receiver.receive(3000);
assertNotNull(received.getJMSCorrelationIDAsBytes());
assertEquals(4, received.getJMSPriority());
assertEquals(DeliveryMode.PERSISTENT, received.getJMSDeliveryMode());
}Dead Letter Queue Testing
@Test
void undeliverableMessageGoesToDlq() throws Exception {
// Create a consumer that always throws
MessageConsumer badConsumer = session.createConsumer(
session.createQueue("DEV.QUEUE.3")
);
session.createProducer(session.createQueue("DEV.QUEUE.3"))
.send(session.createTextMessage("bad message"));
conn.start();
Message msg = badConsumer.receive(3000);
// Simulate failure — don't ack, let session rollback
session.rollback(); // triggers redelivery → eventually DLQ
// Check DEV.DEAD.LETTER.QUEUE
Thread.sleep(1000);
Queue dlq = session.createQueue("DEV.DEAD.LETTER.QUEUE");
MessageConsumer dlqConsumer = session.createConsumer(dlq);
TextMessage dlqMsg = (TextMessage) dlqConsumer.receive(5000);
assertNotNull(dlqMsg, "Message should be in DLQ after rollback");
}Request-Reply Pattern Testing
IBM MQ is commonly used for synchronous request-reply messaging:
@Test
void requestReplyPattern() throws Exception {
Queue requestQueue = session.createQueue("DEV.QUEUE.1");
TemporaryQueue replyQueue = session.createTemporaryQueue();
// Send request
TextMessage request = session.createTextMessage("get-account");
request.setJMSReplyTo(replyQueue);
request.setJMSCorrelationID("req-001");
session.createProducer(requestQueue).send(request);
// Simulate responder (in real app, this is a separate service)
Message incoming = session.createConsumer(requestQueue).receive(3000);
TextMessage reply = session.createTextMessage("account-data");
reply.setJMSCorrelationID(incoming.getJMSCorrelationID());
session.createProducer(incoming.getJMSReplyTo()).send(reply);
// Assert reply received
String selector = "JMSCorrelationID = 'req-001'";
TextMessage received = (TextMessage) session.createConsumer(replyQueue, selector).receive(3000);
assertNotNull(received);
assertEquals("account-data", received.getText());
}Common IBM MQ Testing Pitfalls
Forgetting conn.start() — JMS connections don't deliver messages until start() is called. This is a common cause of receive() returning null.
Not setting MQ_APP_PASSWORD — the Docker container requires a password for the app user. Connection without credentials fails silently.
Wrong channel name — developer container uses DEV.APP.SVRCONN. Using the wrong channel gives MQRC_UNKNOWN_CHANNEL_NAME (2062).
No LICENSE: accept — the container won't start without this environment variable.
IBM MQ startup time — the container takes 30-90 seconds to fully start. Use waitingFor(Wait.forLogMessage(".*Started queue manager.*")) not just port-based health checks.