For a basic introduction with examples have a look at Mocking and simulating JMS IBM® WebSphere MQ Tutorial.
A tester uses a web browser to access the console. The console manages the virtual service. The system under test (application under test) connects directly to the virtual service on different ports.
Here is an example of how that could look like for a scenario where the virtual service is replaying messages to an external queue.
Virtual service replaying JMS messages to and from a queueTo record from or replay to JMS brokers you will need to tell Traffic Parrot how to connect to them.
Those connections are displayed in the dropdown menus on the record and replay panels, for example:
The "Internal broker" connection is available in the dropdown by default when you choose to use an internal broker in the Broker panel.
To define a new connection that will be available in the dropdown in the record and replay panels:[
{
"connectionId": "1",
"connectionName": "Test Payments Broker",
"connectionData": {
"jmsProvider": "IBM_MQ_7_5",
"hostname": "mqserver.example.com",
"port": 1415,
"queueManager": "PAYMENT.QM",
"channel": "PAYMENT.SVRCONN",
"username": "payuser",
"password": "paypassword222",
"useMQCSPAuthenticationMode": false,
"copyRequestMessageIdToResponseMessageId": false
}
},
{
"connectionId": "2",
"connectionName": "TrafficParrot External Payment Broker",
"connectionData": {
"jmsProvider": "IBM_MQ_7_5",
"hostname": "mqserver.example.com",
"port": 1414,
"queueManager": "TRAFFICPARROT.DEV.AWS.QM",
"channel": "TP.PUBLIC.JUNIT",
"username": "tpuser",
"password": "tppass333",
"useMQCSPAuthenticationMode": false,
"copyRequestMessageIdToResponseMessageId": false
}
},
{
"connectionId": "3",
"connectionName": "Test Order System Broker",
"connectionData": {
"jmsProvider": "ACTIVE_MQ",
"hostname": "localhost",
"port": 61616
}
},
{
"connectionId": "4",
"connectionName": "Azure AMQP",
"connectionData": {
"jmsProvider": "AZURE_AMQP_1_0",
"hostname": "namespace.servicebus.windows.net",
"sharedAccessKeyName": "SendListen",
"sharedAccessKey": "password"
}
},
{
"connectionId": "5",
"connectionName": "Local RabbitMQ",
"connectionData": {
"jmsProvider": "RABBIT_MQ_3",
"hostname": "localhost",
"virtualHost": "/",
"username": "guest",
"password": "guest",
"port": 5672,
"amqpCompatibilityMode": true,
"declareArguments" : {
"x-max-length": 10000,
"x-message-ttl": 60000
}
}
},
{
"connectionId": "6",
"connectionName": "Local ActiveMQ AMQP",
"connectionData": {
"jmsProvider": "ACTIVE_MQ",
"hostname": "localhost",
"port": 61617,
"protocol": "amqp"
}
}
]
In the current Traffic Parrot version you edit JMS connections directly in the jms-connections.json file. In near future you will be able to do it via the Web UI as well.
trafficparrot.virtualservice.jmsConnectionsUrl=classpath:jms-connections.jsonto for example
trafficparrot.virtualservice.jmsConnectionsUrl=file:/home/john/git/project/trafficparrot-jms-connections.jsonThis can be useful if you would like to version control it with your application source code.
To connect to IBM® MQ you need jar files provided by IBM that will allow Traffic Parrot to establish connections with MQ.
Before you proceed please read these instructions to double check your actions are inline with the supported way to install WebSphere MQ Java jar files.
If you have any issues with obtaining the jar files please contact us.
Copy those files to trafficparrot-x.y.z/lib/external and restart Traffic Parrot.
As with HTTP recording Traffic Parrot, during recording incoming and outgoing messages are matched up to provide mappings. Then upon playback receipt of a matching incoming message will trigger generation of an outgoing message.
Traffic Parrot can form mappings in a number of ways.
The default is to use time based matching. This can be changed in the advanced parameter section of the record page.
The method which requires least configuration is to use Traffic Parrot's internal broker. Via this method you can record traffic to and from your application by just modifying the broker URL to which your application connects.
This diagram shows how two production systems connect:
One system generates messages onto a queue; another system consumes these messages and puts responses onto a second queue, which the first system consumes. If our goal is to test the system-under-test in isolation, we must record these interactions in order to replay them.
As you can see in the diagram, the recording simply introduces two extra queues, to which the system under test connects, as shown in the diagram below:
As the system-under-test generates messages they are listed in the bottom table 'Current recording session'. As the second system generates responses to these messages, they are also listed at the bottom, but in addition mappings are generated in the 'Mappings' table showing incoming and outgoing messages that Traffic Parrot has paired up.
In this scenario we don't want to use Traffic Parrot's internal broker - we want Traffic Parrot to work with an existing external broker. This scenario is useful mainly when you would like to work with brokers that are unsupported internally by Traffic Parrot, for example IBM® MQ.
Instead of pointing the system under test at a different broker, we will create extra queues on our existing broker that will be used by the virtual service. Then we will reconfigure the system-under-test to connect to these queues instead of the original ones. Traffic Parrot will move messages between these queues and the original queues, recording and creating mappings as it does so.
To replay the recorded mappings we will need the same virtual service queues in place as shown on the image below.
You can use Traffic Parrot's internal broker to record and replay topic messages. For the purpose fo the examples below, we will use a configuration where the production systems connect in a way described on the diagram below:
The system-under-test generates messages onto a topic which are received by a number of other systems. One of these systems generates responses onto a different topic (which are received by a number of systems, one of which is the system-under-test).
We will configure Traffic Parrot to connect to the request and response topics and record the messages appearing on both, generating mappings as it goes, as shown on diagram Recording topics using an internal broker
Recording and playback of topics using an external broker is less intrusive than queues or internal broker topics, because Traffic Parrot can subscribe to a topic just like any other application and receive messages, without affecting the delivery of those messages to other applications.
This diagram shows how the production systems connect:
The system-under-test generates messages onto a topic which are received by a number of other systems. One of these systems generates responses onto a different topic (which are received by a number of systems, one of which is the system-under-test).
We will configure Traffic Parrot to connect to the request and response topics and record the messages appearing on both, generating mappings as it goes, as shown on diagram Recording topics using an external broker
will allow you to edit an existing mapping:
Traffic Parrot supports postponing the delivery of a JMS message. This can be useful to better simulate a more realistic scenario where the responding system does not send a response message immediately after receiving the request message.
Use the 
field on the edit mapping panel to specify the delay in milliseconds.
Sometimes, the response headers or properties of a message are crucial to the system under test. They can be specified line by line using the following format:
StringPropertyName;java.lang.String;StringValue IntegerPropertyName;java.lang.Integer;111
For RabbitMQ, the content type can be specified for example as:
ContentType;java.lang.String;application/x-java-serialized-object
The request priority can be set in order to set up a preference order for matching mappings.
The highest priority value is 1. If two or more mappings both match a request, the mapping with the higher priority will be used to provide the response. The default priority is 5.
This can be useful, if you want a "catch-all" mapping that returns a general response for most requests and specific mappings on top that return more specific responses.
Traffic Parrot is able to record and replay a javax.jms.TextMessage which could contain text in a variety of formats e.g. JSON, XML or plain text.
Traffic Parrot is able to record and replay a javax.jms.BytesMessage that could contain bytes in any format.
If the bytes of a javax.jms.BytesMessage are found to contain at least 95% printable characters (e.g. letters, digits, special characters), it will be displayed in plain text in the user interface.
This is configurable using the trafficparrot.mostly.printable.characters.threshold=0.95 property.
Non printable bytes will typically be displayed by the browser as a small box, as you can see in the screenshot below.
If the bytes of a javax.jms.BytesMessage are found to contain a single java.io.Serializable object that Traffic Parrot is able to deserialize, it will be displayed as a JSON object in the user interface.
The request and response body can be edited as if they were a JSON body. You are free to change the JSON as you wish, so long as the edits are compatible with the underlying Java class that the JSON represents.
By default, Traffic Parrot will use dynamic object serialization to support objects of any class that it is able to understand, including objects that are not on the classpath.
Unlike other tools, we do not require additional JAR files or agents to be installed in order to record, edit and replay object messages.
To improve compatibility (and support special handling during the serialization), you can choose to use standard Java object serialization by adding your classes to the Traffic Parrot classpath.
See the notes for developers for instructions on how to do this.
If you are having trouble with this functionality, please ask the developers on your team to review the notes for developers below.
Please contact us if you require any additional help for your particular configuration.
In order to deserialize a serialized Java object using standard Java object serialization, the Java class of that object and the classes of all of its fields must be on the Traffic Parrot classpath. Copy the JAR files containing those classes to trafficparrot-x.y.z/lib/external and restart Traffic Parrot.
In order to represent the object as JSON and allow editing, the class must have a public zero argument constructor.
Please contact us if you require any additional help for your particular configuration.
JMS mapping configuration is stored in the jms-mappings directory as text files in JSON format. You may directly edit these files on the filesystem and store them in a VCS such as Git or SVN.
Some JMS mapping features are not currently supported in the UI and can only be edited directly in the mapping JSON:{
"mappingId" : "1bf95fd0-5647-4db0-bae6-729a8b29fd1f",
"request" : {
"destination" : {
"name" : "request-queue",
"type" : "QUEUE",
"declareArguments" : {
"x-queue-mode" : "lazy",
"x-dead-letter-exchange" : "dead-letter-exchange",
"x-dead-letter-routing-key" : "dead-letter-routing-key",
"x-max-length" : 100,
"x-message-ttl" : 60000
},
"skipDeclare" : false
},
"bodyMatcher" : {
"equalTo" : "any"
},
"bodyType" : "TEXT",
"jmsMessageType" : "javax.jms.TextMessage"
},
"response" : {
"destination" : {
"name" : "response-queue",
"type" : "QUEUE",
"declareArguments" : {
"x-dead-letter-exchange" : "dead-letter-exchange",
"x-dead-letter-routing-key" : "dead-letter-routing-key",
"x-max-length" : 100,
"x-message-ttl" : 60000
},
"skipDeclare" : false
},
"jmsResponseTransformerClassName" : "NO_TRANSFORMER",
"text" : "anything",
"bodyType" : "TEXT",
"jmsMessageType" : "javax.jms.TextMessage",
"properties" : [ ],
"fixedDelayMilliseconds" : 0
},
"mappingName" : "saved-mapping-1bf95fd0-5647-4db0-bae6-729a8b29fd1f.json"
}
JMS text messages can be sent after an HTTP or gRPC response, configured in the mapping JSON:
"postServeActions" : [ {
"name" : "send-jms-message",
"parameters" : {
"jmsConnectionId" : "(connection id from jms-connections.json)",
"destination" : {
"name" : "queue-name",
"type" : "QUEUE"
},
"variables" : {
"id" : "{{randomValue length=24 type='ALPHANUMERIC'}}"
},
"properties" : {
"id" : "{{variables.id}}"
},
"bodyType" : "TEXT",
"jsonBody" : {
"id" : "{{variables.id}}",
"fieldFromRequest" : "{{originalRequest.jsonBody.requestField}}",
"fieldFromResponse" : "{{originalResponse.jsonBody.responseField}}"
},
"delayDistribution" : {
"type" : "fixed",
"milliseconds" : 500
}
}
} ]
Supported bodyType settings:
When Traffic Parrot receives a request message, it will try to simulate the system it is replacing by sending back a response message on the response queue or topic. To decide which response message to send, it will go through all the request to response mappings it has available to find the response to be sent. For more details how request matching works, see Request matching.
There are several matchers available to match JMS request messages, depending on the attribute.
The type of message can be considered for matching.
The type of the message body can be considered for matching.
| Type name | Type Id | Description |
|---|---|---|
| Text | TEXT | Matches message text directly |
| Printable Characters | PRINTABLE_CHARACTERS | Matches message bytes represented in mapping as text using UTF-8 printable character encoding |
| Base64 Bytes | BYTES | Matches raw bytes represented in mapping using Base64 encoding |
| Proto Bytes | proto/com.example.RequestType | Matches Proto message bytes represented in mapping as JSON text |
| Java Serialized Proto Bytes | javaProto/com.example.RequestType | Matches Java object Serializable Proto message bytes represented in mapping as JSON text |
| Java Serialized Bytes | com.example.RequestType | Matches Java object Serializable message bytes represented in mapping as JSON text |
The most common matchers are shown below. All other WireMock 3 request body patterns are also supported.
| Matcher name | Matcher Id | Description |
|---|---|---|
| any | any | Any request body will match. |
| equal to | equalTo | Check that the received request message body is equal to the request body specified in the mapping |
| contains | contains | Check that the received request message body contains the sequence of characters specified in the mapping |
| does not contain | doesNotContain | Check that the received request body does not contain the sequence of characters specified in the mapping |
| matches regex | matches | Check that the received request message body matches the regexp specified in the mapping |
| does not match regexp | doesNotMatch | Check that the received request message body does not match the regexp specified in the mapping |
| equal to JSON | equalToJson | Check that the received request message body is JSON and that it is equal to the request body JSON specified in the mapping |
| matches JSON | matchesJson |
Check that the received request message body matches (allowing for special wildcard tokens) JSON specified in the mapping.
Tokens allowed:
For example a "matches JSON" request body matcher:
{
"name": "{{ anyValue }}",
"lastName": "{{ anyValue }}",
"age": "{{ anyNumber }}",
"children": "{{ anyElements }}"
}
will match a request body:
{
"name": "Bob",
"lastName": "Smith",
"age": 37,
"children": [{"name": "sam"}, {"name": "mary"}]
}
|
| matches JSONPath | matchesJsonPath | Check that the received request message body is JSON and that it matches JSONPath
specified in the mapping. For example, if we use the following expression as the request body matcher
$[?(@.xyz.size() == 2)]it will match this request body: {"xyz":[{"a":true}, {"b":false}]}
but will NOT match this one:
{"xyz":["a":true, "b":false, "c":true]}
For more examples see the request matching documentation.
|
| equal to XML | equalToXml | Check that the received request message body is XML and that it is equal to the request body XML specified in the mapping |
| matches XML | matchesXml |
Check that the received request message body matches (allowing for special wildcard tokens) XML specified in the mapping.
Tokens allowed:
For example a matches XML request body matcher:
<example>
<name>{{ anyValue }}</name>
<age>{{ anyNumber }}</age>
<children><tp:AnyElements/></children>
</example>
will match a request body:
<example> <name>Sam</name> <age>29</age> <children><child name="bob"/></children> </example> |
| matches XPath | matchesXPath | Check that the received request message body is XML and that it matches XPath
specified in the mapping. For example, if we use the following expression as the request body matcher
/xyz[count(abc) = 2]it will match this request body: <xyz><abc/><abc/></xyz>but will NOT match this one: <xyz><abc/></xyz> |