{"id":13053,"library":"cypress-xray-plugin-v15-compat","title":"Cypress Xray Plugin (v15 Compatibility Fork)","description":"cypress-xray-plugin-v15-compat (version 1.0.0) is a Cypress plugin designed for integrating test results with Xray, a test management tool for Jira (supporting both Server/DC and Cloud versions). This package is specifically noted as a fork, inheriting much of its functionality and documentation from the actively maintained `qytera-gmbh/cypress-xray-plugin` (itself a fork of `csvtuda/cypress-xray-plugin`). It facilitates uploading Cypress test results, including attaching screenshots, web requests, and videos as test execution evidence to Xray. Key features encompass the ability to reuse existing Xray test execution and test plan issues, CI/CD readiness through environment variables for credentials, and robust Cucumber integration for synchronizing step definitions and uploading results. This specific compatibility version is designed to work with modern Cypress environments (requiring Cypress >=10.0.0 and Node.js >=18.0.0), providing comprehensive Xray integration directly from Cypress, covering various evidence types and secure authentication mechanisms.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/CaiqueCoelho/cypress-xray-plugin","tags":["javascript","cypress","xray","upload","screenshot","video","cucumber","typescript"],"install":[{"cmd":"npm install cypress-xray-plugin-v15-compat","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-xray-plugin-v15-compat","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-xray-plugin-v15-compat","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides Cucumber integration for synchronizing step definitions and uploading results.","package":"@badeball/cypress-cucumber-preprocessor","optional":true},{"reason":"The core end-to-end testing framework that this plugin extends.","package":"cypress","optional":false}],"imports":[{"note":"Primary setup function for ESM environments (Cypress configuration files are typically ESM).","wrong":"import configureXrayPlugin from 'cypress-xray-plugin';","symbol":"configureXrayPlugin","correct":"import { configureXrayPlugin } from 'cypress-xray-plugin';"},{"note":"CommonJS import for Node.js environments or older Cypress configurations where ESM imports are not yet adopted.","wrong":"const configureXrayPlugin = require('cypress-xray-plugin');","symbol":"configureXrayPlugin","correct":"const { configureXrayPlugin } = require('cypress-xray-plugin');"},{"note":"Type-only import for TypeScript users to define the plugin's configuration object, leveraging the shipped TypeScript types.","wrong":"import { XrayPluginConfig } from 'cypress-xray-plugin';","symbol":"XrayPluginConfig","correct":"import type { XrayPluginConfig } from 'cypress-xray-plugin';"}],"quickstart":{"code":"npm install --save-dev cypress-xray-plugin\n\n// cypress.config.ts\nimport { defineConfig } from 'cypress';\nimport { configureXrayPlugin } from 'cypress-xray-plugin';\n\nexport default defineConfig({\n  e2e: {\n    async setupNodeEvents(on, config) {\n      // This is required for the Xray plugin to configure itself\n      await configureXrayPlugin(on, config, {\n        jira: {\n          projectKey: process.env.JIRA_PROJECT_KEY ?? 'PRJ',\n          url: process.env.JIRA_URL ?? 'https://example.org',\n        },\n        // Other configurations like authentication should be set via environment variables\n        // e.g., process.env.XRAY_CLIENT_ID, process.env.XRAY_CLIENT_SECRET\n      });\n      return config;\n    },\n  },\n});\n","lang":"typescript","description":"Shows how to install the plugin and integrate it into a Cypress project's `cypress.config.ts` using `configureXrayPlugin`, including basic Jira project setup."},"warnings":[{"fix":"Always use `npx cypress run` for test executions intended for Xray result upload, especially in CI/CD pipelines.","message":"This plugin only uploads test results when Cypress is run via the CLI (`npx cypress run`), not in the interactive 'open' mode (`npx cypress open`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the documentation and issue tracker of this specific compatibility fork (CaiqueCoelho/cypress-xray-plugin) for precise behavior, known limitations, and support.","message":"This package (`cypress-xray-plugin-v15-compat`) is explicitly a compatibility fork. While it aims for similar functionality, be aware of potential subtle differences, specific version requirements, or delayed feature parity compared to the upstream `qytera-gmbh/cypress-xray-plugin`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all required Jira/Xray authentication environment variables are correctly set and accessible in the CI/CD pipeline or local environment where Cypress is executed. Consult the authentication section of the plugin's documentation for details.","message":"Jira/Xray authentication is critical and a common point of failure. The plugin relies on environment variables (e.g., `XRAY_CLIENT_ID`, `XRAY_CLIENT_SECRET`, `JIRA_USERNAME`, `JIRA_PASSWORD`) for credentials. Incomplete or incorrect setup will lead to upload failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `XRAY_CLIENT_ID`, `XRAY_CLIENT_SECRET`, or `JIRA_USERNAME` and `JIRA_PASSWORD` environment variables are correctly set and accessible to the Cypress process.","cause":"Incorrect or missing Jira/Xray authentication details (client ID/secret or username/password environment variables).","error":"Error: Xray: Failed to authenticate. Please check your credentials."},{"fix":"Ensure Xray issue keys in Cypress test titles (e.g., `it(\"PRJ-42 My test\", ...)`) are valid and correspond to existing Xray Test issues. Check the Xray API logs or plugin verbose output for more specific error messages.","cause":"Malformed test issue key in a test title, or the specified Xray test issue does not exist or is inaccessible.","error":"Error: Xray API returned status 400: Bad Request. Check logs for details."},{"fix":"Ensure your `cypress.config.ts` file correctly exports `defineConfig` and that `setupNodeEvents` is defined as an `async` function, as shown in the quickstart example.","cause":"The Cypress configuration file is not correctly setting up the `e2e` or `component` properties, or `setupNodeEvents` is not an async function.","error":"TypeError: Cannot read properties of undefined (reading 'setupNodeEvents')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}