If you're looking to integrate TestRail with popular project management tools like ClickUp, Monday & Zoho, read the reference URL sections below.
Overview of reference URLs integrations
Reference URLs are an easy and universal way to link TestRail to requirement management, user story, wiki or document management tools. Once the reference URLs have been configured, TestRail allows you to link test cases to external resources and quickly jump from test cases to the linked resources.
Configuring reference URL integrations
The reference integration can be configured globally or on a per-project basis. You can also specify global reference URLs and override them for just a few specific projects. To configure global reference URLs, select Administration > Integration > References tab and enter the web addresses of your tool.
Reference View Url
This is the web address of your external tool to view a reference. Use %id% as the placeholder for the reference ID or article name. E.g., if a reference is accessed with the address http://server/view.html?1234, enter http://server/view.html?%id% here.
Reference Add Url
This is the web address of your external tool to add a reference. Not all tools support this and you might need to add new references from your tool’s user interface instead.
To configure references for a specific project, edit the project and enter the web addresses of your bug tracker on the Integration tab.
Example: bug & issue trackers
To link your test cases to your bug or issue tracker, simply use the example URLs listed in the Defect URLs topic. Once you have configured the address of your issue tracker, TestRail automatically links all issue IDs that you enter into the References field.
Example: Wiki software
You can also use the References field to link test cases to specifications and other documents in your Wiki software. For example, if the web address of your Wiki articles typically look like this:
http://server/wiki/My_articleThen enter the Reference View Url like this:
http://server/wiki/%id%
You can then enter My_article in the References field of test cases to link to your Wiki pages. To enter multiple references, separate them with commas.
Overview of reference plugin integrations
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 reference plugins work
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 reference plugin integrations
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 reference plugin 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.
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.
[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.
Hover 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:
[hover.field.component] label=Component size=compact remember=false required=false type=dropdown
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 in reference hover previews
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:
[hover.fields] customfield_11002=on
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:
[hover.field.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 |
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.