Use Rational Integration Tester to test WebSphere MQ test message transactions

An introduction to using the integration testing tool included in IBM Rational Test Workbench

This article covers use of IBM® Rational® Integration Tester to test applications and services that use IBM® WebSphere® MQ software. It also covers the stubbing (virtualization) of these services and applications that use IBM® WebSphere® MQ.


Richa Awasthy (, Staff Software Engineer, IBM

author photoRicha Awasthy is an MCA graduate working with the IBM Asia Pacific Support Team. She joined IBM at the India Software Labs in August 2006 as a developer, working on enhancement of the Rational testing tools. She has worked in C, C++, and Java. Recently, she has been involved in development for Flex application testing. Richa has made contributions and presentations at various workshops or sessions on automated testing, and she wants to make significant contributions in the field of quality engineering in the coming years.

Dulith (Duli) Wijewardene (, Advisory Engineer, IBM

author photoDulith (Duli) S. Wijewardene is an advisory engineer and a member of the North America Rational Testing Tools Support team. With articles such as this, he hopes to ensure that customers are well-informed about new capabilities Rational software. Duli has been part of various diverse teams at IBM. He has been a Testing Team Lead and a Release Manager for IBM Tivoli and, more recently, an Engagement and Deployment Manager in the Cross-Brand Sales and Distribution Group. He is also a certified project manager and has made significant contributions in presenting to quality assurance-related material, including presentations at the Project Management Institute.

26 February 2013

Scope of this article

IBM® Rational® Integration Tester is part of the IBM® Rational® Test Workbench , which combines the capabilities of functional, performance, regression, load, and integration testing automated testing of highly complex applications. This introduction covers only the setup to test message transactions within IBM® WebSphere® MQ. It gives an overview of only one aspect of Rational Integration Tester, and there are more ways that you can use it for integration testing.


You need to have the following software installed on a Microsoft Windows operating system:

  • Rational Integration Tester Version 8.0. To install this, you need to download, IBM Rational Test Workbench Setup and IBM Rational Integration Tester from IBM Passport Advantage (see "Get products" in Resources for a link).
  • IBM WebSphere MQ Version 7.0.

Set up Rational Integration Tester to work with WebSphere MQ

To use IBM WebSphere MQ with Rational Integration Tester, you need to configure the libraries in Rational Integration Tester Library Manager.

Configure the libraries

  1. Select Programs > IBM Rational Integration Tester > Library Manager (set-up).
  2. Select IBM WebSphere MQ in the left pane.
  3. Select an appropriate provider in the right pane.

A red cross for a version in the right pane indicates that the required Java archive (JAR) files are not available for that version.

Figure 1. Library Manager
Configure libraries for specific products

Based on the version of IBM WebSphere MQ, the corresponding libraries (JAR files) should be configured. These JAR files are available where IBM WebSphere MQ server is installed. You might have to copy these files to your local system to configure. In that case, you can copy the files to a directory of your choice, and then click the Browse button to direct Library Manager to that directory.

Create a Queue Manager and Queue

You will be recording MQ messages from a queue, so create a Queue Manager and then a queue within it.

  1. Select Programs > IBM WebSphere MQ > WebSphere MQ Explorer.
Figure 2. IBM WebSphere MQ Explorer
Create required queue under Queue Manager
  1. Right-click Queue Managers to create a new Queue Manager.
  2. Click the default Queue Manager to make it the default manager.

Notice that default queues are created in the default Queue Manager.

  1. To create a new queue, right-click Queues under the Queue Manager in the left pane.
  2. Select New > Queue > Local Queue.
  3. Provide a name for the queue, for example, Test_MQ.
  4. Proceed through the default settings, and then click Finish.

You will see the queue added in the right pane.

Rational Integration Tester can use a concept called proxy queuing to record transactions from live applications. When proxy queues are used, additional queues must be created to match the application queues. For example, Queue1 and the matching proxy queue, either Queue1.GH or Queue1.proxy. Proxy queues can have any extension or prefix but .GH or .proxy extensions are the usual ones.

Prepare for recording

The default WebSphere MQ recording method is Queue Browsing. It does not require any special setup, but it might miss messages in an active queue because it polls. Mirror Queues, Dynamic Mirror Queues, Queue Aliasing, and Proxy Queues are alternative recording methods that require configuration of API exits. The section that follows explains that procedure.

Configure API exits

For recording the entire Queue Manager or individual queues using the Mirror Queue recording mode, Rational Integration Tester requires API exits to be deployed. These exits are included. You need administrative access to the Queue Manager to deploy them. Follow these steps to continue installation:

  1. Install the API exit file.
    1. From the Rational Integration Tester installation directory (usually C:\Program Files\IBM\RationalIntegrationTester\), navigate to the tools\IBM\MQ\7.0 directory, which contains intercepts (the files with .dll extensions). There are 32-bit and 64-bit specific .dll files.
    2. Copy the .dll files to the Exits directory in the WebSphere MQ installation. For example:
      • Windows 32-bit API exit: <IBM WebSphere MQ Installation Directory>\exits\
      • Windows 64-bit API exit: <IBM WebSphere MQ Installation Directory>\exits64\
  2. Configure the Queue Manager to use the exits:
  3. In the IBM WebSphere MQ Explorer, right-click the relevant Queue Manager and select Properties.
  4. In the Properties wizard, select Exits in the left pane to display the Exits configuration in the right pane. The window shows the default location of the exits.
  5. On the Exits page, click the Add button to display the Add API Exit dialog window.
Figure 3. API exit configuration wizard
Values to configure the Queue Manager for exits
  1. In the Edit AP Exit dialog window, add the values to configure the Queue Manager for exits:
    • In the Name field, enter Intercept.
    • In the Function field, enter EntryPoint.
    • For the Module field, click Browse button, navigate to the exits directory within the WebSphere MQ installation directory, and select the appropriate file to enter (usually C:\Program Files\IBM\WebSphere MQ\exits\intercept_windows_x86_7.0.dll).
    • Select the Data check box.
    • In the Data field, type com.greenhat.intercept.
    • Click OK to close the Add API Exit dialog window.
  2. On the Exits page, click Apply.
  3. Click OK to close the Properties wizard.
  4. Restart the Queue Manager from the WebSphere MQ Explorer wizard to deploy the specified API exit file on the selected Queue Manager.

Create a project in Rational Integration Tester

After WebSphere MQ is configured, you can test it.

  1. To create a project in Rational Integration Tester, select Programs > IBM Rational Integration Tester.
  2. Select New Project, and click OK to open the New Project wizard.
Figure 4. Rational Integration Tester New Project wizard
New Project selected
  1. Provide the project name, and click Finish.

The Logical View in the Architecture School Perspective usually opens by default.

Figure 5. Create New Project wizard
RecordMQTest entered as project name

The logical view in the Architecture School perspective shown in Figure 7 usually opens by default.

Set up the recording environment

You need to set up a test environment needs for Rational Integration Tester so that resources can be used according to the requirements of the project.

  1. Create an environment for the test.
    1. In Rational Integration Tester, select Project > Create New Environment.
      Figure 6. Create New Environment wizard
      Provide name for the new environment and click ok
    2. Provide a name for the environment (for example, RITTestEnv), and click OK.
    3. Click OK again in the next window to create the environment.
  2. Add a Queue Manager.
    1. In the logical view of the Architectural School perspective, right-click and select New > IBM > IBM WebSphere MQ Queue Manager.
      Figure 7. Architectural School perspective in Rational Integration Tester
      Drop-down menus show selections described
    2. Provide a name for the Queue Manager, such as RITandMQ, and click OK. The Queue Manager is added in the logical view
      Figure 8. Enter a name for the new Queue Manager
      Field to enter name for Queue Manager
    3. Select the Physical view tab at the bottom of the Architecture School view.
    4. Select IBM > IBM WebSphere MQ Queue Manager.
  3. Create an IBM WebSphere MQ Queue Manager Transport.

A WebSphere MQ Queue Manager transport can be created by creating a physical Queue Manager resource in the Architecture School view of Rational Integration Tester.

Figure 9. Physical View tab within the Architecture School view
Physical view shows the physical resources

Configure transport message settings

Following any one of the previous steps takes you to the wizard shown in Figure 10 to configure the transport message settings so that messages can be recorded, published, or subscribed from a queue within the configured Queue Manager.

Figure 10. Transport Message Settings dialog window
Fields for transport and test connection details
  1. Provide the host name and the name of the Queue Manager, and click the Test Transport button. If the details are correct, the transport test result should be successful.
  2. In the Recording Tab of the transport, define the mode of recording. The physical connection needs to be bound to the logical component. Go back to the Logical View, right-click the Queue Manager that you added, and select Set Binding in > your project > physical Queue Manager name (where words in italic depend on your previous choices).
Figure 11. Binding the physical connection to the logical component
Physical view

You can use Rational Integration Tester to record messages either for an operation or on a transport, so follow the steps under following two sections, based on your requirements.

Set up to record an operation

In the logical view, establish the service components and operations that are associated with the IBM WebSphere MQ. These operations are definitions of your application functions.

  1. Create a service container to hold the operations.
    1. Right-click the logical view of the Architectural School view.
    2. Select New > General > Service.
  2. Create a service operation.
    1. Right-click the logical view of the Architectural School view.
    2. Select New > General > Operation.
Figure 12. Add an operation in the logical view
Drop-down menus to create a service operation
  1. Define your operation and how it interacts with WebSphere MQ queues by double-clicking the operation.

For example, for a Publish operation, you can provide the queue that you must publish to in order to trigger that operation. The other settings are optional in this case.

Figure 13. Publish operation properties configuration
exchange pattern selection screen

WebSphere MQ messaging uses various pairing mechanisms to pair a Publish and Subscribe or a Send and Receive reply pair. This matching and pairing is done with message identifiers in the message header, such as Correlation ID and Message ID. This mechanism of pairing should mimic the similar mechanism used by the application under test.

Queues and Queue Managers defined for operations and stubs would be used when tests, stubs, and so forth are created from the message exchange pattern of the operations. When the recording is used for creating tests and stubs, WebSphere MQ traffic information is used rather these definitions.

  1. In the Recording Studio, click the plus (+) sign to add service operations that can be monitored for WebSphere MQ recording. These operations are the application interfaces that interact with WebSphere MQ, as defined in the logical view of the Architecture School view.
Figure 14. Selecting operation resource for recording
Select a Resource window

Set up to record the whole transport

In WebSphere MQ Version 7 and later, you can record all MQ traffic of the Queue Manager.

After you have created the transport as mentioned in the Set up the recording environment section, go to the Recording Studio, click the + sign to add the transport that can be monitored for WebSphere MQ recording.

Figure 15. Select the resource for recording
Test_Transport selected

Record the messages

In the Recording Studio view, click the round red Start Recording icon to record transactions.

Figure 16. Recording Studio view
Events view

Recorded transactions display in the Event View window.

Figure 17. Recording Studio showing messages (events)
Recording studio shows the events recorded

The recorded events can be exported to be used later by clicking on the Export Event Selected button.

Figure 18. Exporting the recorded events
Recorded events selected

Similarly, test cases, test data, and stubs can be created based on the recorded transactions by clicking the test data and stub creation icons in the toolbar.

Figure 19. Stubs creation from the recorded events
Toolbar icons selected to save the test

The test creation wizard assists in creating these items and allows necessary modifications to be applied to the recorded data. The screen in Figure 20 highlights the wizard where a schema can be applied to the recorded messages.

Figure 20. Modification of the recorded events
Recorded Events window, Operation Assignment view

Run the test

The newly created test looks like the Test Factory view in Figure 21.

Figure 21. Test Factory view
The test factory view shows the newly created test

When you click the green Run icon with the arrow or click F5, the test will execute.

Figure 22. Test execution from the Test Factory View
Run icon selected in the toolbar

You can view the results of a test in the Test Lab view.

Figure 23. Test Lab view
Green progress bar shows 100% completed

Troubleshoot if necessary

If an error message such as the one shown below appears during test execution, make sure that the IBM WebSphere MQ Queue Manager is up and running. Go to Architecture School and Physical view to verify that the settings for physical transport are appropriate and that Test Transport works correctly.

Publish: "MQ Message" on queue "QUEUE1" using schema "MQ Message" via "TestMQ" (2) Fatal Error: Cannot publish as the transport "IBMTest- MQ Queue Manager IBMTest@SQUEUE1.GH@IBMTest." is not available. (Error resolving host "":



Get products and technologies

  • Download Rational Test Workbench, which includes Rational Integration Tester, from Passport Advantage. Registration and sales representative assistance required for access to 30-day free trial.
  • Download a free trial version of Rational software.
  • Evaluate other IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Use Rational Integration Tester to test WebSphere MQ test message transactions