Xray Async Client

Node.js client library for requesting Xray test executions, forwarding async execution updates to the backend queue API, and attaching evidence to Jira through the backend service.

This package is intended for test frameworks, automation runners, and other Node.js services. It is not a browser package because it uses Node APIs such as fs, path, process, and Buffer.

Install

npm install xray-async-helper-integration

For local development from this repository:

cd client
npm ci
npm run build

What It Does

• Requests the backend Queue API to create or reuse an Xray test execution by summary.
• Sends step-based execution updates to the backend queue API.
• Lets the backend services enqueue and process the work asynchronously.
• Optionally asks the backend Queue API to upload attachments to the Jira test execution.

Exports

• createOrGetTestExecution
• executeTestRun
• addAttachmentToJiraTestExecution
• uploadReportResult
• XrayQueueApiError
• closeQueue (kept as a no-op for backward compatibility)
• TStatus
• exported TypeScript types from src/types

Environment Variables

Required for backend Queue API calls:

XRAY_PROJECTKEY=<jira-project-key>
XRAY_TESTSETSUMMARY=<xray-test-set-summary>
XRAY_QUEUE_API_URL=<http://your-backend-host:9100>

The client also accepts XRAY_PROJECT_KEY and XRAY_TESTSET_SUMMARY as aliases for the project key and test set summary. Environment variables are read when each exported method is called, so dotenv or CI setup can run before invoking the client methods.

Optional backend queue API settings:

XRAY_QUEUE_API_TOKEN=<shared-api-token>
XRAY_QUEUE_API_TIMEOUT_MS=10000

Optional report upload settings:

CI=true
XRAY_INTEGRATION=true
REPORT_DIR=<path-to-report-directory>

When CI is not true, the exported Xray methods skip remote API work. This keeps local runs from creating or updating Jira/Xray records.

Usage

Create or fetch a test execution first:

import { createOrGetTestExecution } from "xray-async-helper-integration";

const execution = await createOrGetTestExecution({
  summary: "Smoke Suite - 2026-04-09",
});

console.log(execution.key);
console.log(execution.reportLink);

Queue a two-step test run:

import { executeTestRun, TStatus } from "xray-async-helper-integration";

await executeTestRun({
  testExecutionKey: execution.key,
  summary: "Login test",
  stepId: 1,
  status: TStatus.EXECUTING,
  startTime: new Date().toISOString(),
});

await executeTestRun({
  testExecutionKey: execution.key,
  summary: "Login test",
  stepId: 2,
  status: TStatus.PASS,
  startTime: new Date(Date.now() - 5000).toISOString(),
  endTime: new Date().toISOString(),
  comment: "Completed successfully",
});

Attach a report file:

import { addAttachmentToJiraTestExecution } from "xray-async-helper-integration";
import fs from "fs";

const report = fs.readFileSync("./report.html");

await addAttachmentToJiraTestExecution({
  file: report,
  filename: "report.html",
});

Upload a report directory as a zip attachment:

import { uploadReportResult } from "xray-async-helper-integration";

await uploadReportResult();

Or run the packaged CLI after your tests finish:

npx xray-upload-result

The CLI reads from process.env; it does not load .env files by itself. In CI, configure these variables in your pipeline. For local npm scripts, inject the variables before running the CLI. For example:

{
  "scripts": {
    "posttest": "xray-upload-result"
  }
}

With Node's built-in env-file support:

{
  "scripts": {
    "posttest": "node --env-file=.env ./node_modules/xray-async-helper-integration/lib/bin/xray-upload-result.js"
  }
}

Or with a project-level dotenv runner:

{
  "scripts": {
    "posttest": "dotenv -e .env -- xray-upload-result"
  }
}

How It Works With The Backend

The client sends execution creation, execution events, and attachment uploads to the backend queue API. That backend service owns all Xray/Jira API credentials and calls.

The client calls these backend routes under XRAY_QUEUE_API_URL:

POST /api/v1/test-executions
POST /api/v1/test-runs
POST /api/v1/test-executions/:testExecutionKey/attachments

Error Handling

Backend, network, timeout, and validation failures are thrown as XrayQueueApiError. The error message is written for automation logs, and the instance also includes useful metadata:

import { XrayQueueApiError } from "xray-async-helper-integration";

try {
  await executeTestRun({
    testExecutionKey: "DEMO-123",
    summary: "Login test",
    stepId: 2,
    status: "PASSED",
  });
} catch (error) {
  if (error instanceof XrayQueueApiError) {
    console.error(error.message);
    console.error({
      status: error.status,
      code: error.code,
      backendCode: error.backendCode,
      requestId: error.requestId,
      url: error.url,
    });
    throw error;
  }

  throw error;
}

Common causes are called out directly:

• HTTP 400: missing or invalid payload fields.
• HTTP 401/403: XRAY_QUEUE_API_TOKEN mismatch.
• HTTP 404: wrong XRAY_QUEUE_API_URL or a non-Queue-API service.
• timeout or network error: backend not reachable from the automation runner.

For test-run events, the backend service publishes BullMQ jobs to the JiraQueue queue, and the backend worker consumes those jobs, resolves Xray test cases, and imports the final execution result into Xray Cloud.

The client no longer needs direct Redis, Xray, or Jira API access. It only needs network access to the backend queue API.

For safer parallel execution, pass testExecutionKey into executeTestRun(). If it is omitted, the client falls back to the legacy xrayconfig.json behavior for backward compatibility.

Playwright Integration

This package no longer opens a queue connection locally. closeQueue() is kept only so older test hooks do not break, but it does nothing now.

If your Playwright or framework setup still calls it in teardown, that is safe:

import { closeQueue } from "xray-async-helper-integration";

export default async function globalTeardown() {
  await closeQueue();
}

Or from a shared test hook:

import { test } from "@playwright/test";
import { closeQueue } from "xray-async-helper-integration";

test.afterAll(async () => {
  await closeQueue();
});

Build And Publish

npm run build
npm pack

Before publishing to npm, verify the package contents:

npm publish --dry-run

Then publish:

npm publish