Integrating Ranorex Test Cases Into Jira

Jira is an issue and project tracking solution from Atlassian. This article describes how to integrate Ranorex Studio with Jira, so that Ranorex Studio can automatically create or modify testing issues in Jira. This integration works with both a local Jira server as well as cloud instances, and is possible because Jira offers a REST web service (API description available here).

Use Cases

This integration supports the most essential use cases for a Ranorex Studio/Jira integration, as listed below:

• Create an issue when a test case fails
• Re-open an old issue for a repeated failure
• Close an issue when the related test case succeeds

In addition, this integration provides automatic issue handling, so that you aren’t required to manually copy and assign the Jira issue key to the Ranorex Studio test case each time that an issue is created in Jira.

Finally, the whole integration is customizable and works on both Jira server and Jira cloud installations.

Structure of the Integration

So that you have a single point of control, the integration is designed with a central default configuration, where you can specify the starting values necessary for a running integration. These default values can then be modified as necessary throughout the test execution.

In addition to the default configuration, the integration provides a single module that handles the entire integration. Place this module in the teardown section of the test case for which you want to create a Jira issue.

To modify the settings and values in the default configuration, the integration provides a user code library, allowing you to simply use existing user code actions in the action table.

To provide automatic issue handling, the integration uses a Jira custom field that stores information about the test case.

Getting Started

Add the Integration to Your Ranorex Studio Project

A NuGet package with predefined Ranorex Studio modules and user code actions is available from the Ranorex NuGet package manager. To add the NuGet package to your Ranorex Studio project, follow these steps:

1. Right-click on your project in the Ranorex Studio project view
2. Select Manage Packages…
3. Search for Ranorex.Jira and add the Ranorex Jira reporting modules package

In the background, the package manager installs the Jira integration package and all dependency packages (e.g. the Atlassian SDK). You can have a look at them when switching to the Installed tab in the Ranorex NuGet package manager dialog. All necessary resources will be added automatically to your test automation project.

After adding the integration package to your project, there will be a new Jira folder available in the module browser view. This folder contains two modules, one for setting up the configuration and one for automatically handling the whole integration magic.

Note: There will also be a legacy folder in the module browser view which contains the modules from the former community-driven project. If you are using the modules from the former community project, we strongly recommend updating to the new implementation, relying on these two modules and additional user code actions.

Add the Default Configuration to Your Test Suite

To begin, add a setup region to your test suite:

To add the module to the test suite, simply drag and drop the module InitializeDefaultConfiguration from the module browser view to the newly-created setup region.

Open the global parameters tab of the test suite properties by right-clicking the added module and selecting data binding. Click the Auto-create button to create parameters for all module variables, and then click the Auto-bind button to bind the newly created parameters to the variables.

After that, you can start initializing the integration by entering values for the given parameters.

Required variables:

• EnableJiraIntegration: The default value of EnableJiraIntegration is false. Please specify a boolean value (True/False) to enable it. Otherwise, a warning will appear in the report. This parameter is intended to enable the plugin during CI usage and keep it disabled when maintaining or extending the test suite.
• JiraUserName: The username to connect to the Jira server. For a cloud instance, enter the user’s email address.
• JiraPassword: The password for the specified user.
• JiraServerURL: The URL for the Jira server.
• JiraProjectKey: The project key as specified in Jira (e.g. TES).
• JiraIssueType: An issue type, as available in Jira (e.g., Bug).
• StateClosed: The state which will be set when an issue will be closed (e.g., Done).
• StateReopen: The state which will be set when an issue will be reopened (e.g., In Progress).

Special field:

• RxAutomationFieldName This fields enables an automatic issue treatment by Ranorex. When a test fails, Ranorex Studio searches for an existing issue in Jira where the test case name matches the content of this field. If an issue is found, it is reopened. Otherwise, a new issue is created and the test case name is stored in the issue within this field, so that Ranorex can associate the issue with the test case in the future. Important: A custom field with its name matching the value of this variable must be created in Jira manually!

Other variables:

• JiraSummary: Default summary text for the issue.
• JiraDescription: Default description text for the issue.
• JiraLabels: One or more default labels for the issue separated by “;” (e.g., Mobile; USB; Connection).
• jiraIssuePriority: Default value for the issue priority.
• jiraEnvironment: Default value for the environment field.
• jqlQueryToConnectIssues: Default JQL query to find issues.

Enable the Integration for a Ranorex Studio Test Case

After setting up the default configuration, create a test case which adds a Jira issue when it fails. To do so, simply add a teardown region to a test case in your test suite in the same way that you added the setup region previously.

Now add the module AutoHandleJiraIntegration by simply dragging and dropping it from the module browser view to the newly-created teardown region.

Try Out the Integration

When you execute the test suite, nothing will be sent to Jira because the test case does not fail. In order to test the integration, you can intentionally force a test case to fail. To do so, open the underlying recording module and simply add a log message with the report level Failure.

Run the test suite again, and the report will show a failure in the test case where you’ve added the log message. If you now open the teardown region of the test case, you will see a log message reporting that a new Jira issue has been created, followed by a direct link to the newly-created issue.

Following the link, you will find a newly-created unresolved Jira issue with an attached Ranorex Studio report containing the information about the failing test case.

When re-running the test, the integration will add a new issue.

To overcome this, you can use a custom single line filed in Jira. Let’s call it RxAutomation.

Note: A custom field can be created by a Jira administrator.

Simply configure this custom field in the default configuration, as shown in the image below.

After configuring this RxAutomationFieldname, the name of the test case will automatically be applied as an identifier of the issue. So every time that the auto-handle module triggers an update, the integration checks whether there are one or more issues where the text in the field RxAutomation matches the test case name and updates the issue(s) if necessary.

When you repeat test runs, instead of creating an issue for every failing test case, the Jira integration automatically handles the updates on the existing issue(s).

Allow the test case to succeed by changing the log message from failure to success, and the issue will automatically be updated to the status done, since the error no longer occurs.

Since the basic integration relies on just two modules, that’s all that is necessary!

Advanced Usage

The integration package includes a collection of user code actions in a user code library. These user code actions can easily be added to your recording modules.

Begin by adding a new test case: simply copy the existing one and give it the name TestCaseAdvanced.

Create a new recording module and add a user code action by selecting it from the user code library, as shown in the image below.

There are two classes defined by the integration, described below:

The JiraFieldHelper provides functionality to:

• Add or remove values from fields
• Set values in fields
• Set the values custom fields
• Set a specific issue key
• Set JQL queries

The second class, ValueExtractorHelper, provides actions to:

• Update the description of the issue with all steps performed in the raising test case (including screenshots)
• Update the issues summary tag by appending the error message

For example, if you want to add a new label, simply choose the user code action addNewLabeland define the label as an argument of the action.

Make sure that the recording module is placed before the auto-handle Jira integration module in the test suite.

Starting the test run will result in an added label to the newly-created Jira issue linked to the test case TestCaseAdvanced.

If you are not able to add a custom field to your Jira instance, you can also use the setJiraIssueKey action to define the specific issue you want to update. You can even use a JQL query utilizing the action setJiraJQLQuery to define a set of Jira issues which should be updated.

To give even more information about why the test case has failed, you can add the actions updateSummary and updateDescriptionWithAllStepsMade to a recording.

This will extend the summary field of the Jira issue with the error message that forced the test case to fail, and also add the entire report of the test case to the description of the issue, including all screenshots.

Of course, all of these user code actions can also be utilized directly from code, if you prefer the code-based approach.

To learn more about the Jira integration check out the free on-demand webinar “Mastering Jira Integration“, or visit the project page on GitHub.