Configuring defect integrations

Defect URLs

Defect URLs are an easy and universal way to link TestRail to bug trackers and project management tools. Once the defect URLs have been configured, TestRail allows you to jump to your bug tracker’s New Bug page to enter new bug reports. Entered defect IDs are also automatically linked to your bug tracker to make it easy to track and follow the status of reported issues.

Configuring defect URL integrations

The URL integration with bug trackers and other external issue trackers can be configured globally or on a per-project basis. You can also specify a global bug tracker and override it for just a few specific projects. To configure a global bug tracker, select  Administration  >  Site Settings  >  Integration  and enter the web addresses of your bug tracker.

Defect View URL

This is the web address of your bug tracker to  view  a case. Use  %id%  as the placeholder for the case ID. E.g., if a bug is accessed with the address http://server/view.html?1234, enter http://server/view.html?%id% here.

Defect Add URL

This is the web address of your bug tracker to  add  a case. You can usually just enter the address of your bug tracker’s add form here.

To configure a bug tracker for a specific project, edit the project and enter the web addresses of your bug tracker on the  Integration  tab.

How defect URL integrations work

Once the defect 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 quickly jump to your bug trackers New Bug form to report a new bug. Additionally, entered issue IDs are linked to your bug tracker instance to make it easier to track the status of your issues.

Defect plugins overview

Defect plugins can be used to implement a more sophisticated bug tracker integration in addition to configuring the Defect URLs . Using a defect plugin allows you to directly push bug reports from TestRail to your bug tracker by using the API  or web service of your bug tracking tool. Defect plugins also allow you to look up information about bug reports directly from TestRail, making it easy to check and follow the status and changes of reported issues.

TestRail comes with ready-to-use defect plugins for popular tools and you can build your own plugins for custom tools or not yet supported third-party systems. Please see below for how to configure and use defect plugins.

How defect plugins work

With a Defect Plugin configured, a new Push link is added next to the Defects field in the Add Test Result dialog. This allows you to quickly create a new bug or other item in your external defect tracker without leaving TestRail.

Once you have submitted a bug report, the resulting ID can be added to any Defects field (by the defect plugin or manually). You can also view details about the bug report in TestRail by hovering your mouse cursor over the defect ID on the test page.

Configuring the defect plugin integrations

Defect plugins can be configured globally or on a per-project basis. You can also specify a global defect plugin and override it for just a few specific projects. To configure a global plugin, navigate to  Administration > Integration  and select a defect plugin. To configure a defect plugin for a specific project, edit the project, and select the plugin on the Defects  tab.

Each plugin comes with its own set of configuration parameters that must be defined in order to use the plugin. For example, many bug trackers require a login in order to submit bug reports, so you usually need to configure a username and password for the bug tracker in TestRail. When you select a plugin, all required configuration parameters are displayed in the [connection] section.

Customizing the push defect issue description

Defect Plugins allow you to configure and change the fields displayed in the Push Defect dialog. By default, the plugin already supports a list of fields in the [push.fields] section.

Displayed fields

You can change the fields which appear in the push dialog by setting them ‘on’ or ‘off’. Any fields not listed by default can be defined as a  Custom Field , assuming your tool supports custom fields and the field type is supported.

[push.fields]
summary=on
project=on
issuetype=on
component=on
assignee=on
priority=on
affects_version=on
fix_version=off
estimate=off
labels=off
environment=off
description=on
					

You can enable & disable individual fields and also change the order of fields by adjusting the above configuration.

Field options

In addition to enabling or disabling fields as discussed above, it’s also possible to change additional options per field. To do this, you would define a section for the field, such as [push.field.component] and specify additional options within this section.

[push.field.component]
label=Component
size=compact
remember=false
required=false
type=dropdown

You don’t need to specify all options though, especially for fields which the plugin supports by default. If you just want to change the required option for a field, for example, you can skip the other options. Please see below for an explanation of the various options:

Custom fields

You can also use the above-mentioned approach to add custom fields to TestRail’s Push Defect dialogue. To do this, simply add a line with your custom field to the [push.fields] section to add a field:

[push.fields]
summary=on
...
description=on
customfield_11002=on

Then, add a [field.settings.{custom field identifier}] section. This section is required so the plugin can push and/or retrieve data from your tool. The following is an example custom field configuration for Jira:

[field.settings.customfield_11002]
label=Customer
size=compact
type=dropdown
required=true

The following field types may be supported:

Customizing the hover preview window

When viewing test results, you can hover your mouse pointer over any ID in any  Defects  field, and TestRail will retrieve information about that item from your integrated bug tracker. This information will be displayed in a pop-up dialog, allowing you to see important information without needing to leave TestRail.

Similar to [push.fields] customization, defect plugins allow you to configure and change the fields displayed when hovering over a Defect ID. By default, the plugin supports a list of fields in the [hover.fields] section. You can change the fields which appear in the push dialog by setting them ‘on’ or ‘off’, and change field properties using a [field.settings.{field name}] section, as described in Field Options.

You can also configure custom fields for link hovering. If a field is not listed by default, it will need to be defined as a Custom Field, assuming the field type is supported. If a field is configured for the Push dialog, you do not need to add a second [field.settings.{custom field identifier}] section.

[hover.fields]
summary=on
project=on
issuetype=on
component=on
assignee=on
priority=on
affects_version=on
fix_version=off
estimate=off
labels=off
environment=off
description=on

You can enable & disable individual fields and also change the order of fields by adjusting the above configuration.

Custom fields in the defect hover preview

You can add a custom field to the [hover.fields] section in the same manner as you would add a custom field to the [push.fields] section. A custom field always needs to be specified using customfield_<id> or a similar notation and must have a [field.settings.{custom field identifier}] section. Please see your specific tool’s plugin documentation for custom field definitions, supported field types, and other tool-specific details.