Skip to content

Xray⚓︎

You can provide a bunch of Xray settings which might become necessary depending on your project configuration.

Optional settings⚓︎

status⚓︎

These status options represent the mapping of Cypress statuses to corresponding Xray test statuses. If you have custom test statuses set up in Xray, you should specify their names here.

Xray server test status dropdown

Xray cloud test status dropdown

Info

For more information on test statuses, please refer to the official documentation:

aggregate⚓︎

A function that returns a single Xray status for a given combination of Cypress statuses. It is used to determine the final status of retried and data-driven tests and is never called for tests that have only been run once.

Info

Tests are grouped by the issue keys present in their describe() and it() titles as described here.

Type
function

Default 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
({ failed, passed, pending, skipped }) => {
    if (passed > 0 && failed === 0 && skipped === 0) {
        // return Xray status for passed Cypress status
    }
    if (passed === 0 && failed === 0 && skipped === 0 && pending > 0) {
        // return Xray status for pending Cypress status
    }
    if (skipped > 0) {
        // return Xray status for skipped Cypress status
    }
    // return Xray status for failed Cypress status
}

Example

The following example defines custom FLAKY and ABORTED statuses for iterated tests:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            aggregate: ({ failed, passed, pending, skipped }) => {
                if (passed > 0 && failed === 0 && skipped === 0) {
                    return "PASSED";
                }
                if (passed === 0 && failed === 0 && skipped === 0 && pending > 0) {
                    return "FLAKY";
                }
                if (skipped > 0) {
                    return "ABORTED";
                }
                return "FAILED";
            },
        },
    },
});

failed⚓︎

The Xray status name of a test marked as failed by Cypress.

Environment variable
XRAY_STATUS_FAILED
Type
string
Default
"FAIL" (when providing Xray server credentials)
"FAILED" (when providing Xray cloud credentials)
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            failed: "FAILURE"
        }
    },
});

1
npx cypress run --env XRAY_STATUS_FAILED=FAILURE

passed⚓︎

The Xray status name of a test marked as passed by Cypress.

Environment variable
XRAY_STATUS_PASSED
Type
string
Default
"PASS" (when providing Xray server credentials)
"PASSED" (when providing Xray cloud credentials)
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            passed: "SUCCESS"
        }
    },
});

1
npx cypress run --env XRAY_STATUS_PASSED=SUCCESS

pending⚓︎

The Xray status name of a test marked as pending by Cypress.

Environment variable
XRAY_STATUS_PENDING
Type
string
Default
"TODO" (when providing Xray server credentials)
"TO DO" (when providing Xray cloud credentials)
Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            pending: "AWAITING EXECUTION"
        }
    },
});

1
npx cypress run --env XRAY_STATUS_PENDING="AWAITING EXECUTION"

skipped⚓︎

The Xray status name of a test marked as skipped by Cypress.

Environment variable
XRAY_STATUS_SKIPPED
Type
string
Default
"FAIL" (when providing Xray server credentials)

"FAILED" (when providing Xray cloud credentials)

Note

Defaults to "FAILED" because Cypress only skips test cases if errors occur, as described here.

Example 
1
2
3
4
5
6
7
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            skipped: "IGNORED"
        }
    },
});

1
npx cypress run --env XRAY_STATUS_SKIPPED="IGNORED"

step⚓︎

These status options represent the mapping of step statuses to corresponding Xray step statuses. If you have custom statuses set up in Xray, you should specify their names here.

Xray server test step status dropdown

Xray cloud test step status dropdown

Info

For more information on test step statuses, please refer to the official documentation:

Note

These are currently only accessed in Cucumber report conversion. If you're not using Cucumber in your project, you can safely ignore them.

failed⚓︎

The Xray status name of a step marked as failed.

Environment variable
XRAY_STATUS_STEP_FAILED
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            step: {
                failed: "FAILURE"
            }
        }
    },
});

1
npx cypress run --env XRAY_STATUS_STEP_FAILED=FAILURE
passed⚓︎

The Xray status name of a step marked as passed.

Environment variable
XRAY_STATUS_STEP_PASSED
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            step {
                passed: "SUCCESS"
            }
        }
    },
});

1
npx cypress run --env XRAY_STATUS_STEP_PASSED=SUCCESS
pending⚓︎

The Xray status name of a step marked as pending.

Environment variable
XRAY_STATUS_STEP_PENDING
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            step: {
                pending: "AWAITING EXECUTION"
            }
        }
    },
});

1
npx cypress run --env XRAY_STATUS_STEP_PENDING="AWAITING EXECUTION"
skipped⚓︎

The Xray status name of a step marked as skipped.

Environment variable
XRAY_STATUS_STEP_SKIPPED
Type
string
Default
undefined
Example 
1
2
3
4
5
6
7
8
9
await configureXrayPlugin(on, config, {
    xray: {
        status: {
            step: {
                skipped: "IGNORED"
            }
        }
    },
});

1
npx cypress run --env XRAY_STATUS_STEP_SKIPPED=IGNORED

testEnvironments⚓︎

The test environments for test execution issues. These will be used as follows:

  • if the plugin creates new test execution issues, they will be associated with the issue
  • if the plugin reuses existing test execution issues, they will either:
    • replace existing test environments
    • be added if the issue does not yet have any test environments associated

Note

Xray's API only allows replacing test environments in the plugin's scope. It is not possible to completely remove all existing test environments during result upload. Completely removing all existing environments needs to be done manually.

This means that you will always need to specify one or more test environments to replace all existing ones, or leave them as is by omitting the option entirely.

For more information about working with test environments, make sure to check out the documentation for Xray server or Xray cloud.

Environment variable
XRAY_TEST_ENVIRONMENTS
Type
string[]
Default
undefined
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    xray: {
        testEnvironments: ["DEV", "v3.1"]
    },
});

1
npx cypress run --env XRAY_TEST_ENVIRONMENTS=[DEV,v3.1]

uploadRequests⚓︎

Enables or disables the upload of manually executed requests using cy.request. If true, requests and responses will be attached to the corresponding test as evidence. If false or left undefined, neither requests nor responses are attached.

Note

For this option to work properly, you need to overwrite the cy.request command.

Environment variable
XRAY_UPLOAD_REQUESTS
Type
boolean
Default
false
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    xray: {
        uploadRequests: true
    },
});

1
npx cypress run --env XRAY_UPLOAD_REQUESTS=true

uploadResults⚓︎

Turns execution results upload on or off. Useful when switching upload on or off from the command line (via environment variables).

Environment variable
XRAY_UPLOAD_RESULTS
Type
boolean
Default
true
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    xray: {
        uploadResults: false
    },
});

1
npx cypress run --env XRAY_UPLOAD_RESULTS=false

uploadScreenshots⚓︎

Turns on or off the upload of screenshots Cypress takes during test execution.

Note

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

Environment variable
XRAY_UPLOAD_SCREENSHOTS
Type
boolean
Default
true
Example 
1
2
3
4
5
await configureXrayPlugin(on, config, {
    xray: {
        uploadScreenshots: false
    },
});

1
npx cypress run --env XRAY_UPLOAD_SCREENSHOTS_=false