Skip to content
MaxoPerf MaxoPerf docs

MQ and messaging testing

IBM MQ (formerly WebSphere MQ, also known as MQSeries) is the messaging backbone of many mainframe and distributed system integrations. Payment processing pipelines, insurance claim routing, and airline booking confirmations all depend on MQ to deliver messages reliably between applications. Performance testing MQ means verifying that the queue manager can sustain the required message throughput, that put and get latencies remain within SLA under peak concurrency, and that queue depth does not grow unboundedly under sustained load. This page covers how to test IBM MQ with JMeter’s JMS sampler and run the test through MaxoPerf.

Before you start

Section titled “Before you start”
  • You need access to an IBM MQ queue manager that is authorized for load testing, with the queue name, channel name, port, and queue manager name.
  • You need the IBM MQ JMS client JAR (com.ibm.mq.allclient.jar), available from the IBM MQ client installation. This JAR is required by JMeter’s JMS sampler to connect to MQ. Confirm with MaxoPerf support whether this JAR is already in the runner image.
  • Coordinate with your MQ administrator to confirm authorized throughput rates, queue depth limits, and the channel MCA user ID for the test.

IBM MQ and JMS

Section titled “IBM MQ and JMS”

IBM MQ implements the Java Message Service (JMS) specification through its MQ JMS client library. JMeter’s JMS Point-to-Point sampler (and the JMS Publisher/Subscriber sampler for pub/sub topics) can connect to MQ as a JMS provider, making JMeter a natural fit for MQ load testing without requiring a custom plugin.

The JMS Point-to-Point sampler supports two operation modes:

ModeWhat it doesUse when
Request only (put)Puts a message to a queue and does not wait for a replyTesting producer throughput, measuring put latency
Request-replyPuts a message to a request queue and waits for a response on a reply queueTesting end-to-end message round-trip latency (full processing cycle)

For most mainframe MQ performance tests, request-reply is the more meaningful measurement: you want to know how long it takes for the consumer application (a CICS or IMS listener, a batch program, or a distributed MQ listener) to process the message and return a reply.

Configuring the JMS sampler for IBM MQ

Section titled “Configuring the JMS sampler for IBM MQ”

JNDI configuration

Section titled “JNDI configuration”

JMeter’s JMS sampler uses JNDI to look up the JMS connection factory and queue. For IBM MQ, you provide a jndi.properties file that defines the MQ connection parameters.

A minimal jndi.properties for IBM MQ (placed in JMeter’s bin/ directory during authoring, and uploaded as a Test asset in MaxoPerf):

# IBM MQ JNDI configuration for JMeter
java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file://${user.home}/JNDI-Directory


# Alternatively, using IBM MQ's built-in JNDI with a file-system context
# Contact your MQ administrator for the correct InitialContext class

JMS Connection Configuration element

Section titled “JMS Connection Configuration element”

Add a JMS Connection Configuration element to your Thread Group:

  • QueueConnection Factory — the JNDI name of the MQ JMS connection factory (as defined in your JNDI context).
  • JNDI name Request queue — the JNDI name of the queue to send messages to.
  • JNDI name Reply queue — the JNDI name of the reply queue (for request-reply mode).
  • Use persistent delivery — set to match your production MQ channel configuration (persistent messages have higher latency than non-persistent).
  • Expiry — set a message expiry to prevent dead messages accumulating on the queue during a failed test run.

JMS Point-to-Point sampler

Section titled “JMS Point-to-Point sampler”

With the connection configuration in place, add a JMS Point-to-Point sampler to each step in your Thread Group:

  • Communication style — Request Only for put-only tests, Request/Reply for round-trip latency.
  • Content — the message body. For mainframe integrations, this is often a fixed-format string, XML, or a binary record format. Use a JMeter variable or CSV Data Set Config element to vary message content across VUs.
  • Correlation — for request-reply, JMeter uses JMS CorrelationID to match reply messages back to their originating request. The sampler handles this automatically when using JMeter’s correlation mode.

Testing patterns

Section titled “Testing patterns”

1. Throughput test — producer rate

Section titled “1. Throughput test — producer rate”

Configure the JMS sampler in Request Only mode. Set the Thread Group to the number of concurrent producer VUs and a target rate (using JMeter’s Constant Throughput Timer to cap puts at a specific messages-per-second rate). Measure:

  • Put latency — how long does QueueSender.send() take? Under high throughput, MQ channel saturation causes this to climb.
  • Throughput — messages per second as reported by MaxoPerf.

2. Round-trip latency test — request-reply

Section titled “2. Round-trip latency test — request-reply”

Configure the JMS sampler in Request/Reply mode. Each sampler measures the full round trip: put to request queue → consumer processes message → put reply to reply queue → JMeter receives reply. This end-to-end time is what MaxoPerf records as response time for the sampler. Measure:

  • p95 response time — the 95th percentile of round-trip message latency. This includes MQ network time plus the consumer application’s processing time.
  • Error rate — messages that expire without a reply (consumer could not keep up) appear as errors.

3. Queue depth soak

Section titled “3. Queue depth soak”

Run a put-only test at a rate slightly higher than the known consumer throughput to observe queue depth growth. Queue depth is not directly visible in MaxoPerf (it is an MQ metric, not a JMeter metric), but your MQ administrator can monitor it via MQ Explorer or runmqsc DISPLAY QSTATUS while the MaxoPerf run is active. A queue depth that grows linearly without plateauing indicates the consumer cannot keep pace with the load — an important finding before a peak window.

Running in MaxoPerf

Section titled “Running in MaxoPerf”

The IBM MQ allclient JAR is not in the JMeter standard distribution. You need to make it available in the MaxoPerf runner image. There are two options:

Option A (recommended) — request runner image inclusion: Contact MaxoPerf support and ask for the IBM MQ JMS client JAR to be added to the JMeter runner image. Once included, your JMX can use it without any Test asset upload.

Option B — upload as Test asset: Package the JAR as a ZIP with the same relative path JMeter expects (lib/com.ibm.mq.allclient.jar) and reference it in your JMX. This requires careful path handling. Confirm with MaxoPerf support that this approach is supported for your account.

The jndi.properties file should be uploaded as a Test asset in either case.

# Taurus YAML wrapper for an MQ load test
execution:
  - executor: jmeter
    concurrency: 50
    ramp-up: 2m
    hold-for: 15m
    scenario: mq-request-reply


scenarios:
  mq-request-reply:
    script: mq-request-reply.jmx

Reading the results

Section titled “Reading the results”

MaxoPerf shows per-sampler metrics for each JMS Point-to-Point sampler:

  • Response time (latency) — for request-reply mode, this is the full round-trip time.
  • Throughput — messages per second across all VUs.
  • Error rate — messages that expired, were rejected, or received an unexpected reply.

Correlate MaxoPerf’s latency numbers with MQ channel statistics from your MQ administrator to distinguish network/channel latency from consumer application processing time.

Do / don’t

Section titled “Do / don’t”

Do:

  • Set a message expiry on all JMS messages during testing — without it, unprocessed messages from a failed test accumulate on the queue indefinitely.
  • Test with persistent delivery if production uses it — persistent messages have higher latency and different throughput characteristics than non-persistent.
  • Monitor queue depth externally (via runmqsc or MQ Explorer) during the MaxoPerf run — queue depth is the leading indicator of consumer saturation.
  • Run reply-queue cleanup between test runs to avoid residual messages from a previous run contaminating reply correlation.

Don’t:

  • Use a shared production queue for testing — use a dedicated test queue. An unexpected message on a production queue can trigger real downstream processing.
  • Forget to configure message expiry — if your JMeter request-reply sampler times out and does not receive a reply, but the message stays on the reply queue, subsequent VUs may pick up stale replies.
  • Set concurrency higher than the MQ channel’s configured maximum connections without first coordinating with your MQ administrator.

Where to go next

Section titled “Where to go next”