JQL (Jira Query Language) is the most powerful and flexible way to search for your issues in Jira.

Xray adds a lot of functions and new custom fields that can help you search and find the information you need.

How to use Xray JQL functions & custom fields?

You can use them to:

Search for issues, using Jira Search
Customized your reports, by using advanced features
Create filters than can be displayed into dashboards
Create filters that can be used to configure gadgets

Xray JQL functions to remember

The following JQL functions can be very useful and will enable you to query the relationships between Xray issue types.

JQL Function

Parameters

Purpose

Example

requirementTests

P1 - Requirement Issue Key/Filter of Requirement Issues

Returns a list of Test issues associated with the input Requirement issue key or saved filter with Requirements.

(1)

issuetype = 'Test'

   and key in requirementTests('DEMO-10')

(2)

issuetype = 'Test'

   and key in requirementTests('Requirements saved filter')

testsWithoutTestExecution

None

Returns a list of Tests that are not associated with a Test Execution to be executed

(1)

issuetype = Test and issue in testsWithoutTestExecution()

testTestExecutions

P1 - Test Issue Key/Id or Filter Name/Id

P2 - Test Run Status list separated by "|"(pipe) (Optional)

Returns a list of test executions associated with the input Test Issues from P1 optionally filtered by the current Test status in each Test Execution issue.

Parameter P1 can either be a single Test issue key or Id or a saved filter name or id containing multiple Test issues.

Possible Test Run Status values are: PASS, FAIL, EXECUTING, ABORTED, TODO and all custom statuses.

(1)

issuetype = 'Test Execution'

   and issue in testTestExecutions('DEMO-9')

(2)

issuetype = 'Test Execution'

   and issue in testTestExecutions('DEMO-9',

                                   'PASS')

(3)

issuetype = 'Test Execution'

   and issue in testTestExecutions(

                      'Saved Test Filter',

                      'PASS')

There are a lot of JQL functions that you can explore and add to your searches or filters. Please check the full list at Xray's Documentation.

Xray custom fields to remember

Xray also provides custom fields to allow more refined queries when searching for issues.

JQL Function

Issue Type

Description

Example

Test Type

Test

The Test type: Manual; Cucumber; Generic

issuetype = 'Test'

   and "Test Type" = "Manual"

TestRunStatus

Test

This is a calculated custom field that provides the latest Test Run status based on the current "Test Run Status Version Strategy" option configured in the Xray administration.

Syntax: TestRunStatus = "[Group (version or TestPlan)] - [Status] environment:[environment]"

Only the Status is mandatory; if only the status is provided, Xray will assume you are searching for the latest execution

Xray will lookup for all Tests with Status in that particular version and environment.

issuetype = 'Test'

   and TestRunStatus in ("FAIL", "ABORTED")

_

issuetype = 'Test'

and TestRunStatus = "PASS"

_

issuetype = 'Test'

   and TestRunStatus = "TESTPLAN-123 - PASS"

_

issuetype = 'Test'

   and TestRunStatus = "FAIL environment:Android"

-
issuetype = 'Test'

   and TestRunStatus = "v3.0 - PASS environment:Android"

_

issuetype = 'Test'

   and TestRunStatus = "TESTPLAN-123 - PASS environment:Android"

_

issuetype = 'Test'

   and TestRunStatus is EMPTY

Requirement Status

Requirement

This is a calculated custom field that provides the requirement coverage status.

Possible status values are:

OK - All tests passed the requirement

NOK - At least one test failed

NOTRUN - At least one test did not run

UNCOVERED - The requirements is not associated with tests

testTestExecutions

Syntax: "Requirement Status" = "[Group (version or TestPlan)] - [Status] environment:[environment]"

Only the Status is mandatory; if only the status is provided, Xray will assume you are searching for the latest execution

Xray will lookup for all Requirements with Status in that particular version and environment.

If the Requirements Coverage Strategy depends on the version, then you must also include the actual version name and the status when you do the search. The syntax: "[version name] - [status]"

issuetype = 'New Feature'

   and "Requirement Status" = "OK"

issuetype = 'New Feature'

   and "Requirement Status" in ("NOTRUN", "UNCOVERED")

_

issuetype = 'New Feature'

and "Requirement Status" = "v1.0 - OK"
-

issuetype = 'New Feature'

   and "Requirement Status" = "v1.0 - OK environment:Android"

Steps Count

Test

The number of Steps in a Manual Test

issuetype = 'Test'

   and "Steps Count" = 3