Skip to content

Jira⚓︎

In order to access Xray, some Jira configuration is mandatory.

Mandatory settings⚓︎

projectKey⚓︎

The key of the Jira project. This option is mandatory since otherwise Xray would not know which project to work with. It is used in many places throughout the plugin, for example for mapping Cypress tests to existing test issues in Xray.

Environment variable
JIRA_PROJECT_KEY
Type
string
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        projectKey: "PRJ"
    },
});

1
npx cypress run --env JIRA_PROJECT_KEY="PRJ"

url⚓︎

Use this parameter to specify the base URL of your Jira instance.

For Jira cloud, it is usually of the form https://your-domain.atlassian.net (without the /jira part, see here).

For Jira server, you can have a look here to determine your base URL.

Environment variable
JIRA_URL
Type
string
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        url: "https://example.org/development/jira"
    },
});

1
npx cypress run --env JIRA_URL="https://example.org/development/jira"

Optional settings⚓︎

attachVideos⚓︎

Whether any videos Cypress captured during test execution should be attached to the test execution issue on results upload.

Note

This option only takes effect once uploadResults is turned on. It is not possible to attach videos without uploading results.

Environment variable
JIRA_ATTACH_VIDEOS
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin({
    jira: {
        attachVideos: true
    },
});

1
npx cypress run --env JIRA_ATTACH_VIDEOS=true

fields⚓︎

Jira Field IDs to make all fields required during the upload process uniquely identifiable. By default, the plugin accesses field information using the fields' names (ignoring case). Therefore, providing Jira field IDs can make sense in the following scenarios:

  • Your Jira language setting is a language other than English

    Example

    When the plugin tries to access the test environments of issues, it will look for a field with name Test Environments by default. However, if Jira is set to French for example, it will return a field called Environnements de Test instead.

    In these situations, the plugin will display an error message containing the fields it received and their IDs. The ID of field Environnements de Test could then be copied to the testEnvironments option, fixing the error in future uploads:

    1
2
3
4
5
6
7
    Failed to fetch Jira field ID for field with name: Test Environments
Make sure the field actually exists and that your Jira language settings did not modify the field's name

Available fields:
  name: Environnements de Test, id: customfield_11805
  name: Type de Test,           id: customfield_42069
  ...

  • Your Jira project contains several fields with identical names

    Example

    Jira does not prohibit configuring multiple fields with the same name. There might be multiple fields called Test Environments for example, the default Xray one and another one for descriptions of defects reported by customers in user acceptance tests.

    In these situations, the plugin will display an error message containing the duplicates it detected and their properties, including the field IDs. The ID of Jira's test environments field could then again be copied to the testEnvironments option, fixing the error in future uploads:

    1
2
3
4
5
6
7
    Failed to fetch Jira field ID for field with name: Test Environments
There are multiple fields with this name

Duplicates:
  id: customfield_11805, name: Test Environments, clauseNames: Test Environments
  id: customfield_12345, name: Test Environments, clauseNames: Test Environments (user acceptance)
  ...

Info

Please consult the official documentation for more information about field IDs: https://confluence.atlassian.com/jirakb/how-to-find-id-for-custom-field-s-744522503.html

description⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. Field description is a system field and will always have the ID description. It is no longer necessary to specify this field ID.

The description field ID of Jira issues.

Environment variable
JIRA_FIELDS_DESCRIPTION
Type
string
Default
"description"
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        fields: {
            description: "Beschreibung" // German
        }
    },
});

1
npx cypress run --env JIRA_FIELDS_DESCRIPTION=Beschreibung

labels⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. Field labels is a system field and will always have the ID labels. It is no longer necessary to specify this field ID.

The labels field ID of Jira issues.

Environment variable
JIRA_FIELDS_LABELS
Type
string
Default
"labels"
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        fields: {
            labels: "Stichworte" // German
        }
    },
});

1
npx cypress run --env JIRA_FIELDS_LABELS=Stichworte

summary⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. Field summary is a system field and will always have the ID summary. It is no longer necessary to specify this field ID.

The summary field ID of Jira issues.

Environment variable
JIRA_FIELDS_SUMMARY
Type
string
Default
"summary"
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        fields: {
            summary: "Beschreibung" // German
        }
    },
});

1
npx cypress run --env JIRA_FIELDS_SUMMARY=Beschreibung

testEnvironments⚓︎

The Xray test environments field ID (i.e. the test environments associated with test execution issues).

Note

This option is required for server instances only. Xray cloud provides ways to retrieve test environment field information independently of Jira.

Environment variable
JIRA_FIELDS_TEST_ENVIRONMENTS
Type
string
Default
"test environments"
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        fields: {
            testEnvironments: "customfield_12345"
        }
    },
});

1
npx cypress run --env JIRA_FIELDS_TEST_ENVIRONMENTS=customfield_12345

testPlan⚓︎

The Jira field ID of test plans in Xray test (execution) issues.

Note

This option is necessary for server instances only. Xray cloud provides ways to retrieve test plan field information independently of Jira.

Environment variable
JIRA_FIELDS_TEST_PLAN
Type
string
Default
"test plan"
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        fields: {
            testPlan: "customfield_12345"
        }
    },
});

1
npx cypress run --env JIRA_FIELDS_TEST_PLAN=customfield_12345

testExecutionIssue⚓︎

This option can be used to configure the test execution issue that the plugin will either create or modify with the run results. The value must match the format of Jira's issue create/update payloads:

Note

Because the data here has to go through Xray first, it is possible that some fields that Jira normally is happy to accept will be rejected by Xray. For example, the assignee may need to be set using the name property instead of account IDs (see FAQ).

You can do cool things here, including:

Almost everything you can do when you create Jira issues using the Jira API, you can also do here. Make sure to check out the Jira API documentation for more information.

Tip

The plugin also accepts a function that allows you to specify dynamic values based on the Cypress results.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: ({ results }) => {
            if (results.totalFailed > 0) {
                return {
                    fields: {
                        summary: "Failed test execution"
                    }
                };
            }
            return {
                fields: {
                    summary: "Perfect test execution"
                }
            };
        }
    }
});

Warning (affected versions: 7.2.0 ≤ version < 8.0.0)

While conflicting options such as testExecutionIssueDescription or testExecutionIssueSummary are still available, the fields and values defined in testExecutionIssue will take precedence over all options marked as deprecated. The following code configuration will create test executions with Blue summary and Blue description fields:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                summary: "Blue summary",
                description: "Blue description"
            }
        },
        testExecutionIssueSummary: "Red summary", // ignored
        testExecutionIssueDescription: "Red description", // ignored
    },
});
Environment variable
JIRA_TEST_EXECUTION_ISSUE
Type
object
Default
undefined

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            key: "PRJ-16",
            fields: {
                summary: "My execution issue summary",
                description: "My execution issue description",
                assignee: {
                    name: "cool.turtle@company.com"
                },
                customfield_12345: "Sprint 17"
            }
        }
    },
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE='{"key":"PRJ-16","fields":{"summary":"My execution issue summary","description":"My execution issue description","assignee":{"name":"cool.turtle@company.com"},"customfield_12345":"Sprint 17"}}'

fields⚓︎

These options modify the fields of the test execution issue that is either created or modified by each test run.

description⚓︎

The description of test execution issues, which will be used both for new test execution issues as well as for updating existing issues (if one was provided through key).

If the key is configured but description is omitted, the existing test execution issue's description will not be modified.

Environment variable
JIRA_TEST_EXECUTION_ISSUE
Type
string
Default
`Cypress version: ${version} Browser: ${name} (${version})` with values depending on Cypress and the chosen browser
Example 
1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                description: "Release Test Results for v42.0"
            }
        }
    }
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE='{"fields":{"description":"Release Test Results for v42.0"}}'
issuetype⚓︎

The issue type of test executions. By default, Xray calls them Test Execution, but it's possible that they have been renamed or translated in your Jira instance.

Use this option to specify the type of the test executions the plugin should create for each run.

Environment variable
JIRA_TEST_EXECUTION_ISSUE
Type
string
Default
'Test Execution'
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                issuetype: {
                    id: "12345",
                    name: "Xray Test Execution",
                    // ... more properties to uniquely identify the issue type
                }
            }
        }
    }
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE='{"fields":{"issuetype":{"id":"12345","name":"Xray Test Execution"}}}'
summary⚓︎

The summary of test execution issues, which will be used both for new test execution issues as well as for updating existing issues provided through key.

If the key is configured but the summary is omitted, the existing test execution issue's summary will not be modified.

Environment variable
JIRA_TEST_EXECUTION_ISSUE
Type
string
Default
`Execution Results [${t}]` with t being a Unix timestamp when Cypress started testing
Example 
1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                summary: "my summary"
            }
        }
    }
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE='{"fields":{"summary":"my summary"}}'

key⚓︎

The key of the test execution issue to attach the run results to. If omitted, Jira will always create a new test execution issue with each upload.

Environment variable
JIRA_TEST_EXECUTION_ISSUE
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            key: "PRJ-123"
        }
    }
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE='{"key":"PRJ-123"}'

testExecutionIssueDescription⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. To define a description, please use description instead:

1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                description: "my description"
            }
        }
    },
});

The description of test execution issues, which will be used both for new test execution issues as well as for updating existing issues (if one was provided through testExecutionIssueKey).

If the testExecutionIssueKey is configured but the testExecutionIssueDescription is omitted, the existing test execution issue's description will not be modified.

Environment variable
JIRA_TEST_EXECUTION_ISSUE_DESCRIPTION
Type
string
Default
`Cypress version: ${version} Browser: ${name} (${version})` with values depending on Cypress and the chosen browser
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssueDescription: "This test run was approved by Mr Anderson."
    },
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE_DESCRIPTION="This test run was approved by Mr Anderson."

testExecutionIssueKey⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. To reuse a test execution issue, please use key instead:

1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            key: "PRJ-123"
        }
    },
});

The key of the test execution issue to attach the run results to. If omitted, Jira will always create a new test execution issue with each upload.

Note

Must be prefixed with the project key.

Environment variable
JIRA_TEST_EXECUTION_ISSUE_KEY
Type
string
Default
undefined
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssueKey: "PRJ-123"
    },
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE_KEY="PRJ-123"

testExecutionIssueSummary⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. To define a summary, please use summary instead:

1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                summary: "my summary"
            }
        }
    },
});

The summary of test execution issues, which will be used both for new test execution issues as well as for updating existing issues (if one was provided through testExecutionIssueKey).

If the testExecutionIssueKey is configured but the testExecutionIssueSummary is omitted, the existing test execution issue's summary will not be modified.

Environment variable
JIRA_TEST_EXECUTION_ISSUE_SUMMARY
Type
string
Default
`Execution Results [${t}]` with t being a Unix timestamp when Cypress started testing
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssueSummary: "Monday morning regression test"
    },
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE_SUMMARY="Monday morning regression test"

testExecutionIssueType⚓︎

Deprecated since 7.2.0

Will be removed in version 8.0.0. To define a test execution issue type, please use issuetype instead:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssue: {
            fields: {
                issuetype: {
                    // whatever is necessary to uniquely identify the issue type, e.g:
                    name: "Xray Test Execution",
                    id: "12345"
                }
            }
        }
    },
});

The issue type name of test executions. By default, Xray calls them Test Execution, but it's possible that they have been renamed or translated in your Jira instance.

Use this option to specify the type of the test executions the plugin should create for each run (if needed, see here).

Environment variable
JIRA_TEST_EXECUTION_ISSUE_TYPE
Type
string
Default
Test Execution
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        testExecutionIssueType: "Test Run"
    },
});

1
npx cypress run --env JIRA_TEST_EXECUTION_ISSUE_TYPE="Test Run"

testPlanIssueKey⚓︎

A test plan issue to attach the execution to.

Environment variable
JIRA_TEST_PLAN_ISSUE_KEY
Type
string
Default
undefined
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        testPlanIssueKey: "PRJ-456"
    },
});

1
npx cypress run --env JIRA_TEST_PLAN_ISSUE_KEY="PRJ-456"

testPlanIssueType⚓︎

Deprecated since 7.4.0

Will be removed in version 8.0.0. Unused.

The issue type name of test plans. By default, Xray calls them Test Plan, but it's possible that they have been renamed or translated in your Jira instance.

Note

You can ignore this setting if:

  • you're using Xray cloud or
  • you're not running any Cucumber tests

The plugin only accesses this option when:

  • you're using Xray server and
  • you're running Cucumber tests and
  • a test plan issue key has been specified and it's trying to attach the test execution to it
Environment variable
JIRA_TEST_PLAN_ISSUE_TYPE
Type
string
Default
Test Plan
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    jira: {
        testPlanIssueType: "Plan de test" // 🇫🇷
    },
});

1
npx cypress run --env JIRA_TEST_PLAN_ISSUE_TYPE="Plan de test"