Test Run Custom Fields in Jira: Record Failure Reasons With Xray Cloud

A reusable checkout Test can encounter different problems in different executions. One run might show the wrong order confirmation; another might stop at an environment error. A single failure-reason field on the Test work item cannot represent those separate contexts clearly. The classification belongs with the individual run.

Xray Cloud provides Test Run custom fields for this purpose. Configure the field in Xray's settings and record its value on the relevant execution screen. Before making it Required, decide how the team will classify nonfailure outcomes too: an applicable required run field prevents a final status whenever its value is missing, not only when the intended result is a failure. The procedure below is for a future authorized setup; no Jira or Xray configuration or test execution has been performed here.

Choose the Field's Owner Before Configuring It

There are three different places a similarly named field could belong. An Xray Test is a reusable Jira work item with a test definition. A Jira custom field on that Test describes the work item, rather than supplying a separate value for every execution context. Keep reusable information, such as the purpose of the check, separate from the reason reported for a particular run.

A Test Execution is the Jira issue that organizes execution of associated Tests. A field on that container can describe the overall execution, but it does not become an individual failure reason for every Test inside it. If the container includes Tests with different problems, a single issue-level value would leave those differences ambiguous.

A Test Run is Xray's internal record for a Test in its Test Execution context. It is not a separate Jira issue. Xray's run custom fields hold additional information at that level. Creating an ordinary Jira custom field, adding it to an issue screen, or changing a Jira field configuration is therefore not the setup route for the run field taught here. Do not assume that a run field is automatically available as an ordinary Jira field in JQL.

The run also contains a copy of selected Test specification fields. That copy is not a copy of every Jira field: Xray's Test Runs documentation specifically excludes general custom fields, summary and description from the copied specification. The execution screen can still show current Test issue context, including its description. Visible issue information and run-owned recording are different things; recording a run reason does not require rewriting the reusable Test definition.

Prepare the Cloud Field and Its Recording Policy

A useful field needs both an applicable scope and a meaning testers can apply consistently. Agree those decisions before an administrator changes the configuration, particularly when the field could prevent testers from completing otherwise valid work.

Confirm Installation, Access and Scope

This procedure assumes Xray is installed and configured for Jira Cloud, with the relevant Test and Test Execution work types available. The target tenant, its settings and its permissions have not been inspected. An administrator should confirm the intended Space or project, applicable Test Types, field access and authorized handling of any test data before proceeding.

The current Space Settings guide requires Admin Space permissions for the relevant settings access. Permission to configure the field is separate from permission to execute a Test. Xray's execution guide requires Browse and Resolve permission for the Test Execution issue, and neither that issue nor the Test issue may be in a workflow status configured to disallow execution. Having access to an execution details page can still mean read-only access.

Cloud documentation currently uses Space terminology in the administration guide while some execution guidance still says project. Follow the labels supported in the target Cloud tenant, rather than importing a Server or Data Center navigation path.

Create the Field in Xray Settings

For an authorized future configuration, follow the documented Space route:

1. Enter the intended Space and open its ellipsis menu.
2. Choose Space settings, then Apps, then Xray Settings.
3. Open Test Run Custom Fields and choose Create Test Run Custom Field.
4. Set Type, Name, Description and the applicable Test Type selection. Decide whether Required should be enabled before using Create.

The field reference lists Toggle Switch, Date Picker, Date Time Picker, Number, Radio Buttons, Select List, Select List (Multiple), Text, Text (Single Line) and User Picker. Choose a type that matches the information being collected. A failure-context label does not need a date or a person field merely because those types exist.

The illustration below proposes Text (Single Line). Its vocabulary would be a team convention, not a configured select-option list. A team wanting a selection-based taxonomy should confirm the supported option controls in its own configuration before choosing Select List or another selection type; this procedure does not invent those controls or claim they were configured.

Use the Description to explain what the field means and what it does not mean. A concise reporting classification should identify the context needing investigation. It should not encourage a tester to label a suspected root cause as established fact. An Unknown / needs investigation convention can preserve uncertainty when the team permits it.

Decide Whether Every Final Outcome Needs a Value

The operational rule is broader than a failure-only requirement. Xray says users cannot set a final Test Run status while an applicable required custom field remains unpopulated. Its documented native run statuses are TO DO, EXECUTING, FAILED and PASSED; PASSED and FAILED are identified as final statuses. Tenant-specific custom statuses and available transitions need their own configuration review.

Consequently, a required Failure Context field also needs an honest way to handle a successful outcome. A team could agree No failure / not applicable as a nonfailure value, provided that value is appropriate and supported by the chosen field design. It must not become a convenient way to close an unresolved failure without classifying it.

Alternatively, leave the field optional and define a separate team review convention for failed runs. An optional field may remain empty unless another agreed rule requires review. Required is not documented here as conditional on FAILED, and it is not a Jira workflow validator. The configuration reference reuses some Test Step wording in its descriptions; use the explicit Test Run final-status rule in the execution guide when deciding the effect of Required.

Record the Value on the Intended Test Run

Once an authorized administrator has established the field and the team has approved its meaning, an authorized tester would work in the specific Test Execution issue. Open Test Runs and select the play icon on the intended Test's row to reach its execution screen. Confirm the Test, execution context and applicable Test Type before entering a classification; a similarly named reusable Test or execution container is not enough to identify the intended run.

The execution screen's Findings area includes Custom Fields. Fields defined for that run's project and Test Type appear there. Record the value in that run's field, rather than editing the Test issue or placing one shared reason on the Test Execution issue. Use the field interaction supported in the tenant and read the value back on the same run before relying on it; do not assume a particular Save button or an automatic propagation behavior that has not been verified.

Keep the classification distinct from the actual result. Step results describe what happened at the relevant step; comments, evidence and defect links add supporting context. Record the tested build and environment through the team's established execution records, and make severity or defect decisions separately. A reason label cannot replace reproduction details, establish the cause of an error or explain every aspect of a bug.

If the required value is missing, populate it truthfully before attempting a final result. A nonempty field satisfies this field's presence requirement, not every permission or step-result constraint. It also does not approve a release.

One Unexecuted Same-Test Illustration

The following source packet is deliberately fictional. It holds the reusable definition constant while varying the proposed run context. Nothing in it is an observed customer result or evidence that a field was created, a status changed, or a Test executed.

Proposed Configuration and Inputs

RUN-FIELD-25v1 is one fictional, UNEXECUTED configuration and run-recording illustration. Its assumed reusable Manual Test, Checkout Confirmation, has definition v1: submit a permitted checkout and check that the confirmation identifies the submitted order. Proposed Execution A and proposed Execution B would each associate that same Test with their own Test Run in the fictional Checkout Space. These labels are teaching references, not live Jira keys or Test Run IDs. The original reusable Test definition remains unchanged throughout this illustration.

The authored field proposal is Failure Context, type Text (Single Line), applicable only to Manual Tests in Checkout Space, with Required enabled. Its team vocabulary is Checkout outcome mismatch, Environment response interruption, Unknown / needs investigation, and No failure / not applicable. These are authored reporting conventions, not Xray-supplied categories or a configured select-option list; a text field does not enforce this vocabulary. No failure / not applicable is reserved for a genuinely nonfailure outcome and must not disguise an unresolved failure. Classification describes the reported context and is not proof of root cause.

The invented input for Execution A is a confirmation showing a different order from the submitted order; its proposed run value is Checkout outcome mismatch. The invented input for Execution B is an environment error response interrupting the same checkout check; its proposed run value is Environment response interruption. FAILED is only a hypothetical final target for each proposed run, subject to the team's approved result policy. No customer behavior, actual execution, evidence attachment, or saved field value has been observed. Actual tenant settings, permissions, data authorization, configuration approval, run outcomes, and human acceptance are Unknown / NOT RUN.

Proposed Recording and Gate Interpretation

For the proposed recording, keep Checkout outcome mismatch on Execution A's own Test Run and Environment response interruption on Execution B's own Test Run. Neither value belongs in the reusable Test definition or in a single Test Execution issue field representing all its Tests. Do not reuse one Test Run ID across the two proposed Executions. Separate run ownership explains the distinct values; this unexecuted design is not a product round-trip or historical-retention test.

Within the field's applicable Manual scope, a missing required value would block any final target, including FAILED and PASSED. A populated value would satisfy this field's presence check only; it would not prove the classification truthful or satisfy every permission, step-result, or workflow constraint. A nonfailure target would need an honest nonfailure value under the authored convention. No failure / not applicable on a real unresolved failure would be wrong even though the field was nonempty. The documented final-status rule alone does not establish a block on the nonfinal EXECUTING target.

An out-of-scope Test Type would not be gated by this field. As a comparison rather than another configured example, an optional field could remain empty unless the team separately required review; Required is not documented here as failure-only conditional logic or a Jira workflow validator. Preserve actual results, step details, environment and build context, permitted evidence, severity decisions, and defect links separately from the classification. Configuration approval and a satisfied field check would authorize neither application execution nor release acceptance. All real configuration changes, run updates, approvals, and results remain Unknown / NOT RUN.

Field Scope and Rule	Proposed Value	Target Status	Meaning of This Field Check
Applicable Manual; Required	Empty	FAILED	Missing value blocks the final target.
Applicable Manual; Required	Empty	PASSED	Missing value also blocks the nonfailure final target.
Applicable Manual; Required	Appropriate failure context	FAILED	Presence check satisfied; other constraints and truthfulness still need review.
Applicable Manual; Required	No failure / not applicable	PASSED	Presence check satisfied only if this is an honest nonfailure classification.
Applicable Manual; Required	No failure / not applicable on an unresolved failure	FAILED	Nonempty does not make the classification correct.
Applicable Manual; Required	Empty	EXECUTING	The final-status rule alone does not establish a block.
Outside the selected Test Type	Empty	Any final target	This field does not apply and does not supply the gate.
Optional-field comparison	Empty	Any final target	This field is not a required-value gate; team review may still apply.

These are predicted field-check interpretations, not accepted transitions or executed outcomes. The optional row compares a policy choice; it does not describe another configured tenant. A correct classification still needs supporting evidence and human review.

Review the Record Without Promising Unverified History

Before adopting the field in real work, arrange a separately authorized tenant check covering the intended project, Test Type and permissions. Review both failure and nonfailure final targets, an empty value and a truthful populated value. If the field is intentionally Manual-only, confirm that another Test Type is outside that field's scope. Those checks would establish behavior in that tenant; this article has not performed them.

For each recorded reason, a reviewer should be able to identify the particular Test Run, understand the classification and locate the actual result and permitted supporting evidence. Challenge values that assert more than the evidence shows. An environment error can describe a reported condition without proving that infrastructure, test data or application code caused it.

Do not treat this procedure as a guarantee about what happens after a field definition is renamed, deleted or otherwise changed. Historical-value retention, selection-option changes, reports, exports and search behavior need separate documentation and verification for the intended operation. Likewise, do not reset or merge a Test Run merely to record a failure reason; those are separate specification-update operations with consequences for recorded execution information.

Agree the vocabulary and nonfailure handling before enabling Required. Then keep each reason on its own run, preserve the reusable Test definition, and review the classification alongside the execution evidence. A completed field is a recording control, not proof of root cause, performed testing or release acceptance.