Test the IBM Rational Quality Manager REST API with the Rational Performance Tester Extension for SOA Quality

Interact with RQM's REST API using RPT SOA's Generic Service Client, Test Editor, and Test Log

IBM® Rational® Quality Manager provides a Representational State Transfer (REST) API based on the IBM Rational Jazz™ REST Services. You can access the API through a Jazz form-based authentication mechanism that IBM Rational Performance Tester does not supported as originally configured. This article contains the best practices for handling this authentication mechanism when you test the performance of a Rational Quality Manager server with Rational Performance Tester Extension for SOA Quality.

Nicolas Constans (nconstans@fr.ibm.com), Software Quality Engineer, Software Test Specialist, IBM

Nicolas is a software quality engineer at IBM Rational in France. He is currently working on IBM Rational Test RealTime, Rational Performance Tester, Rational Service Tester for SOA Quality and Rational Quality Manager, in the System Verification Team. He has experience in functional, integration, and performance testing of graphical interfaces and application programming interfaces.



04 May 2010

Also available in Chinese

Introduction

IBM® Rational® Quality Manager is a test management and quality management tool to manage quality-assurance team projects. It is built on the IBM Rational Jazz™ platform and inherits its Representational State Transfer (REST) capabilities and the Rational Jazz form-based authentication mechanism. Load testing a Rational Quality Manager server through the REST API is best done using IBM Rational Performance Tester Extension for SOA Quality. However, testing this way can be difficult for these reasons:

  • The SOA quality extension does not provide built-in support for the Jazz authentication mechanism.
  • Recording a Rational Quality Manager session with the HTTP Proxy recorder of the SOA quality extension generates complex test scenarios, which are difficult to understand and to handle.

The best practice described in this article consists of using the generic service client to interact with the RESTful Web services that Rational Quality Manager provides and to generate uncomplicated, convenient test scenarios.

This document was written using IBM Rational Quality Manager 2.0.0.1 iFix003 Standard Edition and IBM Rational Performance Tester extension for SOA Quality 8.1.1.


The Jazz authentication mechanism and the service under test

To build a simple load test for Rational Quality Manager you must authenticate with the Rational Quality Manager Server. Rational Quality Manager uses the Jazz form-based user authentication scheme.

This scheme is described at https://jazz.net/wiki/bin/view/Main/JFSCoreSecurity#User_Authentication. The way to authenticate on a IBM Rational Jazz Team Server is described at https://jazz.net/wiki/bin/view/Main/WritingAJazzClient.

In short, the client must authenticate to obtain a session ID from the server, and then use this ID as a cookie in all subsequent requests to the server. You can obtain the session ID by using the generic service client.

The Rational Quality Manager service that you interact with here deals with managing test cases. Rational Quality Manager publishes the XML representation of most its artifacts, including test cases, through an Atom feed whose URL is similar to this address:

https://rqmserver:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/testcase where rqmserver is the name of your Rational Quality Manager server or IP address.

For subsequent steps, you need to have the URL of the test case that the Atom feed publishes.

Figure 1. A Rational Quality Manager test-case feed
Two test cases displayed by the feed

The following artifacts can be queried using various REST commands:

  • Use GET to obtain XML representations.
  • Use POST to create artifacts.
  • Use PUT to modify artifacts.
  • Use DELETE to delete artifacts.

Use the generic service client to authenticate with the Rational Quality Manager server

To authenticate with the Rational Quality Manager server:

  1. In the Performance perspective, open the generic service client by using the ad-hoc toolbar button:
Figure 2. Opening the generic service client
The generic service client toolbar button

The Services page displays a library of Web Services Description Language (WSDL) files, endpoint requests, and a history of all requests. The Transport page manages the underlying transport configurations. In this case, the transport configurations are based on HTTPS.

Figure 3. The generic service client Services page
The client page displays requests and history
  1. Query an XML representation of a test case:
  1. Click Add EndPoint request, and enter the GET method and the URL of the test case as published by the Atom feed:
Figure 4. Creating an endpoint request
The URL and Method fields in the request wizard

Note:
The default HTTP does not cover HTTPS, so a specific HTTPS configuration must be created for this request.

  1. Click New, enter a name, and select Keep Alive and SSL certificate:
Figure 5. Creating a protocol configuration
The HTTP configuration options
  1. Click Open SSL Editor, and then click Rename.
  2. Rename the SSL configuration:
Figure 6. Renaming the SSL configuration
The new name for the SSL configuration
  1. Click OK three times, click Next, and then click Finish to create the request.

The request is displayed in right pane of the generic service client:

Figure 7. The request displayed in the generic service client
The generic service client request contents
  1. Click Invoke to call the request and display the server response. The request and the response are stored in the request history:

With the Request History box, users can quickly retrieve the requests that they sent and the corresponding responses.

Figure 8. The Request History box
The Request History shows requests and responses

In this instance, the response message from the server is empty, but the Response Properties page contains information:

Figure 9. Response properties
The Response Properties page contains cookies

The session ID that was mentioned earlier (here as a JSESSIONID cookie) is of particular interest. The URL that redirects to the queried test case (as the Location property) also contains important information. Moreover, the x-com-ibm-team-repository-web-auth-msg response header that is set to authrequired indicates that you must follow the Jazz authentication scheme.

Tip:
The property names and values can be selected and copied, which facilitates creating requests using the established values.

To conform to the authentication scheme, you need to call another GET action on the redirection URL, sending the session ID as a cookie, and using the same HTTPS configuration

Figure 10. The endpoint request using the JSESSIONID session ID
The request includes JSESSIONID session ID cookie
  1. Call the action in the generic service client, and review the properties of the response:
Figure 11. A response that requires authentication
The HTTP header requires authentication

The response properties contain the X-com-ibm-team-repository-web-auth-msg HTTP header set to authrequired and do not contain a redirect Location. The Jazz authentication mechanism specifies that the next step is to authenticate after making the required preparations.

  1. Use the POST action to issue the user credentials (both the user name and password are "admin") to this address: https://rqmserver:9443/jazz/ authenticated/j_security_check?j_username=admin&j_password=admin

The server also requires the Path=jazz cookie statement. The User Authentication Jazz scheme requires the application/x-www-form-urlencoded content-type header.

The authentication request looks like this screen capture:

Figure 12. The authentication request
The request posts the user credentials
  1. Invoke the request and see that the response properties no longer contain the x-com-ibm-team-repository-web-auth-msg header.
Figure 13. Authentication is granted
The response no longer asks for authentication

The Location property redirects you to the same URL as before the authentication.


Use the request history to complete the authentication

You can take advantage of the generic service client Request History box to retrieve the second request. Use that request as a basis for a new one to save time:

  1. In the Request History box, select the second request that you made:
Figure 14. Retrieving a request from Request History
The second request is selected

The request is displayed in the right pane of the generic service client and can be invoked as-is.

  1. Click Invoke and see the Location property in the response: It contains a URL that does not redirect you. In fact, the URL is the original address that you used in the initial GET action.
Figure 15. A URL that does not redirect
The Location property URL does not redirect

You can retrieve the first request in the Request History box, and add the JSESSIONID cookie to make it work:

Figure 16. The first request with the JSESSIONID cookie added
The GET request includes the JSESSIONID cookie

After you invoke the GET request again, the response contains a message that is the XML description of the Rational Quality Manager test case. This screen capture shows the XML description in the Form view:

Figure 17. The Form view of the test case XML description
Test case contents are displayed in Form view

The Tree view displays the XML elements as a hierarchical tree, and the Source view displays XML code:

Figure 18. The Source view of the test case XML description
Test case contents as XML in Source view

Generate and review the service test

The previous sequence of requests can be converted into a service test script:

  1. Select all the requests in the Request History box, and click Generate Test Suite:
Figure 19. Generating a service test from the Request History
The New Test wizard for generating a test suite
  1. Click New Project to create a container project, rename the service test as getTestCase, and click Finish. The service test contains all the requests and their responses:
Figure 20. Requests and responses in the test
The generated test includes requests and responses

The HTTPS configuration that is used in the generic service client has been retrieved and stored in the test.

Figure 21. The HTTP configuration in the test
The HTTP configuration in the Propertes box

All the requests use the HTTP configuation:

Figure 22. The HTTP configuration is used by a request
A Request using the RQM-HTTPS configuration

Automatic data correlation makes the test runnable

Automatic data correlation is a powerful feature of Rational Performance Tester. With this feature, you can run the service test immediately as-is, regardless of the complexities of the scenario in the generic service client.

In the test editor, click View > Display Data Correlation. The first substituter shows that the test generator detected the use of the JSESSIONID cookie by the requests that follow the first response. The substituter created a reference to the cookie in the response, and substituted its value all in subsequent requests by this reference.

Figure 23. Data correlation in the test
A data substitution using the JSESSIONID cookie

Larger view of Figure 23.

With data correlation, when the test is run, the JSESSIONID cookie that the server returns is used by the requests, even though its value is not the one stored in the service test.


Verification points

Before running the test, you can use a verification point to check the status of the last GET request.

To create a verification point:

  1. Click View > Display all Test Contents, and select the last response.
  2. Click Add > Equal Verification Point.

At run time, this test element compares the XML message that the server returns and the XML message that is stored in the test. Additional comparison options are also available:

Figure 24. Setting up an equal verification point
A verification point for the contents of TestCase1

Custom Java code

This verification point itself is sufficient to check the status of the test case retrieval. However, you can verify additional aspects of the system under tests by using another Rational Performance Tester feature: custom Java™ code.

For example, you can check for the HTTP status code of a response. For this procedure, use the last response and review the properties.

To add custom Java code to the test:

  1. Open the Response Properties page:
Figure 25. Response properties in the test
Response properties in the test

The status code is 200, which means "OK." In the remaining steps, you create a reference to this value, and use it as the argument of a Java custom code statement. At run time, this code checks whether the actual status equals 200, and logs a pass or fail event accordingly.

  1. Click the 200 value to give value focus.
  2. Right-click the value, and select Create Reference.
  3. When the Edit Reference Name dialog box prompts you, accept the default name, and click OK.
Figure 26. Create a reference to the HTTP status code
The reference-creation dialog box

The reference is created and the editor highlights the value in blue:

Figure 27. The test editor highlights the reference
The reference value is a shaded background
  1. To add the custom code to the test, select the root node of the test, and click Add > Custom Code:
Figure 28. Adding custom code to the test
Click the root node and add custom code to a test

The custom code element is linked to a Java class in the project.

  1. Change the default class name so that it has meaning: test.CheckHTTPStatus:
Figure 29. Changing the custom code name
In Test Element Details rename the custom code
  1. Click View Code to generate the class and open it in an editor. The behavior of the class at run time is defined by the exec method, which is unspecified:
public String exec(ITestExecutionServices tes, String[] args) {
    return null;
}
  1. Change the contents as follows:
Listing 1. Specifying the exec method
public String exec(ITestExecutionServices tes, String[] args) {

    if (args[0].equals("200")) {
tes.getTestLogManager().reportVerdict("Status code is 
correct",VerdictEvent.VERDICT_PASS,VerdictEvent.REASON_SEE_DESCRI
PTION);
    }
    else {
        tes.getTestLogManager().reportVerdict("Status code is not 
correct",VerdictEvent.VERDICT_FAIL,VerdictEvent.REASON_SEE_DESCRIP
TION);
    }
    return null;
}
  1. Add the Java import statement, which is required to recognize the VerdictEvent class:
import org.eclipse.hyades.test.common.event.VerdictEvent;

This code checks the value of the custom code argument. The value must be defined.

  1. Open the test editor, and click Add next to the Arguments field of the custom code. The Select Arguments dialog box opens, in which you can choose a data source as an argument.
  2. Expand the last GET entry, and select the Cookie: 200 reference; then click Select.
Figure 30. Adding an argument to Custom Code
A reference is used as a custom-code argument

The reference is added to the custom code arguments list:

Figure 31. The argument is added to custom code
The custom code argument list
  1. Save the test, and click Run in the test editor.

Analyze the results of the test run

During the test run, the Service Test report is automatically opened and updated in real time. However, only the built-in equal verification point is part of this report. To get a more precise view of the test-run events, right-click the run result in the Performance Test Runs view, and select Display Test Log:

Figure 32. Displaying the Test Log report
The menu for displaying a test log

The Test Log report provides advanced information about all test events. To open the log, click the test log Events tab, and expand Events tree:

Figure 33. Test log events
The log lists test-run events

The equal verification point is part of the event list. The log also includes pass event that the custom code logs. Selecting the pass event displays the text string that that was set in the Java custom code for the "pass" verdict:

Figure 34. The Custom code status text string
The custom code status text string in the Test Log

When reviewing the Test Log report, the Service Content page is updated accordingly. For example, it displays the XML message received from the last server response:

Figure 35. The Service Content page
The test-case XML code on the Service Content page

The Service Content page also displays the expected and actual XML content of the verification point:

Figure 36. A verification point on the Service Content page
The returned data and verification-point content

Finally, the Test Log report shows that subsequent requests used the JSESSIONID cookie that was received from the server:

Figure 37. The JSESSIONID cookie that the server provided
The JSESSIONID cookie that the RQM server sent
Figure 38. The JSESSIONID cookie used by a request
The JSESSIONID cookie is used by later requests

Customizing the service test to issue various REST requests

To issue other requests to the Rational Quality Manager server, we could use the generic service client again, and authenticate with the server. However, a quicker method consists of reusing the service test, which already contains the necessary authentication steps, as a foundation.

  1. In the Test Navigator, right-click the test, select Copy.
  2. Paste the test into the project.
  3. Right-click the copy, select Rename, and name it createTestCase.
  4. To create a test case, you must use the POST action to send the full XML representation of the test case to the server.
    1. In the test, click the Transport tab, and change Method to POST instead of GET in each instance. XML Test Case instead of an empty message is sent to the server.
    2. Change the URL to target the test case service: https://rqmserver:9443/jazz/ service/com.ibm.rqm.integration.service.IIntegrationService/testcase)
Figure 39. Change the method of the requests
Select POST from the Method list
  1. To access the XML representation of the test case:
    1. Select the last response to populate the Service Content page.
    2. Select all its contents and copy the selected text:
Figure 40. Copying XML test data from the Service Content page
The Copy push button in the Service Content toolbar

Larger view of Figure 40.

  1. Paste the content into the Source view of the message of the last request:
Figure 41. Pasting XML data into a request message
Message contents of the last request after pasting

You paste the content into the last request because the XML message will not have been processed before the user authenticates, so the content is meaningless before the actual POST request is issued on the correct URL.

Furthermore, the URL must be changed in the first request. Following redirections from the server can be handled by the use of references.

To change the URL in the first request:

  1. Click the Transport tab for the first request.
  2. Make the URL field editable: Right-click the field, and select Remove Substitution.
  3. Change the URL to https://rqmserver:9443/jazz/service/ com.ibm.rqm.integration.service.IIntegrationService/testcase:
Figure 42. Changing the URL
The Transport page of URL in the first request

In answer to this request, the server response Location header contains the redirection URL.

  1. Select the redirection URL in the test editor, right-click the selection, and create a reference:
Figure 43. Creating a reference with the redirection URL
The menu that opens when you right-click Location
  1. Name the reference URL1.
  2. Repeat these steps to create two additional references to the Location value of the third and fourth server responses, and name the responses URL2 and URL3:
Figure 44. Creating a reference with the second redirection URL
The Test Editor Edit Reference Name window
  1. To make the requests follow these redirections, replace their respective URLs with these references:
    1. Select the whole text field of the second-request URL, right-click, and then click Substitute > Select Data Source.
    2. Select the URL reference, and click Select:
Figure 45. Selecting a data source reference
The URL1 reference is selected as data source
  1. Repeat the step 7 to substitute the URLs of the fourth request by the URL2 reference, and the fifth request by URL3.
  2. Remove the equal verification point from the last response, because it is no longer relevant.
  3. Modify the custom code so that it checks for this status: 201 – Created HTTP:
if (args[0].equals("201")) {
    tes.getTestLogManager().reportVerdict("Status code is correct",
VerdictEvent.VERDICT_PASS,VerdictEvent.REASON_SEE_DESCRIPTION);
}
  1. Change the name of the test case in the last POST request to a new value:
Figure 46. Renaming the new test case
The test-case name in the POST request form view
  1. Save the test.
  2. Run the test. The server Atom feed displays the created test case:
Figure 47. The updated test case feed
The Atom feed displays the new test case

Conclusion

A request to the Rational Quality Manager REST API can be called with the generic service client. Furthermore, a service test that contains this request can be generated, modified, and run.

In a similar fashion, REST requests using other commands (most prominently PUT and DELETE) can be created and called easily by Rational Performance Tester with the convenient features of the generic service client and the test editor.

As a matter of fact, all the requests of a test can use the same JSESSIONID provided that the duration of the test does not exceed the Rational Quality Manager session timeout. You need to authenticate according to process described in this article only once per service test, which greatly simplifies the elaboration and maintenance of test scenarios.

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=486521
ArticleTitle=Test the IBM Rational Quality Manager REST API with the Rational Performance Tester Extension for SOA Quality
publish-date=05042010