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” |
|
|
| 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. |
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.
Note: Custom case fields of the following types cannot be used to sort/filter Test Cases, nor to add columns in the Test Cases page - "Text", "Steps", "Scenarios".
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.
Note: Custom results fields of the following types cannot be used to sort/filter Test Results or to add columns in the Test Runs & Results page - "Text", "Steps", "Step Results", "Scenarios", "Scenario Results".
Custom test result statuses
In addition to custom test case and test result fields, you can customize test result statuses themselves. This includes the ability to customize the names of individual test statuses, as well as the RGB color used to highlight or represent the status throughout your TestRail project.
To customize the default test result statuses in your instance or add your own statuses, click on the Administration tab, then select Customizations from the right-side menu. From there, click on the Result Statuses menu in tab in the Customizations settings menu. Depending on your screen resolution, you may see the Result Statuses Icon instead of the full words spelled out to denote the correct tab.
By default, TestRail comes with five 'System' fields: Passed, Blocked, Untested, Retest, and Failed. You can edit any of these fields, although you may need to add a new, custom status before changing certain settings (for example, to ensure there is always one result status that is the final status a given test will receive—whatever the final status is). To edit a default status, click the pencil icon on the right side of the status entry in the table.
On the Edit Status page, you can update the Label (displayed to users in the UI) and System Name (unique, lowercase string used to identify the field for actions like export) for the field. You can also update the color used to denote the status across a variety of the application, like labels, charts, and other highlights through the application.
To add your own custom status, click the Edit pencil icon next to one of the result statuses that have the type 'Custom (Inactive)'. In addition to specifying a label, system name, and colors, you can also set whether your new custom status should be considered a 'final' status during testing or not.
Final statuses are used to denote a status that is assumed to be the furthest or most ultimate status that a particular test can receive in a given test run or plan, based on what your team has discovered during testing. Examples of final statuses include Passed, Failed, or Blocked, and all statuses marked as 'final' will be counted in the statistics about your test runs, plans, and milestones. An example of a status that isn't considered a 'final' status is 'Untested', which is a status often used to denote a test that still needs to be executed.
Finally, when you are ready to use to custom test result status, you can check the box next to This status is active to activate the status and begin using the test status in your testing.
You can have at most seven custom statuses, for a total of twelve possible test result statuses.