CodeceptJS XRay Cloud Helper

Common errors

• XRAY API Error: Invalid client id or secret (401 Unauthorized)

  cause The provided `xrayClientId` or `xraySecret` are incorrect, expired, or lack the necessary permissions to authenticate with the XRAY Cloud API.
  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.

• Jira Project not found for key: JIRAKEY (404 Not Found)

  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.
  fix Confirm the `projectKey` exactly matches an active Jira project key. Check that the XRAY API key has 'Browse Projects' permission for this project.

• Test Execution JIRAKEY-1118 not found (404 Not Found)

  cause When `importToExistingTestExecution` is true, the `existingTestExecutionKey` points to a Test Execution that does not exist or has been deleted.
  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.

• Error: Request timed out after 120000ms

  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.
  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.

Warnings

• gotcha 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.
  Fix: Ensure your Jira and XRAY instances are cloud-based. For self-hosted solutions, seek alternative reporting tools.
• gotcha 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.
  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.
• gotcha The `projectKey` and `testExecutionKey` configurations are critical. Incorrect values will lead to API errors, preventing test results from being imported.
  Fix: Double-check `projectKey` against your Jira project ID. If `importToExistingTestExecution` is true, verify `existingTestExecutionKey` points to a valid, existing Test Execution in XRAY.
• gotcha 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.
  Fix: Increase the `timeout` value in the plugin configuration if you experience frequent timeouts during report submission. Monitor XRAY API performance and network conditions.

Install

• npm install codeceptjs-xray-cloud-helper npm
• yarn add codeceptjs-xray-cloud-helper yarn
• pnpm add codeceptjs-xray-cloud-helper pnpm

Imports

• plugin configuration
  wrong:

  import { XrayCloudHelper } from 'codeceptjs-xray-cloud-helper';

  correct:

  plugins: {
      xrayImport: {
          require: "codeceptjs-xray-cloud-helper",
          enabled: true,
          // ... other config
      }
  }

  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.
• CLI initializer
  wrong:

  node node_modules/codeceptjs-xray-cloud-helper/cli.js init

  correct:

  npx xray-import init

  The package provides a convenient CLI tool via `npx` for interactive configuration setup, which simplifies initial manual configuration.

Quickstart

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.

const { set</td>

exports.config = {
  tests: './*_test.js',
  output: './output',
  helpers: {
    WebDriver: {
      url: 'http://localhost',
      browser: 'chrome'
    }
  },
  include: {
    I: './steps_file.js'
  },
  plugins: {
    xrayImport: {
        require: "codeceptjs-xray-cloud-helper",
        enabled: true,
        debug: false,
        projectKey: process.env.JIRA_PROJECT_KEY ?? 'JIRAKEY',
        testExecutionAssigneeUserId: process.env.JIRA_ASSIGNEE_ID ?? '604ba41b020eb0068634',
        importToExistingTestExecution: false,
        existingTestExecutionKey: '',
        testExecutionPlanKey: process.env.JIRA_TEST_PLAN_KEY ?? '',
        testExecutionVersion: '1.0',
        testExecutionRevision: '1',
        testExecutionEnvironments: ['QA'],
        testExecutionSummary: 'Automated CodeceptJS Test Execution',
        testExecutionDescription: 'Results from CI/CD pipeline run.',
        testExecutionSendEvidenceOnFail: true,
        testExecutionCustomFields: [{ id: '63c5731047c0ed24ee469f5b', value: 'local' }],
        createNewJiraTest: true,
        timeout: 120000,
        xrayClientId: process.env.XRAY_CLIENT_ID ?? '74122128E033FD4efef42341E2B1DF70A6027BD799',
        xraySecret: process.env.XRAY_CLIENT_SECRET ?? '28e15830390194549bazzea0ce461274eabb71119113096ba3d746'
    }
  }
}