Defects: Defect Plugins - TestRail

Defect Plugins

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 it works

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 a bug report has been submitted, 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 integration

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 Dialog

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:

Option Description
label Specifies the display name of the field in the Push Defect dialogue (Required for custom fields)
size Specifies whether the field is displayed as a compact field (compact) or uses the full width of the dialogue (full)
remember Specifies if previously selected values for this field should be remembered and restored the next time the Push Defect dialogue is opened
required Specifies if this field is mandatory or optional and whether users are required to enter a value for this field in the Push Defect dialogue
type Specifies the type of this field; please see section Custom fields below for a list of supported field types (Required for custom fields)

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:

Field Type Description
bool A Yes/No dropdown menu for True/False, Yes/No, or similar binary values.
date A string field which accepts a YYYY-MM-DD or similarly structured date value. Formatting may depend on the integrated tool’s requirements.
datetime A string field which accepts a YYYY-MM-DD HH:MM or similarly structured date and time value. Formatting may depend on the integrated tool’s requirements.
string A small free-text field for up to 250 characters
text A large free-text field without practical size limitations
dropdown A dropdown list that allows users to select one of the multiple options
multiselect Allows users to select multiple, pre-defined options

 

info Note: A custom field always needs to be specified using customfield_<id> or a similar notation. Please see your specific tool’s plugin documentation for custom field definitions, supported field types, and other tool-specific details.

Customizing the Hover 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

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.

Defect from Anywhere

For any project which uses a Defect Plugin and/or Defect URL, users can connect to the integrated external tool using the ‘Defects’ button available on the following TestRail views:

  • The project Overview page
  • The project Milestones pages
  • The project’s Test Runs and Results pages (including from a test run or test plan)
  • The Test Cases page

Push New Defect

This option in the Defects menu is used to open the Push dialog for submitting a new defect to your external tool, without leaving TestRail. This feature requires a Defect Plugin to be configured for your TestRail instance, or the current project. The guide for configuring defect integrations can be found here.

When you successfully submit a new defect to the external tool using this dialog, TestRail will provide you with the new entity ID so you can then enter this ID into the Defects or References fields of any associated TestRail entities.

Add New Defect

This option in the Defects menu is used to open the defect creation screen in your external tool. This feature requires a Defect Add URL to be configured for your TestRail instance, or the current project. The guide for configuring Defect URLs can be found here.

When using the Add New Defect option, TestRail will not automatically capture the ID of the new entity you create. If you would like to add this ID to the Defects or References field of a TestRail entity, you will need to copy the ID from your external tool in order to add it to your TestRail entities.