Table of Contents

Configuring custom fields

TestRail's custom fields feature allows you to add your own fields to TestRail's user interface. You can use custom fields to customize TestRail and adjust it to your needs. This is especially useful if you need to record and manage information that TestRail has no built-in fields for. This article explains how custom fields work and how to use them.

You can manage custom fields in the administration area under Administration > Customizations in TestRail.

The basics

TestRail currently supports custom fields for two entities, namely for test cases and test results. Custom fields for test cases allow you to add additional details to your test cases. Custom fields for test results can be used to record additional information when test results are entered (for example, on the Add Test Result dialog).

TestRail supports several custom field types. The type of a custom field specifies what kind of information the field can store and how it's rendered. For example, a Text field allows users to enter arbitrary text, whereas a Date field only allows date values as a valid value. The following custom field types are currently supported by TestRail.

Type Sample Value Description
Checkbox Yes / No A checkbox can be used to record boolean values (true/false or yes/no). So if you have a field that has only two possible values, checkboxes are commonly used for that.
Date 2013-06-15 A Date field can be used to record a date value. The edit box for this field includes a handy calendar control to make it easier to pick a date.
Dropdown Option 1
Option 2
Option 3
A Dropdown field can be used to present multiple choices. The user can then select one of the presented values. TestRail stores the selected value internally as a number. That is why you are asked to enter your values as number/option pairs when you configure a Dropdown custom field. You can change the order, add new options or delete options without affecting existing values because of this.
Integer 1022 Integer fields can be used to enter numbers. If a user tries to enter a value that is not a number, a validation error is raised and the user is asked to enter a valid number instead.
Milestone [Release 2.44] The Milestone field is a dropdown box that contains all milestones of the current project as items.
Multi-select Option 1
Option 2
Option 3
A multi-select field can be used to store multiple, predefined values (e.g. a list of tags). Multi-select fields use the same configuration format as Dropdown fields (i.e. number/option pairs).
Steps 1: ...
2: ...
3: ...
The Steps field allows users to enter test case steps in a structured way. This field can be combined with the Step Results field for ticking off individual steps in the test result dialog. This field can only be used with test cases.
Step Results 1: ... [Passed]
2: ... [Untested]
3: ... [Failed]
The Step Results field is the matching type for the Steps field. It enables users to assign a test status to each step of the related test case. This field can only be used with test results.
String "Foobar" The String field is a single-line text box that allows users to enter arbitrary text. This field is similar to the Text field.
Text "Multi-
Line
Text"
A Text field is a multi-line text box that allows users to enter text of arbitrary length. You can specify if a Text field should support Markdown formatting or just plain text.
URL (Link) http://google.com/ The URL (Link) field can be used to store a web address. This can be both a public internet address or the address of a web page in a local intranet.
User [Colin Quinn] The User field is a dropdown box that contains all user names of the TestRail installation.

Properties of a custom field

A custom field has several properties and options that must be considered when you add new fields. The Label and Description properties define how the custom field is displayed in TestRail's user interface. The label is the display name of the field, whereas the description is an optional explanation of what the field does. The description is usually displayed below the field in TestRail.

The System Name is the name TestRail uses internally to represent the field's value. The system name is used as the actual database field name, for XML files and internal data structures. The system name must be unique and cannot be changed after the field was created. The same is true for the field's Type, which cannot be changed either.

All previously mentioned properties apply globally, i.e. for all projects. Once you have defined those properties, you need to assign the field to one or more projects and specify the options.

Project assignments

You assign custom fields to projects by adding entries to the Projects table at the bottom of the form. You can add one or more assignments to a custom field, specifying different options for different projects. This allows you to define varying field options for your projects.

To illustrate this, consider the following example: You want to introduce a test case custom field that allows users to select the Project Area the case is associated with (such as Documentation, User Interface, Setup etc). You design this field as a dropdown and plan to configure all valid project areas for the custom field. As your projects have different project areas you want to specify, you can add multiple project assignments with different options.

TestRail's way of separating custom fields and their project assignments/options is a powerful concept that makes this feature very flexible. If you just want to add a simple custom field that uses the same options for all your projects though, simply add a project assignment that applies to all projects.

Custom fields for test cases

Custom fields for test cases appear on the test case form and can be viewed on test case pages. Depending on the custom field type, custom fields are either placed at the top (for small fields) or at the bottom (for larger fields) of the edit form. You can change the field order (but not the position) on the Customizations overview page in the Administration area.

Custom fields for test results

Custom fields for test results appear in the test result dialog and can be viewed in the history of a test. Depending on the custom field type, custom fields are either placed on the left (for large fields) or on the right (for small fields) of the result dialog. You can change the field order (but not the position) on the Customizations overview page in the Administration area.