Reference Plugin - TestRail

References: Reference Plugin

TestRail’s Reference Plugin feature is an easy way to link your test cases, runs, plans, and other entities to requirement management, user story, wiki, or document management tools. Once a reference plugin has been configured, you can look up information about linked items directly from TestRail, making it easy to check and follow the status and changes of requirements, issues, etc.

How it works

Reference plugins utilize the “References” field available throughout TestRail. When hovering your mouse pointer over a Reference ID entered into this field, TestRail makes an API request to your connected tool and retrieves information about the linked item. Combined with TestRail’s View and Add URLs, you can quickly view linked requirements or jump to your external tool to retrieve and update information as needed.

Configuring the integration

The reference plugin can be configured globally or on a per-project basis. You can also specify global reference plugin and override it for just a few specific projects. To configure a global plugin, select Administration > Integration > References tab and select a reference plugin. To configure a plugin for a specific project, edit the project, and select the plugin on the References tab.

Each plugin comes with its own set of configuration parameters that must be configured in order to use the plugin. For example, many bug trackers require a login in order to submit API requests, so you usually need to configure a username and password for the connected tool in TestRail. When you select a plugin, all required configuration parameters are displayed in the Connection section.

Displayed fields

When viewing TestRail entities which have the References field (e.g. test cases), you can hover your mouse pointer over any ID in any References field, and TestRail will retrieve information about that item from your integrated tool. This information will be displayed in a pop-up dialog, allowing you to see important information without needing to leave TestRail.

You can configure the [push.fields] section of the plugin to change the fields displayed when hovering over an ID. By default, the plugin supports a list of fields in the [hover.fields] section. You can change the fields which appear in by setting them ‘on’ or ‘off’, and change field properties using a [field.settings.{field name}] section, as described in the Custom Fields section below.

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.


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 like [hover.field.component] to specify additional options for the component field. The following options are supported:


You don’t need to specify all options though. 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 Hover Reference dialogue
size Specifies whether the field is displayed as a compact field (compact value) or uses the full width of the dialogue (full value)


Custom fields

Similar to configuring an existing field, you can add a custom field to the hover dialog (assuming the field is supported). To do this, simply add a line like this to the [hover.fields] section to add a field:


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


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.