To quickly get started with the TestRail-Jira integration, we recommend using our integration wizard from TestRail’s Administration area under Admin > Integration.
You can find more information on how to set up the integration for each Jira configuration in the links below:
Alternatively, you can configure the integration without the setup wizard. This article explains how to integrate TestRail with Jira manually (both Jira Server and Jira Cloud).
There are currently four mechanisms to integrate TestRail with Jira:
- Using defect URLs to link test results to Jira
- Using the defect plugin to create new Jira issues and view issue details directly in TestRail
- Using reference URLs to link test cases to Jira
- Using the reference plugin to view linked issues details directly in TestRail
You don’t have to use all listed integration options and you can mix and match the integration with other tools. Configuring the integration usually only takes a few minutes and this guide explains how to configure the integration and how it works.
TestRail allows you to specify a global Jira instance for all projects, as well as one Jira instance per project. You can override the integration parameters for each project under Admin > Projects.
Defect URLs
Defect URLs are used to let TestRail know how to access your Jira instance.
To configure Jira’s URLs for Defects fields, select Admin > Integration > Defects.
You can reference the following example URLs to configure the addresses for your Jira instance:
Jira Cloud
| URL Integration Type | URL |
|---|---|
| Defect View Url | https://<yoursubdomain>.atlassian.net/browse/%id% |
| Defect Add Url | https://<yoursubdomain>.atlassian.net/secure/CreateIssue!default.jspa |
Jira Server or Data Center
| URL Integration Type | URL |
|---|---|
| Defect View Url | http://<your.server.address>/jira/browse/%id% |
| Defect Add Url | http://<your.server.address>/jira/secure/CreateIssue!default.jspa |
Once the URLs have been configured, a new Add link appears next to the Defects field in the Add Test Result dialog. This link allows you to jump to Jira’s Create Issue form to report a new bug.
Additionally, entered issue IDs are automatically linked to your Jira instance to make it easier to track the status of your issues.
Reference URLs
The reference URLs are used to link test cases to issues stored in Jira via the References field. Once the URLs have been configured, issue IDs entered in the References field are linked to your Jira instance to make it easier to jump to related issues, feature specifications or requirements.
To configure Jira’s URLs for the References field, select Admin > Integration > References.
You can reference the following example URLs to configure the addresses for your Jira instance:
Jira Cloud
| URL Integration Type | URL |
|---|---|
| Reference View URL | https://<yoursubdomain>.atlassian.net/browse/%id% |
| Reference Add URL | https://<yoursubdomain>.atlassian.net/secure/CreateIssue!default.jspa |
Jira Server or Data Center
| URL Integration Type | URL |
|---|---|
| Reference View URL | http://<your.server.address>/jira/browse/%id% |
| Reference Add URL | http://<your.server.address>/jira/secure/CreateIssue!default.jspa |
Once the URLs have been configured, you can add your user story issue IDs to your test cases and they will be turned into links that allow you to navigate straight to Jira.
Defect plugins
Defect plugins can be used to implement a deeper bug tracker integration and TestRail comes with ready-to-use Jira defect plugins. The Jira integration plugins have been split out into two separate plugins to handle cloud and server Jira integrations separately. As of 29th April 2019, Atlassian deprecated user password functionality in their cloud version of Jira so as to align with European GDPR regulations.
For TestRail, this means that cloud and server Jira integration need to be treated somewhat differently. In a nutshell:
- For Jira Server or Data Center integrations, you should use the Jira REST plugin (Jira Server 5.x, 6.x, 7.x, 8.x, and later), and authenticate the integration using your Jira username and password combination.
- For Jira cloud integration, you should use the Jira Cloud plugin, and authenticate the integration using your Jira email address and Jira API token.
To configure the defect plugin, select Admin > Integration and select the relevant Jira defect plugin in the Defect Plugin dropdown list. The next step is to configure all the necessary connection settings in the Configuration field. Project-specific plugins and configuration settings can optionally be specified under Admin > Projects.
When the defect plugin has been configured, a new Push link is shown next to the Defects field in the Add Test Result dialog. Clicking the link will open a popup dialog that enables you to push a bug report to Jira without leaving TestRail.
Once the test result is added, hovering the mouse cursor over an issue ID will open a window with useful information and status details about the issue in Jira.
Reference plugins
Reference plugins can be used to retrieve additional information from IDs entered into the References field of TestRail entities, such as test cases, test runs, and milestones. The Reference Plugin is configured on the References tab of the integration settings in the same manner the Defect Plugin is configured.
The plugin supports hovering over Reference IDs and editing the Jira issues directly in TestRail. It is also possible to customize the fields which appear via link hovering and add custom fields, as described above.
If you have the Defect Plugin already configured for Jira, you can simply copy your [connection] and [hover.fields] sections from the Defect Plugin into the Reference plugin configuration. Alternatively, you can choose different fields to be displayed for References and Defects.
Attachments
The Jira Defect Plugin supports submitting attachments when you create new issue and push them to Jira. This field can be turned on and off, but cannot be customized further. To submit one or more attachments to Jira, simply drag the attachment to the attachments or description areas of the push dialog or click on the area to choose an attachment from your file system after clicking Push on a test result dialogue or Defects dropdown menu.
Additional Customizations
TestRail Server also supports custom defect plugins. If your team uses TestRail Server, it is possible to further customize the defect plugin (or build your own) to support additional field types or other data. Please see our documentation on custom defect plugins here for additional information.