IBM MQ Testing: JMS Unit Tests, IBM MQ Dev Container, and Spring JMS Integration

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: passw0rd

Default 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.

Read more

Start now free