JMS

Introduction

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.

Message matching

Traffic Parrot can form mappings in a number of ways.

• Time: pair messages in the order they happened in time
• Correlation ID: pair messages with matching correlation id

The default is to use time based matching. This can be changed in the advanced parameter section of the record page.

Recording and replaying JMS Queues using an internal broker

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.

Recording JMS Queues using an internal broker

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.

Replaying JMS Queue messages using an internal broker

To replay the recorded mappings we will use the internal broker and connect the system under test to it.

Recording and replaying JMS Queues using an external broker

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.

Recording JMS Queues using an external broker

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.

Replaying JMS Queues using an external broker

To replay the recorded mappings we will need the same virtual service queues in place as shown on the image below.

Recording and replaying JMS Topics using an internal broker

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

Recoding JMS topics using an internal broker

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

Replaying JMS Topics using an internal broker

When replaying to an internal broker Traffic Parrot will subscribe to the request topic and publish to the response topic as shown in the diagram Replaying topic messages using an internal broker.

Recording and replaying JMS Topics using an external 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).

Recoding JMS topics using an external broker

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

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.

Replaying JMS Topics using an external broker

When replaying to an external broker Traffic Parrot will subscribe to the request topic and publish to the response topic as shown in the diagram Replaying topic messages using an external broker.

Go to JMS in the top navigation bar and then click Export. Click the button to download a ZIP file that contains all of the JMS mappings and data files.

The ZIP file contains the following directories:

• mappings/ — JMS stub mappings in JSON format
• data/ — data directory files

Go to JMS in the top navigation bar and then click Import. Select a ZIP file that was previously exported and it will be uploaded and the mappings and data files will be restored.

AsyncAPI is an open specification for describing event-driven and message-based APIs — its channels, operations and message schemas — in the same way that OpenAPI describes HTTP APIs. If your team already documents its messaging APIs with AsyncAPI, you can create JMS mappings directly from that document instead of writing them by hand.

Go to JMS in the top navigation bar and then click Import AsyncAPI. Upload a JSON or YAML AsyncAPI 2.x or 3.0 document and Traffic Parrot generates one JMS mapping per importable channel operation, each serving an example payload generated from the operation's message schema.

After you upload the document, Traffic Parrot shows a preview of the mappings it would create so you can review and select exactly which ones to import.

The preview table lists one row per importable operation, with the following columns:

• Destination — the channel name the operation maps to
• Type — QUEUE or TOPIC, taken from the channel's jms or ibmmq binding
• Operation — the AsyncAPI operation id (for example publishOrderCreated)
• Reply destination — for an AsyncAPI 3.0 request-reply operation (one that carries a reply object), the reply channel the response is published to; blank for a one-way operation
• Example payload — the example message generated from the operation's message schema
• Status — a green New badge for an operation that does not match an existing mapping

Each row has a checkbox. Use the header checkbox to select or deselect all rows at once, or toggle individual rows. The Import Selected button shows the count of selected rows. Click it to create JMS mappings only for the checked operations, or click Cancel to discard the preview and return to the file selector.

If the document is malformed, is not a supported AsyncAPI version, or contains no importable operations, the page reports a clear error and no mappings are created.

Each selected operation becomes a JMS mapping whose request matches any message on the channel destination and whose response is the example payload generated from the message schema. You can then open the mapping in the JMS editor to refine the request matchers, response body, properties or delay just like any other JMS mapping.

For an AsyncAPI 3.0 operation that carries a reply object, Traffic Parrot creates a request-reply mapping instead: it still receives the request on the operation's own channel, but it publishes the response on the reply channel's destination (shown in the Reply destination column of the preview), and the response is the example payload generated from the reply message's schema. A one-way operation continues to echo its example back on the same channel as before.

The same import flow is also available for native IBM® MQ — see Import an AsyncAPI specification on the native IBM® MQ page.

Supported scope

Traffic Parrot supports both AsyncAPI 2.x and AsyncAPI 3.0 documents with the JMS and IBM® MQ channel bindings. For a 3.0 document, the destination is taken from the channel's address (falling back to the channel name). The destination type is taken from the channel binding: it is a TOPIC when either the jms or the ibmmq binding declares destinationType: topic (case-insensitive); otherwise it defaults to a QUEUE (so a document with no binding, or one whose destinationType is absent, empty or unrecognised, imports as a queue). Both one-way publish/subscribe operations (send and receive) and request-reply operations (those that carry a reply object) are imported — a request-reply operation publishes the reply message's example on the reply channel's destination.

Other channel bindings (AMQP, Kafka, MQTT) and AsyncAPI 4.x are not yet supported. Message payload schemas use JSON Schema (draft-07 for 2.x, draft 2020-12 for 3.0); Traffic Parrot generates an example from common schema constructs, and renders a placeholder payload for advanced constructs it cannot yet turn into an example (for example $defs with internal $ref, patternProperties, prefixItems, const, if/then/else and additionalProperties). You can edit any generated payload in the editor afterwards.

Messaging skeletons offer a quick way to pre-fill a JMS mapping form from an operation declared in an imported AsyncAPI specification, in the same way the HTTP skeletons and gRPC skeletons dropdowns pre-fill their forms. Where Import AsyncAPI creates mappings for many operations at once, the skeletons dropdown is for hand-crafting a single mapping that starts from a declared operation.

On the JMS Add/Edit page, pick an operation from the skeletons dropdown above the form. The form's destination name, destination type (the Queue / Topic radio) and request body/payload pre-fill from the selected operation. You can then edit any field before saving, just like a mapping you wrote by hand.

To edit the list of operations on the skeletons dropdown, place AsyncAPI specifications (JSON or YAML, AsyncAPI 2.x or 3.0) into the trafficparrot-x.y.z/asyncapi configuration directory — the same directory the messaging coverage check reads. Each declared operation becomes an entry in the dropdown.

Alternatively, you can use the import button beside the dropdown to upload an AsyncAPI specification directly. If you import a file with the same name as a file that was previously imported, it will be overwritten.

For a request-reply operation the dropdown option is labelled <operationId> (request-reply), and selecting it pre-fills both the request side (destination name, type and request body) and the reply side (a cloned response row carrying the reply destination name and reply body). This works for AsyncAPI 3.0-native reply operations and for AsyncAPI 2.x operations paired by a shared correlation id.

The headless trafficparrot validate command also checks your messaging mappings against your imported AsyncAPI specifications, so you can run it as a step in a continuous integration pipeline. AsyncAPI is the messaging contract, exactly as OpenAPI is the contract for HTTP and proto files are for gRPC. The same command also validates HTTP mappings against OpenAPI specifications and gRPC mappings against proto files; for the shared usage, exit codes, and CI-pipeline details see the full validate CLI reference.

The command enumerates the operations declared in your imported AsyncAPI specifications and reports any declared operation that has no backing messaging mapping — whether JMS, native IBM® MQ or file-message. This means a partially-mocked messaging API cannot silently drift from its contract. The AsyncAPI specifications are read from <files-root>/asyncapi/ (the messaging analogue of the HTTP openapi/ and gRPC proto/ directories; JSON or YAML, AsyncAPI 2.x or 3.0; all files in the directory are aggregated before the check runs). For example, a specification declaring an operation on the orders queue with no mapping that backs it reports:

Some AsyncAPI operations have no backing messaging mapping (under-coverage): (1)
No mapping covers AsyncAPI operation: QUEUE:orders

A declared operation is matched to a mapping by its destination identity — the destination name and type written as TYPE:name, where TYPE is QUEUE or TOPIC (for example QUEUE:orders or TOPIC:events). The same identity is used in the report and in the allowlist below. A TOPIC mapping never covers a QUEUE operation of the same name, and the reverse.

For a request-reply operation, coverage is measured on the inbound (request) destination only — the reply destination is the mock's output, not a coverage target.

If there are no AsyncAPI specifications (no declared operations), the messaging under-coverage check contributes nothing and passes silently.

If your virtual service intentionally mocks only part of a messaging API, you can mark the remaining destinations as deliberately unmocked so that they do not fail the under-coverage check. Create a file named messaging-coverage.properties in the files-root directory (alongside the mappings and the asyncapi/ directory) and list the excluded destinations in the exclude.destinations property:

exclude.destinations=QUEUE:orders, TOPIC:events

Each entry is a TYPE:name destination token, where TYPE is QUEUE or TOPIC, written exactly as it appears in the report. Entries are separated by commas. If the file is absent, no destinations are excluded.

To stop the allowlist from quietly going stale, an exclude.destinations entry for a destination that is not present in any AsyncAPI specification is itself reported as drift and causes a non-zero exit code, with the message Allowlist excludes a destination not present in the AsyncAPI specification: <entry>. Remove or correct an entry once the destination it refers to no longer appears in the specifications.

Messaging drift participates in the same report and the same exit codes as the HTTP and gRPC checks — a declared operation with no backing mapping fails the build (exit code 1) the same way a renamed or removed HTTP endpoint does. Run the command as a pipeline step and check its exit status, exactly as described in Using it in a CI pipeline in the validate CLI reference.

Pact is a consumer-driven contract format. As well as the HTTP interactions you can import as HTTP stubs, a Pact contract can describe asynchronous message interactions — the messages a provider publishes for a consumer to handle. If your team captures its messaging contracts as Pact files, you can create JMS mappings directly from them instead of writing them by hand.

Go to JMS in the top navigation bar and then click Import message Pact. Upload a Pact .json file and Traffic Parrot generates one JMS mapping per message interaction in the contract, each publishing the message's example payload.

Two contract shapes are accepted. A Pact specification v3 contract carries its messages in a top-level messages[] array. A specification v4 contract carries them as interactions[] entries whose type is Asynchronous/Messages. Both are detected automatically. An HTTP-only Pact contract (one with no message interactions) is rejected with a message pointing you to the HTTP Pact import instead.

After you upload the file, Traffic Parrot shows a preview of the mappings it would create so you can review and select exactly which ones to import.

The preview table lists one row per message interaction, with the following columns:

• Destination — the queue or topic the message is published to, derived from the contract
• Type — QUEUE or TOPIC (see how the destination is derived)
• Operation — the message's description from the contract, used as the operation id
• Reply destination — always blank for a message Pact, because message interactions are one-way (there is no reply)
• Example payload — the message's example contents from the contract, which is what the mapping will publish
• Status — a green New badge for a message whose derived destination does not match an existing mapping, or a Duplicate badge when it does

Each row has a checkbox. New rows are checked by default and duplicate rows are left unchecked. Use the header checkbox to select or deselect all rows at once, or toggle individual rows. The Import Selected button shows the count of selected rows. Click it to create JMS mappings only for the checked messages, or click Cancel to discard the preview and return to the file selector.

If the file cannot be parsed as JSON, or contains no message interactions, the page reports a clear error and no mappings are created.

A Pact message interaction describes what a provider publishes, but not the queue or topic it is published to — a message contract carries no transport binding. Traffic Parrot therefore derives a destination for each message:

• From the message metadata, when present. If the message's metadata object has a destination, queue or topic key, its value is used as the destination (the keys are checked in that order). A topic key makes the destination a TOPIC; otherwise the destination is a QUEUE.
• From the message description otherwise. When the metadata has none of those keys, the destination is generated from the message's description — lower-cased, with each run of non-alphanumeric characters replaced by a dot (so Order Created event becomes order.created.event). A description-derived destination is always a QUEUE.

Review a derived destination before importing. When a destination is derived from the description rather than taken from explicit metadata, the preview shows a warning banner above the table listing each affected message, because the generated name is a best guess and may not match the queue or topic your system under test actually uses. Confirm the contract carries the right metadata, or correct the destination on the imported mapping in the JMS editor afterwards, so the mapping listens on the destination you expect.

Each selected message becomes a one-way publish JMS mapping. It matches any message on the derived destination and, on receipt, publishes the message's example contents back on that same destination. You can then open the mapping in the JMS editor to refine the request matchers, response body, properties or delay just like any other JMS mapping.

Message Pact imports are one-way only. A Pact message interaction is a fire-and-forget message a provider publishes — the contract has no request that selects it and no reply. The imported mapping therefore just publishes the example payload; it is not a request-matching, request-reply stub. (Request-reply mappings are created only by an AsyncAPI operation that carries a reply object.)

A worked example

Given this minimal Pact specification v3 contract with a single message in its messages[] array, where the destination is taken from the message metadata:

{
  "consumer": { "name": "OrderConsumer" },
  "provider": { "name": "OrderProvider" },
  "messages": [
    {
      "description": "an Order Created event",
      "metadata": { "queue": "orders.created" },
      "contents": { "orderId": "1001", "status": "CREATED" }
    }
  ]
}

importing it on the JMS page creates a one-way mapping that listens on the orders.created QUEUE and publishes {"orderId":"1001","status":"CREATED"} on receipt of any message there. Importing the same contract on the IBM® MQ page instead creates the equivalent native IBM® MQ mapping.

Had the message carried no metadata destination key, the destination would have been derived from the description as an.order.created.event and the preview would have shown a warning to review it before importing.

The same import flow is also available for native IBM® MQ — see Import a message Pact contract on the native IBM® MQ page.

Supported scope and licensing

Import message Pact is part of the JMS support and is available on a JMS licence, the same as the rest of the JMS functionality; the menu link does not appear without it. Pact specification v3 (messages[]) and v4 (Asynchronous/Messages interactions) message contracts are supported. For a v4 contract the example body is read from the message's contents.content envelope. The example contents is imported as-is — you can edit any imported payload in the editor afterwards.

Introduction

Response delay

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.

Supported brokers

• ActiveMQ 5.4+ when schedulerSupport is enabled
• IBM®MQ 8+

Response properties

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

RabbitMQ Content Type

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.

Text messages

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.

Supported features

• Edit the response body
• Use parts of the request body in the response body by extracting from the request
• Use helpers in the response body
• Programmatically transform the response using JMS response transformers
• Match requests using the request body matchers (e.g. JsonPath, contains, regexp)
• Use priority to set up a preference order for matching mappings

Bytes messages

Traffic Parrot is able to record and replay a javax.jms.BytesMessage that could contain bytes in any format.

Supported features

• Edit Base64 representation of the response body
• Edit Base64 representation of the request body to match
• Match requests using byte equality only
• Use priority to set up a preference order for matching mappings

Printable character messages

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.

Supported features

• Edit plain text representation of the response body
• Edit plain text representation of the request body to match
• Use parts of the request body in the response body by extracting from the request
• Use helpers in the response body
• Match requests using any of the request body matchers (e.g. contains, regexp)
• Use priority to set up a preference order for matching mappings

Java object messages

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.

Supported features

• Edit objects without requiring additional JAR files or agents
• Edit response object values
• Edit response object structure (e.g. delete fields, add items to list, add nested fields)
• Use helpers in the response body
• Use parts of the request object in the response object by extracting with JsonPath
• Match request objects using the request body matchers (e.g. JsonPath, contains, regexp) on the JSON representation of the object
• Use priority to set up a preference order for matching mappings

Dynamic object serialization

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.

Standard object serialization

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.

Notes for testers

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.

Notes for developers

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 JSON

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:

• declareArguments (used e.g. for RabbitMQ queue declaration arguments)
• skipDeclare (used e.g. to skip RabbitMQ queue declaration and assume a queue already exists)

Example JMS 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"
}

Sending JMS messages from other protocols

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:

• TEXT - text message
• proto/example.ProtoType - proto message of given type (using provided proto files)
• protoBase64Bytes/example.ProtoType - proto message with Base64 encoded bytes