{"id":15308,"library":"codeceptjs-xray-cloud-helper","title":"CodeceptJS XRay Cloud Helper","description":"The `codeceptjs-xray-cloud-helper` is a CodeceptJS plugin designed to automate the process of reporting test results from CodeceptJS executions to Jira's XRAY Cloud via its REST API v2. It currently stands at stable version `2.0.1`, with a `2.1.0-beta.0` pre-release indicating ongoing development. This plugin is specifically engineered for XRAY/JIRA Cloud instances, and explicitly does not support on-premise or server versions. Its key differentiators include comprehensive support for various Xray test types (Generic, Manual, Manual with iterations, Cucumber scenario, Cucumber scenario outline), the ability to automatically create new Jira tests or link to existing ones, attach failure screenshots as evidence, link test executions to test plans, and populate custom fields for both Test Executions and Test Runs. Release cadence appears demand-driven, with updates addressing bug fixes and minor enhancements.","status":"active","version":"2.1.0-beta.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/saadichouaib/codeceptjs-xray-cloud-helper","tags":["javascript","codeceptjs","jira","xray","cloud","report"],"install":[{"cmd":"npm install codeceptjs-xray-cloud-helper","lang":"bash","label":"npm"},{"cmd":"yarn add codeceptjs-xray-cloud-helper","lang":"bash","label":"yarn"},{"cmd":"pnpm add codeceptjs-xray-cloud-helper","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a CodeceptJS plugin and requires CodeceptJS as a peer dependency for its core functionality.","package":"codeceptjs","optional":false},{"reason":"Used internally for making HTTP requests to the XRAY Cloud API, as indicated by v2.0.1 release notes improving error handling.","package":"axios","optional":false}],"imports":[{"note":"This package is a CodeceptJS plugin, and its primary consumption method is via the `plugins` configuration section in `codecept.conf.js`. It is not intended for direct programmatic imports into test files or other modules.","wrong":"import { XrayCloudHelper } from 'codeceptjs-xray-cloud-helper';","symbol":"plugin configuration","correct":"plugins: {\n    xrayImport: {\n        require: \"codeceptjs-xray-cloud-helper\",\n        enabled: true,\n        // ... other config\n    }\n}"},{"note":"The package provides a convenient CLI tool via `npx` for interactive configuration setup, which simplifies initial manual configuration.","wrong":"node node_modules/codeceptjs-xray-cloud-helper/cli.js init","symbol":"CLI initializer","correct":"npx xray-import init"}],"quickstart":{"code":"const { set</td>\n\nexports.config = {\n  tests: './*_test.js',\n  output: './output',\n  helpers: {\n    WebDriver: {\n      url: 'http://localhost',\n      browser: 'chrome'\n    }\n  },\n  include: {\n    I: './steps_file.js'\n  },\n  plugins: {\n    xrayImport: {\n        require: \"codeceptjs-xray-cloud-helper\",\n        enabled: true,\n        debug: false,\n        projectKey: process.env.JIRA_PROJECT_KEY ?? 'JIRAKEY',\n        testExecutionAssigneeUserId: process.env.JIRA_ASSIGNEE_ID ?? '604ba41b020eb0068634',\n        importToExistingTestExecution: false,\n        existingTestExecutionKey: '',\n        testExecutionPlanKey: process.env.JIRA_TEST_PLAN_KEY ?? '',\n        testExecutionVersion: '1.0',\n        testExecutionRevision: '1',\n        testExecutionEnvironments: ['QA'],\n        testExecutionSummary: 'Automated CodeceptJS Test Execution',\n        testExecutionDescription: 'Results from CI/CD pipeline run.',\n        testExecutionSendEvidenceOnFail: true,\n        testExecutionCustomFields: [{ id: '63c5731047c0ed24ee469f5b', value: 'local' }],\n        createNewJiraTest: true,\n        timeout: 120000,\n        xrayClientId: process.env.XRAY_CLIENT_ID ?? '74122128E033FD4efef42341E2B1DF70A6027BD799',\n        xraySecret: process.env.XRAY_CLIENT_SECRET ?? '28e15830390194549bazzea0ce461274eabb71119113096ba3d746'\n    }\n  }\n}\n","lang":"javascript","description":"This configuration snippet for `codecept.conf.js` demonstrates how to enable and configure the `codeceptjs-xray-cloud-helper` plugin. It sets up automatic reporting to XRAY Cloud, creating new Jira tests if needed, and handling authentication with environment variables for sensitive credentials."},"warnings":[{"fix":"Ensure your Jira and XRAY instances are cloud-based. For self-hosted solutions, seek alternative reporting tools.","message":"This helper is explicitly designed and tested for XRAY/JIRA Cloud versions only. It will not work with self-hosted Jira or XRAY Server instances.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use environment variables (e.g., `process.env.XRAY_CLIENT_ID`) for all API keys and secrets. Store these variables securely in your CI/CD pipeline or local environment.","message":"Sensitive API credentials (xrayClientId, xraySecret) should never be hardcoded directly in `codecept.conf.js` or any source code. Exposing these credentials can lead to unauthorized access to your Jira/XRAY instance.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Double-check `projectKey` against your Jira project ID. If `importToExistingTestExecution` is true, verify `existingTestExecutionKey` points to a valid, existing Test Execution in XRAY.","message":"The `projectKey` and `testExecutionKey` configurations are critical. Incorrect values will lead to API errors, preventing test results from being imported.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Increase the `timeout` value in the plugin configuration if you experience frequent timeouts during report submission. Monitor XRAY API performance and network conditions.","message":"The default `timeout` of 120 seconds (120000 ms) might be insufficient for large test suites or during periods of high XRAY API latency, leading to 'Request Timed Out' errors.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that your `xrayClientId` and `xraySecret` are correct and active in your Jira's XRAY Cloud integration settings. Ensure the associated API key has 'Create Test Execution' and 'Update Test Run' permissions for the target project.","cause":"The provided `xrayClientId` or `xraySecret` are incorrect, expired, or lack the necessary permissions to authenticate with the XRAY Cloud API.","error":"XRAY API Error: Invalid client id or secret (401 Unauthorized)"},{"fix":"Confirm the `projectKey` exactly matches an active Jira project key. Check that the XRAY API key has 'Browse Projects' permission for this project.","cause":"The `projectKey` configured in `codecept.conf.js` does not correspond to an existing Jira project, or the XRAY API key does not have access to it.","error":"Jira Project not found for key: JIRAKEY (404 Not Found)"},{"fix":"Verify that the `existingTestExecutionKey` is correct and refers to an active Test Execution in XRAY. Alternatively, set `importToExistingTestExecution` to `false` to allow the plugin to create a new Test Execution.","cause":"When `importToExistingTestExecution` is true, the `existingTestExecutionKey` points to a Test Execution that does not exist or has been deleted.","error":"Test Execution JIRAKEY-1118 not found (404 Not Found)"},{"fix":"Increase the `timeout` value in the plugin configuration (e.g., to `300000` for 5 minutes). Consider reducing the number of tests in a single execution or optimizing network conditions.","cause":"The XRAY Cloud API did not respond within the configured `timeout` period, possibly due to network latency, large payload size, or API rate limiting.","error":"Error: Request timed out after 120000ms"}],"ecosystem":"npm"}