JMS protocol DSL

JMS support was initially contributed by Jason Koch.


Gatling JMS DSL is not imported by default.

One has to manually add the following imports:

import javax.jms._

import io.gatling.jms.Predef._

JMS Protocol

Use the jms object in order to create a JMS protocol.

  • connectionFactory: mandatory, an instance of ConnectionFactory. Use jmsJndiConnectionFactory_ to obtain one via JNDI lookup or create it by yourself.
  • credentials: optional, to create a JMS connection
  • useNonPersistentDeliveryMode / usePersistentDeliveryMode: optional, default to non persistent
  • matchByMessageId / matchByCorrelationId / messageMatcher: specify how request and response messages should be matched, default to matchByMessageId. Use matchByCorrelationId for ActiveMQ.
  • replyTimeout: optional reply timeout, in milliseconds, default is none
  • listenerThreadCount: optional listener thread count, some JMS implementation (like IBM MQ) need more than on MessageListener to achieve full readout performance

JMS JNDI Connection Factory

Use jmsJndiConnectionFactory object to obtain an instance of JMS ConnectionFactory via JNDI lookup.

  • connectionFactoryName: mandatory
  • url: mandatory
  • contextFactory: mandatory
  • credentials: optional, for performing JNDI lookup
  • property: optional, custom JNDI property

JMS Request API

Use the jms("requestName") method in order to create a JMS request.

Request Type

Currently, requestReply and send (fire and forget) requests are supported.


Define the target destination with queue("queueName") or alternatively with destination(JmsDestination).

Optionally define reply destination with replyQueue("responseQueue") or replyDestination(JmsDestination), otherwise a dynamic queue will be used. If you do so, you have the possibility of not setting the JMSReplyTo header with noJmsReplyTo.

Additionally for reply destination, JMS selector can be defined with selector(Expression[String])

If you have the need to measure the time when a message arrive at a message queue different from the replyDestination(JmsDestination), you can additional define a trackerDestination(JmsDestination).

Message Matching

Request/Reply messages are matched using JMS pattern (request JMSMessageID should be return in response as JMSCorrelationID).

If different logic is required, it can be specified using messageMatcher(JmsMessageMatcher).


  • textMessage(Expression[String])
  • bytesMessage(Expression[Array[Byte]])
  • mapMessage(Expression[Map[String, Any]])
  • objectMessage(Expression[])


One can send additional properties with property(Expression[String], Expression[Any]).

JMS Type

Jms type can be specified with jmsType(Expression[String]).


JMS checks are very basic for now.

There is simpleCheck that accepts just javax.jms.Message => Boolean functions.

There is also xpath check for javax.jms.TextMessage that carries XML content.

And there is bodyString, jsonPath, substring checks for java.jms.TextMessage that carries JSON content and java.jms.BytesMessage that carries json content in UTF-8 encoding. And You may use checkIf for conditional checks.

Additionally you can define your custom check that implements Check[javax.jms.Message]


Short example, assuming FFMQ on localhost, using a reqreply query, to the queue named “jmstestq”:

import javax.jms._

import scala.concurrent.duration._

import io.gatling.core.Predef._
import io.gatling.jms.Predef._

class TestJmsDsl extends Simulation {

  // create a ConnectionFactory for ActiveMQ
  // search the documentation of your JMS broker
  val connectionFactory =
    new org.apache.activemq.ActiveMQConnectionFactory("tcp://localhost:61616")

  // alternatively, you can create a ConnectionFactory from a JNDI lookup
  val jndiBasedConnectionFactory = jmsJndiConnectionFactory
    .credentials("user", "secret")

  val jmsConfig = jms

  val scn = scenario("JMS DSL test").repeat(1) {
    exec(jms("req reply testing").requestReply
      .textMessage("hello from gatling jms dsl")
      .property("test_header", "test_value")


  def checkBodyTextCorrect(m: Message) = {
    // this assumes that the service just does an "uppercase" transform on the text
    m match {
      case tm: TextMessage => tm.getText == "HELLO FROM GATLING JMS DSL"
      case _               => false

Edit this page on GitHub