Xray provides a set of custom fields that can be used for some issue types as detailed in Custom Fields and Screen Configuration.

Besides this, you can add your own custom fields to any Xray issue type: Tests, Pre-Conditions, Test Sets, Test Executions, Test Plans.

Currently, you can't add custom fields to Test Runs since they're not JIRA issues.

Xray provided custom fields

As mentioned in Custom Fields and Screen Configuration, whenever you install Xray it will also add some custom fields that are available only for some issue types. Bellow, please find a more detailed explanation of some of the most important ones.

Begin Date

The start date for the Test Execution or Test Plan.

Conditions

The Pre-Condition conditions.

Cucumber Scenario

The Cucumber Scenario clauses in Gherkin.

Cucumber Test Type

The Cucumber Scenario Type (i.e. Scenario or Scenario Outline).

End Date

The end date for the Test Execution or Test Plan.

Test Repository Path

The Test Repository Path for the test

Generic Test Definition

The definition of a generic Test (e.g. full classname of some automated test, name of some script, goals of exploratory testing).

Manual Test Steps

The manual steps fields, in JSON format

Manual Test Steps (Export)

The manual steps fields for exporting manual tests

Pre-Condition Type

Choose the Pre-Condition Type. It must match the Test Type to which this Pre-Condition is associated.

Pre-Condition association with a Test

The Pre-Condition(s) issue(s) associated with this Test.

Requirement Status

Whenever we're speaking about status associated with a requirement, we may in fact be talking about different things:

• workflow status associated to the requirement issue (e.g. "New", "In Progress", "Closed")
• (coverage) status for some version, taking into account executions made for that version of the Tests that do validate the requirement
• "Requirement Status" custom field, the one that we will detail next

The "Requirement Status" custom field is a calculated field, usable in the context of requirement issues, that calculates the requirement coverage for a specific version. The version that it calculates the coverage for depends on the behavior for that field defined in a global configuration (see configuration details here).

As an example, you may prefer to always calculate this based on the latest test run(s), independently in which version it/they was/were executed... or you may prefer to calculate it for the earliest version yet to be released (i.e. the next version). In the later case, it takes into account the order of the versions within the project settings page.  

Have in mind that a requirement  is assigned to and implemented in some version. However the requirement will still live after that version, at least for some time. Therefore, when someone mentions a "status of  a requirement", you have to ask "In which version?". The status of the requirement is thus dependant on the executions you make for the associated Tests in some version of the system, which may by different from the version in which the requirement was initialy implemented in.

In the following example, the first image shows the calculated value for the status of requirement for the next to be released version (i.e. v3.0), while the second image shows the calculated values for all the unreleased versions. This behaviour was changed in Custom Fields Preferences, in Xray settings, in this case from "Earliest unreleased version" to "Unreleased Versions".

 

This field is searchable, so you can make statistics with it or use in gadgets. However, if you wish to search for requirements in some status we recommend using the requirements() JQL function instead (more info here). You can also add it to your cards of your Agile boards, to have real-time feedback of its status shared across your team members.

  

Revision

The system revision (or code revision) being tested in the context of a given Test Execution. It is an open field that can contain the Git commit hash or the SVN revision, for example. Some users use it to put the build number/identifier.

Steps Count

Number of Steps in a Manual Test.

Test Type

The Test type (e.g. Manual, Cucumber, Generic).

TestRunStatus

Whenever we're speaking about status associated with a Test, we may in fact be talking about different things:

• workflow status associated to the Test issue (e.g. "New", "In Progress", "Closed")
• (coverage) status for some version, taking into account the runs made for that Test in some version of the system
• "TestRunStatus" custom field, the one that we will detail next

The "TestRunStatus" custom field is a calculated field, usable in the context of Test issues, that calculates the "status" (not the workflow status) of the Test for a specific version, having in mind executions (i.e. test runs) for that version. The version that it calculates the status for depends on the behaviour for that field defined in a global configuration (see configuration details here).

The calculated value for the field also depends on Test Environments, if they're being used, as mentioned here. As an example, you may prefer to always show the latest test run result independently in which version it was executed... or you may prefer to show the status of the latest run executed on the earliest version yet to be released (i.e. the next version). In the later case, it takes into account the order of the versions within the project settings page.  

Although a Test in Xray is essentialy a test case template, thus not related with any execution whatsoever, you can add this field to the Test view screen as a way to have a glance of the current status of it for some version right from the screen of the "test template" (i.e. Test).

      

This field is searchable, so you can make statistics with it or use in gadgets. If you wish to search based on, please see the proper syntax here.

Tests Count

Number of Tests within a Test Set or a Test Plan issue.

Tests association with a Test Set 

Associated Tests with the Test Set.

Tests association with a Test Execution 

Associated Tests with the Test Execution.

Test Environments

The Test Environment(s) associated to a given Test Execution. This is an open field, similar to a label; you should try to reuse existing Test Environments. It may be empty (default).

Test Execution Defects

Shows the number of defect issues associated with a Test Execution issue. These can be directly linked with the issue using JIRA issue links or defects that were created during testing within Test Runs.

Test Execution Status

This custom field provides information about the progress (i.e. the "Overall Execution Status") of the Test Execution issue.

It can be used, for example, in gadgets, included in the cards of Agile boards, used as a column in JIRA issues listing.

This field is non-searchable.

 

Test Set Status

The "Test Set Status" custom field  is a calculated field, usable in the context of Test Set issues, that calculates the "status" (not the workflow status) of all the Tests within the Test Set, for a specific version, having in mind executions (i.e. test runs) for that version. The version that it calculates the status for depends on the behaviour for that field defined in a global configuration (see configuration details here).

Although a Test Set in Xray is basically a list of Tests,thus not related with any execution whatsoever, you can add this field to the Test Ser view screen as a way to have a glance of the current status of the Tests that are part of it, for some version right from the screen of the Test Set. This can be quite useful if you have some highly relevant Test Sets and you wish to quickly have an high-level idea of the status of the Tests that belong to it.

This field is non-searchable.

   

Test Plan Status

This custom field provides information about the progress (i.e. the "Overall Execution Status") of the Test Plan issue.

It can be used, for example, in gadgets, included in the cards of Agile boards, used as a column in JIRA issues listing.

This field is non-searchable.

   

Adding your own custom fields

You may add CFs to Tests, however they’re not copied to the Test Run. Custom fields at Tests can be seen as complementary, non-relevant information.

But adding custom fields is not limited to the Test issue type; they can also be added to other Xray issue types, including the Test Execution and the Test Plan. For example, in the Test Execution you could add a custom field to identify the browser version. Note that, in this example, if you wanted to analyze your Test Execution per browser, it would be preferable to reuse the Test Environments custom field instead; otherwise, you can add some custom fields to the Test Execution if their purpose is just to add more context to it.

Recommendations

• Don’t reinvent the wheel; use standard fields, such as labels and components, and avoid creating custom fields without need
• Remember that custom fields added to Tests are not copied to Test Runs, so they’re volatile/informative only; they’re not part of the specification