Table of Contents

Defects: User variables

TestRail's defect tracker integration comes with a unique feature that lets you define variables and fields for users to fill out. You can then use the variables as placeholders as part of the defect tracker integration settings.

Why is this useful, you might ask? Imagine you would like to allow your TestRail users to actually use their own defect tracker account to push bug reports (instead of e.g. a generic 'QA' account for all your testers). By using user variables you can enable users to securely enter their defect tracker login name and password in TestRail to easily map users between both systems.

This article explains the general user variable feature and describes the exact steps to set up the user mapping via variables, as this is a popular use case of this feature.

How user variables work

You can add new user variables under Administration > Integration. Once you've defined user variables, users can enter their details for the variables under My Settings (via the My Settings link in the upper right corner of TestRail's user interface).

It is then possible to use the user variables as placeholders in your defect plugin configuration. For example, if you have defined a user variable with the system name of “jira_user”, then you can simply enter %jira_user% in the configuration box to get this replaced by TestRail for each user. See the next section a concrete example on how to benefit from this feature.

Configuring user mapping

By default you usually use a single user account in your defect tracker to push all bug reports from TestRail to your tool, regardless of who pushed the bug report from TestRail. This means that all bug reports are created under the same user in your bug tracker (you would usually set up a generic account like testrail or qa for this). User variables provide an easy way to map users between TestRail and your defect tracking tool and this section explains how to do this.

We first need to define two variables to allow your TestRail users to enter their bug tracker login name and password. For this example we assume we want to integrate TestRail with Jira, but you can just replace this with the name of the tool you use. Follow these steps to set up the user variables:

  1. Select Administration > Integration
  2. Click the Add User Variable link at the bottom of the form
  3. As the Label, enter “Jira User”
  4. As the Description, enter “Your Jira user name”
  5. As the system name, enter “jira_user”
  6. Keep the type of String selected
  7. For the Fallback field we recommend entering a generic “testrail” user you set up in Jira. This is used for all users who haven't entered their Jira login details. If you don't specify the Fallback, TestRail will show a message box asking users to enter their details under My Settings before they can push bug reports
  8. Click OK to save the user variable

Please also create another user variable with the following settings:

  1. Label: Jira Password
  2. Description: Your Jira password
  3. System Name: jira_password
  4. Type: Password
  5. Fallback: the password of the generic “testrail” user you set up in Jira (optionally)

Please make sure to select the Password field type for actual passwords. This ensures that passwords are not displayed in plain text in TestRail's user interface.

Please also make sure to click the Save Settings button on the Integration form. Users can now open their My Settings page and select the Settings tab to enter their Jira login credentials:

Now the last step is to actually use the user variables in your defect plugin configuration. To do this you can just specify the system name in percent characters, like %jira_user%. The defect plugin configuration for our example could look like this:

; Please configure your Jira connection below
[connection]
address=http://jira/
user=%jira_user%
password=%jira_password%

That's it! Users can now enter their defect tracker login details under My Settings and TestRail will use these details to push bug reports.

Tip: If your defect tracking tool uses the email address as the login name, TestRail also comes with two built-in user variables you can use without defining any extra variables for this:
  • %user_email% - The email address of the TestRail user
  • %user_name% - The full name of the TestRail user

Advanced usage

If you are customizing an existing defect plugin or even building your own plugin, then you can also directly access any defined user variables from your code. As the user variables are part of the $context variable, you can simply access user variables like this:

$context['user']->settings['jira_user']

By using user variables in your defect plugin you can implement different behaviors and settings for different users as needed.