Jira is an issue and project tracking software from Atlassian. The following article describes how you can integrate Ranorex test cases into Jira. That way you will empower Ranorex to submit or modify testing issues within Jira in an automated way.

As Jira offers a REST web service (API description available here), it becomes possible to submit issues automatically. This is achieved using the JiraRestClient  and RestSharp. Please note that the libraries provided are not part of Ranorex and, therefore, not covered by Ranorex support services. These libraries are wrapped with Ranorex functionality, forming re-usable modules. Starting with Ranorex 7.0, these libraries are, however, already included in the Ranorex Jira NuGet package. The integration of these Jira testing modules into Ranorex test automation is described in the following article.

The following steps need to be performed:

Step 1 – Adding the Libraries to Ranorex for Jira Automation:

A NuGet package with predefined Ranorex modules is available from the “Manage Packages” dialog for Ranorex 7.x and higher. To add the NuGet package to your Ranorex project

  • right-click on “References” in the Ranorex project view,
  • select “Manage Packages…”,
  • search for “Ranorex” and add the “Ranorex Jira Reporter ” package

Add NuGet Package

Predefined modules for Ranorex 6.x (for x86 architecture and .NET 4.0) are available here and modules for Ranorex 5.x (for x86 architecture and .NET 3.5) are available here. The assemblies in this zip-file just need to be added to the Ranorex project. In succession the modules (as shown below) will appear in the module browser under “JiraReporter” (demonstrated in the Ranorex KeePass sample):

AddReference

Step 2 – Using the Modules in the Ranorex Test Suite

Individual modules are available in the “JiraReporter” project. These modules merely need to be used within the Ranorex Test Suite, as shown below:

Modules_TestSuite

The modules are interacting with Jira, based on the results of the related test cases. Except for the initialization module, which should be part of the Ranorex set up region, it is recommended to place the modules in the test case’s teardown.

Available modules for Jira automation:

  • InitializeJiraReporter — This module establishes the connection to the Jira server. It is mandatory for the following modules to be functional.
  • AutoCreateNewIssueIfTestCaseFails — If the test case fails, an issue is automatically created on the server, which is defined in “InitializeJiraReporter”. An issue number is automatically created by the server.
    A compressed Ranorex report is automatically uploaded as well.
  • ReOpenExistingIssueIfTestCaseFails — If the test case fails, an existing and already closed issue gets re-opened.
  • ResolveIssueIfTestCaseSuccessful — If the test case is successful, an existing and already open issue is set to “resolved”.
  • UpdateExistingIssueIfTestCaseFails — If a test case fails, attributes of an existing issue are updated.
  • AutoHandleJiraIntegration — This module combines the modules AutoCreateNewIssueIfTestCaseFail, ReOpenExistingIssueIfTestCaseFails and ResolveIssueIfTestCaseSuccessful.

 

Step 3 – Configure Parameters for the Modules

The modules has different configurable variables. Each module accepts different parameters, but they’re all used in the same way in the modules. Which module accepts which parameters can be seen when using the modules in the Ranorex project.

  • JiraUserName: The username to connect to the Jira server.
  • JiraPassword: The password for the specified user.
  • JiraServerURL: The URL for the Jira server.
  • JiraProjectKey: The project key as specified in Jira (e.g. MYP).
  • JiraIssueType: An issue type, as available in Jira (e.g., Bug)
  • JiraSummary: Some free summary text for the issue.
  • JiraDescription: Some free description text for the issue.
  • JiraLabels: Labels for the issue separated by “;” (e.g., Mobile; USB; Connection)
  • JiraIssueKey: The key for the respective issue (e.g., MYP-25).
  • StateClosed: The state which will be set when an issue will be closed (e.g., Done).
  • StateReopened: The state which will be set when an issue will be reopened (e.g., In Progress).
  • RxAutomationFieldName: The name of the custom field, the test case name will be stored. This field will be taken to identify one or more issues.
  • jqlQueryToConnectIssue: Alternatively to the parameter RxAutomationFieldName, a jql query can be taken to identify one or more issues.

The configuration of the modules is then done with common Ranorex data binding:

DataBinding

… and you’re done:

In succession, Ranorex will automatically interact with Jira when one of the modules is executed. The issues can then be processed in Jira. The following screenshot shows an automatically created issue and its attached report:

JiraPic

 

Advanced usage:

OnDemandCreateNewIssueIfTestCaseFails

This module enables you to create a new Jira issue directly out of the Ranorex report. A new issue will only be created when the link, that is provided within the report, is clicked. So the user or tester can decide whether an issue is create or not.

The compressed Ranorex report will also be automatically uploaded to the newly created issue..

rxReport

Note: This functionality relies on a batch file created by Ranorex in the output folder and the execution of the Jira Command Line interface (CLI). It does not depend on a prior initialization from “InitializeJiraReporter”.

The module exposes the same variables as the modules mentioned above. An additional parameter is essential for this module:

  • JiraCLIFileLocation: The full path to the “jira-cli-<version>.jar” file, provided by the Jira CLI.

Please note that the following requirements need to be met to use this module:

  • Remote API must be enabled in your JIRA installation
  • The mentioned batch file needs to be accessible over the same file path, where the file was initially created. If the file is moved to a new location, the link is not working anymore.
    In this case the batch-file needs to be started manually.

 

JiraReporter Source Code:

The whole project which contains the code for the JiraReporter is available on GitHub under the following link:

https://github.com/ranorex/Ranorex-Jira-Integration

Please feel free to modify the code according to individual needs and/or upload new modules.

 

Troubleshooting:

  • Assembly can’t get loaded
    If an error similar to the following one happens, you have to enable loading from “RemoteSources”.
    Error messsage: Could not load file or assembly ‘file:///C:RanorexJiraOldTestJiraOldTestbinDebugJiraReporter.dll’ or one of its dependencies. Operation is not supported. (Exception from HRESULT: 0x80131515)
    An attempt was made to load an assembly from a network location which would have caused …

    • Add the following lines to the app.conf of the Ranorex project:
      <runtime>
        <loadFromRemoteSources enabled="true" />
      </runtime>

      Jira_AssemblyNotLoaded

    • “Unblock” all .dlls files
      (property of each of them and click “unblock”) — an example how this is done is available here.
  •  Exception — “JIRA returned wrong status
    If you’re encountering an error like
    ‘{“errorMessages”:[], “errors”:{“summary”:”Field ‘summary’ cannot be set. It is not on the appropriate screen, or unknown.”, …}}‘,
    it is very likely that your Jira installation is customized in some way. This message says that the library wants to set a field, which is not available when performing the desired action. Please check your Jira installation as well as the respective action for all necessary and available fields. To overcome this issue, you have to extend and compile the underlying library. A potential starting point for modifications would be the JiraReporter class.

Please note that this blog was originally published November 26, 2014, but has been revised to reflect recent technical developments.

Download free trial