@msalaam/xray-qe-toolkit 1.1.0

package/lib/xrayClient.js

@@ -0,0 +1,416 @@
+/**
+ * @msalaam/xray-qe-toolkit — Xray + JIRA API Client
+ *
+ * Consolidated API layer that replaces the duplicated code from the original
+ * index.js and scripts/linkTests.js.  Handles:
+ *   • Xray Cloud authentication (JWT)
+ *   • JIRA REST v3 issue CRUD
+ *   • Xray GraphQL mutations (test type, steps)
+ *   • Issue linking (Test ↔ Execution / Plan)
+ *   • Exponential-backoff retry for Xray indexing race conditions
+ */
+
+import axios from "axios";
+import https from "node:https";
+import logger from "./logger.js";
+
+// Shared HTTPS agent — rejectUnauthorized: false for corporate proxy compat
+const httpsAgent = new https.Agent({ rejectUnauthorized: false });
+
+// ─── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Build the Basic Auth header value for JIRA REST calls.
+ * @param {object} cfg Config from loadConfig()
+ * @returns {string}
+ */
+function jiraAuth(cfg) {
+  return Buffer.from(`${cfg.jiraEmail}:${cfg.jiraApiToken}`).toString("base64");
+}
+
+/**
+ * Standard JIRA REST headers.
+ * @param {object} cfg
+ * @returns {object}
+ */
+function jiraHeaders(cfg) {
+  return {
+    Authorization: `Basic ${jiraAuth(cfg)}`,
+    "Content-Type": "application/json",
+  };
+}
+
+/**
+ * Convert a plain-text description to Atlassian Document Format (ADF).
+ * @param {string} text
+ * @returns {object} ADF document
+ */
+export function toAdf(text) {
+  return {
+    type: "doc",
+    version: 1,
+    content: [
+      {
+        type: "paragraph",
+        content: [{ type: "text", text: text || "" }],
+      },
+    ],
+  };
+}
+
+/**
+ * Sleep for `ms` milliseconds.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Xray Cloud Authentication ─────────────────────────────────────────────────
+
+/**
+ * Authenticate with Xray Cloud and return a JWT bearer token.
+ *
+ * @param {object} cfg  Config from loadConfig()
+ * @returns {Promise<string>} JWT token string
+ */
+export async function authenticate(cfg) {
+  logger.auth("Authenticating with Xray Cloud...");
+  const response = await axios.post(
+    cfg.xrayAuthUrl,
+    { client_id: cfg.xrayId, client_secret: cfg.xraySecret },
+    { httpsAgent }
+  );
+  logger.success("Authenticated with Xray Cloud");
+  return response.data; // JWT string
+}
+
+// ─── JIRA REST v3 — Issue operations ───────────────────────────────────────────
+
+/**
+ * Create a JIRA issue (generic).
+ *
+ * @param {object}  cfg          Config
+ * @param {string}  issueType    e.g. "Test", "Test Execution", "Test Plan"
+ * @param {object}  fields       { summary, description, priority, labels, ... }
+ * @returns {Promise<{key: string, id: string}>}
+ */
+export async function createIssue(cfg, issueType, fields) {
+  const payload = {
+    fields: {
+      project: { key: cfg.jiraProjectKey },
+      summary: fields.summary,
+      description: toAdf(fields.description || fields.summary),
+      issuetype: { name: issueType },
+      ...(fields.priority ? { priority: { name: fields.priority } } : {}),
+      ...(fields.labels && fields.labels.length > 0 ? { labels: fields.labels } : {}),
+    },
+  };
+
+  const response = await axios.post(
+    `${cfg.jiraUrl}/rest/api/3/issue`,
+    payload,
+    { httpsAgent, headers: jiraHeaders(cfg) }
+  );
+
+  return { key: response.data.key, id: response.data.id };
+}
+
+/**
+ * Update an existing JIRA issue's fields.
+ *
+ * @param {object}  cfg      Config
+ * @param {string}  issueKey e.g. "APIEE-6933"
+ * @param {object}  fields   Fields to update { summary, description, priority, labels }
+ * @returns {Promise<void>}
+ */
+export async function updateIssue(cfg, issueKey, fields) {
+  const update = {};
+  if (fields.summary) update.summary = fields.summary;
+  if (fields.description) update.description = toAdf(fields.description);
+  if (fields.priority) update.priority = { name: fields.priority };
+  if (fields.labels) update.labels = fields.labels;
+
+  await axios.put(
+    `${cfg.jiraUrl}/rest/api/3/issue/${issueKey}`,
+    { fields: update },
+    { httpsAgent, headers: jiraHeaders(cfg) }
+  );
+}
+
+/**
+ * Fetch a JIRA issue by key.
+ *
+ * @param {object} cfg
+ * @param {string} issueKey  e.g. "APIEE-6933"
+ * @returns {Promise<object>} Full issue payload
+ */
+export async function getIssue(cfg, issueKey) {
+  const response = await axios.get(
+    `${cfg.jiraUrl}/rest/api/3/issue/${issueKey}`,
+    { httpsAgent, headers: jiraHeaders(cfg) }
+  );
+  return response.data;
+}
+
+// ─── Xray GraphQL — Test type & steps ──────────────────────────────────────────
+
+/**
+ * Set a test issue's type to "Automated" via Xray GraphQL.
+ *
+ * @param {object} cfg
+ * @param {string} xrayToken  JWT from authenticate()
+ * @param {string} issueId    Numeric JIRA issue ID (NOT the key)
+ */
+export async function setTestTypeAutomated(cfg, xrayToken, issueId) {
+  const headers = {
+    Authorization: `Bearer ${xrayToken}`,
+    "Content-Type": "application/json",
+  };
+
+  const response = await axios.post(
+    cfg.xrayGraphqlUrl,
+    {
+      query: `mutation ($issueId: String!, $testType: UpdateTestTypeInput!) {
+        updateTestType(issueId: $issueId, testType: $testType) {
+          issueId
+          testType { name kind }
+        }
+      }`,
+      variables: { issueId: String(issueId), testType: { name: "Automated" } },
+    },
+    { httpsAgent, headers }
+  );
+
+  if (response.data.errors) {
+    throw new Error(`GraphQL errors: ${JSON.stringify(response.data.errors)}`);
+  }
+}
+
+/**
+ * Add a single test step via Xray GraphQL.
+ *
+ * @param {object} cfg
+ * @param {string} xrayToken  JWT
+ * @param {string} issueId    Numeric JIRA issue ID
+ * @param {object} step       { action, data, expected_result }
+ */
+export async function addTestStep(cfg, xrayToken, issueId, step) {
+  const headers = {
+    Authorization: `Bearer ${xrayToken}`,
+    "Content-Type": "application/json",
+  };
+
+  const response = await axios.post(
+    cfg.xrayGraphqlUrl,
+    {
+      query: `mutation ($issueId: String!, $step: CreateStepInput!) {
+        addTestStep(issueId: $issueId, step: $step) {
+          id
+          action
+        }
+      }`,
+      variables: {
+        issueId: String(issueId),
+        step: {
+          action: step.action,
+          data: step.data || "",
+          result: step.expected_result || "",
+        },
+      },
+    },
+    { httpsAgent, headers }
+  );
+
+  if (response.data.errors) {
+    throw new Error(`GraphQL errors: ${JSON.stringify(response.data.errors)}`);
+  }
+
+  return response.data.data.addTestStep;
+}
+
+/**
+ * Remove all existing test steps via Xray GraphQL (for update/replace flow).
+ *
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ */
+export async function removeAllTestSteps(cfg, xrayToken, issueId) {
+  const headers = {
+    Authorization: `Bearer ${xrayToken}`,
+    "Content-Type": "application/json",
+  };
+
+  // First, get existing steps
+  const getResponse = await axios.post(
+    cfg.xrayGraphqlUrl,
+    {
+      query: `query ($issueId: String!) {
+        getTest(issueId: $issueId) {
+          steps {
+            id
+          }
+        }
+      }`,
+      variables: { issueId: String(issueId) },
+    },
+    { httpsAgent, headers }
+  );
+
+  const steps = getResponse.data?.data?.getTest?.steps || [];
+
+  // Remove each step
+  for (const step of steps) {
+    await axios.post(
+      cfg.xrayGraphqlUrl,
+      {
+        query: `mutation ($issueId: String!, $stepId: String!) {
+          removeTestStep(issueId: $issueId, stepId: $stepId)
+        }`,
+        variables: { issueId: String(issueId), stepId: String(step.id) },
+      },
+      { httpsAgent, headers }
+    );
+  }
+
+  return steps.length;
+}
+
+// ─── Issue linking ─────────────────────────────────────────────────────────────
+
+/**
+ * Link a test issue to a container (Test Execution or Test Plan) via JIRA issue links.
+ *
+ * @param {object} cfg
+ * @param {string} testKey          Inward issue key (Test)
+ * @param {string} containerKey     Outward issue key (Execution / Plan)
+ * @returns {Promise<boolean>} true if linked successfully
+ */
+export async function linkIssues(cfg, testKey, containerKey) {
+  const payload = {
+    type: { name: "Test" },
+    inwardIssue: { key: testKey },
+    outwardIssue: { key: containerKey },
+  };
+
+  await axios.post(
+    `${cfg.jiraUrl}/rest/api/3/issueLink`,
+    payload,
+    { httpsAgent, headers: jiraHeaders(cfg) }
+  );
+
+  return true;
+}
+
+/**
+ * Link multiple test keys to a container key.
+ *
+ * @param {object}   cfg
+ * @param {string[]} testKeys
+ * @param {string}   containerKey   Test Execution or Test Plan key
+ * @returns {Promise<{linked: string[], failed: string[]}>}
+ */
+export async function linkMultiple(cfg, testKeys, containerKey) {
+  const linked = [];
+  const failed = [];
+
+  for (const testKey of testKeys) {
+    try {
+      await linkIssues(cfg, testKey, containerKey);
+      linked.push(testKey);
+    } catch (err) {
+      logger.warn(`Failed to link ${testKey}: ${err.response?.data?.errorMessages?.[0] || err.message}`);
+      failed.push(testKey);
+    }
+  }
+
+  return { linked, failed };
+}
+
+// ─── Xray import endpoint ──────────────────────────────────────────────────────
+
+/**
+ * Import JUnit/XUnit XML results into Xray Cloud.
+ *
+ * @param {object} cfg
+ * @param {string} xrayToken   JWT
+ * @param {Buffer} xmlBuffer   Raw XML file content
+ * @param {string} testExecKey Test Execution key to associate results with
+ * @returns {Promise<object>}
+ */
+export async function importResults(cfg, xrayToken, xmlBuffer, testExecKey) {
+  const url = "https://xray.cloud.getxray.app/api/v2/import/execution/junit";
+
+  const params = {};
+  if (testExecKey) params.testExecKey = testExecKey;
+  if (cfg.jiraProjectKey) params.projectKey = cfg.jiraProjectKey;
+
+  const response = await axios.post(url, xmlBuffer, {
+    httpsAgent,
+    headers: {
+      Authorization: `Bearer ${xrayToken}`,
+      "Content-Type": "application/xml",
+    },
+    params,
+  });
+
+  return response.data;
+}
+
+// ─── Retry wrapper ─────────────────────────────────────────────────────────────
+
+/**
+ * Retry an async function with exponential backoff.
+ * Used to handle the Xray GraphQL indexing delay after new issue creation.
+ *
+ * Backoff sequence: 2s → 4s → 8s → 16s → 32s  (baseDelay × 2^attempt)
+ *
+ * @param {Function} fn           Async function to retry
+ * @param {object}   [opts]       Options
+ * @param {number}   [opts.maxRetries=5]   Max attempts
+ * @param {number}   [opts.baseDelay=2000] Base delay in ms
+ * @param {string}   [opts.retryOn]        Error substring to match for retry
+ * @returns {Promise<*>}
+ */
+export async function withRetry(fn, opts = {}) {
+  const maxRetries = opts.maxRetries ?? 5;
+  const baseDelay = opts.baseDelay ?? 2000;
+  const retryOn = opts.retryOn ?? "issueId provided is not valid";
+
+  let lastError;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const delay = baseDelay * Math.pow(2, attempt);
+      if (attempt > 0) {
+        logger.wait(`Retry ${attempt}/${maxRetries - 1} after ${delay}ms...`);
+      }
+      await sleep(delay);
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      const msg = err.message || "";
+      if (!msg.includes(retryOn)) {
+        // Non-retryable error — detect impersonation issues
+        if (msg.includes("disallowed to impersonate") || msg.includes("no valid active user exists")) {
+          throw new Error(
+            `Xray user authentication mismatch detected.\n\n` +
+              `This error occurs when:\n` +
+              `1. Your JIRA_EMAIL doesn't match the Xray API Key owner\n` +
+              `2. The user doesn't have an active Xray license\n` +
+              `3. The Xray API Key was created by a different user\n\n` +
+              `Solutions:\n` +
+              `- Ensure JIRA_EMAIL matches the Xray API Key owner's email\n` +
+              `- Verify you have an active Xray license assigned\n` +
+              `- Regenerate Xray API Key with the same user as JIRA_API_TOKEN\n` +
+              `- Contact your Xray administrator\n\n` +
+              `Original error: ${msg}`
+          );
+        }
+        throw err;
+      }
+    }
+  }
+  throw lastError;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@msalaam/xray-qe-toolkit",
+  "version": "1.1.0",
+  "description": "Full QE workflow toolkit for Xray Cloud integration — test management, Postman generation, CI pipeline scaffolding, and browser-based review gates for API regression projects.",
+  "type": "module",
+  "bin": {
+    "xqt": "./bin/cli.js"
+  },
+  "main": "lib/index.js",
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --test tests/",
+    "lint": "echo \"No linter configured\" && exit 0"
+  },
+  "keywords": [
+    "xray",
+    "jira",
+    "testing",
+    "automation",
+    "test-management",
+    "ci-cd",
+    "quality-assurance",
+    "xray-cloud",
+    "test-automation",
+    "jira-integration",
+    "postman",
+    "newman",
+    "qe-toolkit",
+    "regression"
+  ],
+  "author": "@Muhaymien96 <muhaymien96@gmail.com>",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "axios": "^1.13.4",
+    "commander": "^13.1.0",
+    "dotenv": "^17.2.3",
+    "express": "^5.1.0",
+    "open": "^10.1.2"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=8.0.0"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "lib/",
+    "ui/",
+    "templates/",
+    "schema/",
+    "README.md",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/schema/tests.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oldmutual.com/schemas/xray-qe-toolkit/tests.json",
+  "title": "XQT Test Configuration",
+  "description": "Schema for @msalaam/xray-qe-toolkit tests.json files. Defines test cases to push to Xray Cloud.",
+  "type": "object",
+  "required": ["tests"],
+  "properties": {
+    "testExecution": {
+      "type": "object",
+      "description": "Configuration for the Test Execution issue created in JIRA.",
+      "required": ["summary"],
+      "properties": {
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Summary/title for the Test Execution issue."
+        },
+        "description": {
+          "type": "string",
+          "description": "Description for the Test Execution issue."
+        }
+      }
+    },
+    "tests": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Array of test case definitions.",
+      "items": {
+        "type": "object",
+        "required": ["test_id", "xray"],
+        "properties": {
+          "test_id": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9_\\-]+$",
+            "description": "Unique internal test identifier. Used as the key in xray-mapping.json. Must be alphanumeric with hyphens/underscores."
+          },
+          "skip": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, this test will be excluded from push-tests."
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["regression", "smoke", "edge", "critical", "integration", "e2e", "security", "performance"]
+            },
+            "description": "QE-assigned tags for categorisation. Set via edit-json UI."
+          },
+          "type": {
+            "type": "string",
+            "enum": ["api", "ui", "e2e"],
+            "default": "api",
+            "description": "Test type: 'api' for API tests (Postman), 'ui' for UI tests (Playwright), 'e2e' for end-to-end. Determines which generator applies."
+          },
+          "xray": {
+            "type": "object",
+            "required": ["summary"],
+            "description": "Xray/JIRA test case fields.",
+            "properties": {
+              "summary": {
+                "type": "string",
+                "minLength": 1,
+                "description": "JIRA issue summary (title) for the test."
+              },
+              "description": {
+                "type": "string",
+                "description": "JIRA issue description."
+              },
+              "priority": {
+                "type": "string",
+                "enum": ["Highest", "High", "Medium", "Low", "Lowest"],
+                "description": "JIRA priority level."
+              },
+              "labels": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "JIRA labels for the test issue."
+              },
+              "steps": {
+                "type": "array",
+                "description": "Ordered test steps.",
+                "items": {
+                  "type": "object",
+                  "required": ["action", "expected_result"],
+                  "properties": {
+                    "action": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "What action to perform."
+                    },
+                    "data": {
+                      "type": "string",
+                      "description": "Input data or parameters for the step."
+                    },
+                    "expected_result": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Expected outcome of the step."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}