Skip to main 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

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

({ 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:

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 when providing Xray server credentials : "FAIL"

Default when providing Xray cloud credentials : "FAILED"

Example
await configureXrayPlugin(on, config, {
  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 when providing Xray server credentials : "PASS"

Default when providing Xray cloud credentials : "PASSED"

Example
await configureXrayPlugin(on, config, {
  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 when providing Xray server credentials : "TODO"

Default when providing Xray cloud credentials : "TO DO"

Example
await configureXrayPlugin(on, config, {
  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 when providing Xray server credentials : "FAIL"

Default when providing Xray cloud credentials : "FAILED"

note

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

Example
await configureXrayPlugin(on, config, {
  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

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
await configureXrayPlugin(on, config, {
  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
await configureXrayPlugin(on, config, {
    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
await configureXrayPlugin(on, config, {
  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
await configureXrayPlugin(on, config, {
  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
await configureXrayPlugin(on, config, {
  xray: {
    testEnvironments: ["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
await configureXrayPlugin(on, config, {
  xray: {
    uploadRequests: 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
await configureXrayPlugin(on, config, {
  xray: {
    uploadResults: 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
await configureXrayPlugin(on, config, {
  xray: {
    uploadScreenshots: false,
  },
});

url​

The Xray base URL to use. For more information please refer to the official documentation:

Environment variable : XRAY_URL

Type : string

Default : jira.url for Xray server and https://xray.cloud.getxray.app for Xray cloud

Example
await configureXrayPlugin(on, config, {
  xray: {
    url: "https://eu.xray.cloud.getxray.app",
  },
});