In ReadyAPI, you can create virtual services that emulate behavior of real JMS clients that act like both subscribers and publishers. For detailed information on how to perform this or that action, see topics of the Testing with Virtual Services section. This section highlights specifics of creating and using JMS virtual clients in ReadyAPI.

Create JMS virtual services

In ReadyAPI, you create an empty JMS virtual service and then add JMS routes to it manually. A JMS route specifies:

the JMS server,
the JMS topic or queue.

Recording of JMS virtual services is not supported.

Configure Connection

To add JMS routes to an existing virtual service, right-click the virtual service in the Navigator panel and select JMS Route.

JMS service virtualization and API testing: Adding a new JMS route to a JMS virtual service manually

Click the image to enlarge it.

Option	Description
JMS Server	Select one of the JMS servers specified in the JMS dialog or select Create New to create a new JMS server.
Receive Destination JNDI Name	The name of the topic or queue that ReadyAPI emulates. Requests to it will be redirected to the virtual service.
Send Destination JNDI Name	The name of the topic or queue ReadyAPI sends the response to. It can also be configured in the response editor.

Connection specifics

Do not use the same topic (queue) for the request and its response. This may cause an infinite loop: after sending the outgoing message to the topic (or queue), the virtual service will recognize it as an incoming request and will process a reply, and the loop can repeat again and again.
Also, remember that in JMS, multiple consumers can subscribe to the same destination. In this case, the destination type – topic or queue – comes into play and specifies how messages are processed:
- A message that comes to a destination of the topic type can be read by all consumers subscribed to this destination.
- A message that comes to a queue destination will be read only by one consumer, the other subscribers will not receive it.
When virtualizing JMS services, it is quite easy to create two or more consumers of the same queue destination. This might cause issues during testing, because your test will not receive answers to some messages. The JMS Request test step can run in an infinite waiting loop and you might think that your test has hung (see the example below). Be aware!

Example
ExampleExample
Imagine you create a JMS Request test step that sends a message to the Topic1 destination and monitors the Queue1 destination for an answer.

Now imagine that you create a JMS virtual service with two virtual operations:
- Operation A listens to Topic1 and replies to Queue1, and
- Operation B listens to Queue1 and replies to Queue2.
So, we have two consumers subscribed to Queue1: the JMS Request test step and Operation B of your virtual service.

Now, if you start your JMS virtual service and run the JMS Request test step, the messages will be processed in the following order:
1. The test step will send a message to the Topic1 destination.
2. The service will receive this message and will reply to Queue1 (according to the Operation A settings).
3. Now the message at Queue1 can be read by Operation B or by the JMS Request test step. Each of them can be faster than the other.
  
  If it is Operation B that captures the message from Queue1, then the test step will not receive the message. It will run in an infinite loop waiting for an answer at Queue1, and you might think your test has hung.
You can configure each response individually to use the ReplyTo value from the incoming request or the destination configured manually. ReadyAPI can send responses to a different queue or a different JMS server. For more information about connection options, see the JMS Response Properties topic.

If necessary, you can use the Start script to dynamically configure JMS connection properties. To do this, you call the ConnectionFactoryProducer() method and provide the required closures. This method should create, configure and return an instance of the ActiveMQConnectionFactory class.The scripts can use the following closures:

Callback Name	Required Parameters	The Callback Returns
`contextProducer`	JmsConnectionConfiguration, Properties	An `InitialContext` that you use to create the JMS connection.
`connectionFactoryProducer`	InitialContext	A `ConnectionFactory` object that you use in your script.
`connectionProducer`	ConnectionFactory	A `JMS Connection` object that you use to create the session.
`sessionProducer`	javax.jms.Connection	A `JMS Session` object that you use in your script.
`destinationProducer`	javax.jms.Session, String	A `Destination` object that specifies the JMS endpoint you send requests to.

Here is a sample script that creates a connection to Apache ActiveMQ Artemis by using the above closures:

Show Example

Hide Example

This example uses libraries of Apache ActiveMQ Artemis. Make sure you have copied the required .jar files to the <ReadyAPI>\bin\ext folder.

Groovy

// Import Java JMS classes
import javax.jms.*
import com.smartbear.servicev.core.model.impl.jms.*
// Import ActiveMQ classes
import org.apache.activemq.ActiveMQConnectionFactory
import org.apache.activemq.artemis.core.protocol.core.impl.ActiveMQSessionContext
import org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory
import org.apache.activemq.artemis.api.jms.ActiveMQJMSClient
import org.apache.activemq.artemis.api.jms.JMSFactoryType
import org.apache.activemq.artemis.jms.client.ActiveMQSession
import org.apache.activemq.artemis.jms.client.ActiveMQJMSProducer
import org.apache.activemq.artemis.jms.client.ActiveMQQueue
import org.apache.activemq.artemis.jms.client.ActiveMQMessage
import org.apache.activemq.artemis.jms.client.ActiveMQConnection
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection
import org.apache.activemq.artemis.api.core.*
import org.apache.activemq.artemis.api.core.client.ServerLocator
import org.apache.activemq.artemis.api.core.client.ClientSessionFactory
import org.apache.activemq.artemis.api.core.client.ClientSession
import org.apache.activemq.artemis.core.remoting.impl.netty.*
import org.apache.activemq.artemis.api.core.TransportConfiguration
import org.apache.activemq.artemis.uri.TCPSchema

def mockService = context.mockService

// Set contextProducer to null
mockService.contextProducer = { configuration, additionalProperties ->
    return null
}

// Create a connection factory and configure its properties
mockService.connectionFactoryProducer = {
    initialContext ->
    HashMap<String, Object> map = new HashMap<String, Object>()
    map.put(org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants.HOST_PROP_NAME, "127.0.0.1") // Set the JMS provider IP
    map.put(org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 61616) // Set the JMS Provider port
    TransportConfiguration tcp = new TransportConfiguration(
            "org.apache.activemq.artemis.core.remoting.impl.netty.NettyConnectorFactory",map) // Create a connection that uses the parameters above
    ActiveMQConnectionFactory mqFactory = (ActiveMQConnectionFactory) ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, tcp) // Create a connection factory
    mqFactory.setClientID("ReadyAPI") // Set the client ID to ReadyAPI
        return mqFactory
}

// Create a connection to the destination
mockService.destinationProducer = { initialContext, destinationName ->
    return ActiveMQJMSClient.createQueue(destinationName)
}

Send requests

To send requests, you can use a JMS publisher application, or you can use the JMS Request test step.

1. Configure the test step

Let’s see how you can do this with the JMS Request test step:

Create a test suite and a test case (or open an existing test case for editing) and click JMS Request on the toolbar. ReadyAPI will ask you to enter the test step name and then will ask what interface type to use for the JMS request being created. This information is needed for selecting the request editor UI. Select any value you want:

Click the image to enlarge it.
Go through the subsequent dialogs that ReadyAPI uses for adding REST or SOAP requests. You can leave default settings in them. For instance, if you selected the REST interface, ReadyAPI will ask you about selecting the REST request. You can choose any value in that dialog.

On the next step, ReadyAPI asks you to specify the endpoint for the request. For JMS virtual services, the endpoint means the JMS server (or JMS session) and topic or queue that the request will use for communication:

JMS service virtualization and API testing: Add JMS Endpoint dialog

Click the image to enlarge it.

Parameter

Description

JMS Server

Specifies the JMS server the test step will use. You can select the JMS server specified in the JMS dialog or create a new one.

Send Destination JNDI Name

The JMS topic or queue, where the JMS Request test step will post a message.

Receive Destination JNDI Name

The JMS topic or queue, where the JMS Request test step will wait for a response to the posted message.

Note:

We recommend using a different queue or topic than that you specified in the “Send Destination JNDI Name” field.

Click OK to create the endpoint.

You will see it in the JMS Request editor:

JMS service virtualization and API testing: JMS Request editor

Click the image to enlarge it.

Note that only the endpoint matters. Other values like the resource path or method type are ignored.

If needed, you can keep the “Send...” or “Receive...” edit box empty to create “send-only” or “receive-only” endpoints. See Setting Endpoints.

Tip: After the test step sends a request, it will wait for a response message to appear in the JMS topic or queue set by the “Receive Destination JNDI Name” parameter. We recommend setting the maximum waiting time in the Timeout property of the JMS Request. This is needed to prevent endless request execution in case when the virtual service does not post a response. The timeout is set in milliseconds.

2. Start the JMS broker

Before sending requests to a JMS virtual service, you need to start the JMS broker on your computer. In this example, we are using ActiveMQ. You can start it from the command line:

<ActiveMQ folder>/bin/activemq.bat start

You can also configure and run ActiveMQ as a service every time the operating system starts. See Running ActiveMQ as a Service or ActiveMQ documentation.

3. Send a JMS request and check the results

Start the virtual service. You can do this for example, by clicking Run on the service editor toolbar. Also, see Running Virtual Services.

If the service found the broker running, and if it detected the needed JMS sessions, topics and queue, the “connection” icons are black, otherwise, they are red:
Run the JMS Request test step or the test case. After the virtual service responds, you will see the response contents in the editor:

Click the image to enlarge it.

Request and response dispatching

When a JMS virtual service receives a request, it starts searching for the matching virtual operation by comparing the JMS session and message destination with the session and destination set in the virtual operation properties. If the operation is found, the service uses dispatch settings to select a response for the reply. If the service has two operations that match the JMS session and destination, it will use the first found operation.

If the service fails to find an operation, it does not return anything. That is why we recommend setting a timeout for the JMS request (see above).

Tip: To simulate absence of responses from your JMS virtual service, select either the Query Match, XPath or the Script dispatch strategy, configure the strategy properties so that they do not return any response name, and select <None> in the Default Response box:

JMS virtual service: Simulating absence of responses

Click the image to enlarge it.

Run JMS virtual services

You can run JMS virtual services both on local and remote machines:

On local computers, you can run them from within ReadyAPI and from the command-line runner.
To run virtual services on remote machines, you need VirtServer there.

For complete information, see Running Virtual Services.

Important: To run a JMS virtual service on remote machines, you need to add the provider’s JAR files to the VirtServer/bin/ext directory. Some providers may require additional configuration:

WebSphere

Work with bytes messages

In the Transaction Log, you can view the contents of JMS bytes messages:

The Default tab shows messages as a stream of bytes. To work with the stream, open the Hex viewer (see below).
The Text tab shows the decoded message:

Click the image to enlarge it.

You select the encoding of the incoming message in the JMS route configuration:

Click the image to enlarge it.

In some specific cases, ReadyAPI may fail to convert bytes to text. In such cases, the Text tab and route assertions will not work.

Hex viewer

To open the editor, click Show hex viewer:

Click the image to enlarge it.

You can configure the editor, using the following options:

Option	Description
View mode	Specifies the view mode of the editor. Possible options: Code — Raw representation of the message. Text — ASCII representation of the message. Dual — Includes both views, with the Code view on the left and the Text view on the right.
Encoding	The encoding is used to view request and response messages.
Code Type	How ReadyAPI should represent the message in the Code view. Hexadecimal Decimal Octal Binary

JMS Virtual Services

Create JMS virtual services

Configure Connection

Connection specifics

Send requests

1. Configure the test step

2. Start the JMS broker

3. Send a JMS request and check the results

Request and response dispatching

Run JMS virtual services

Work with bytes messages

Hex viewer

See Also