@msalaam/xray-qe-toolkit 1.3.4 → 1.4.1

package/lib/xrayClient.js

@@ -1,17 +1,17 @@
 /**
  * @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:
+ * Consolidated API layer handling:
  *   • Xray Cloud authentication (JWT)
  *   • JIRA REST v3 issue CRUD
- *   • Xray GraphQL mutations (test type, steps)
- *   • Issue linking (Test ↔ Execution / Plan)
+ *   • Xray GraphQL — test management (tests, test plans, folders, test runs)
+ *   • Xray REST v2 — execution import (JSON, multipart), bulk test import, attachments
  *   • Exponential-backoff retry for Xray indexing race conditions
  */
 
 import axios from "axios";
 import https from "node:https";
+import FormData from "form-data";
 import logger from "./logger.js";
 
 // Shared HTTPS agent — rejectUnauthorized: false for corporate proxy compat
@@ -19,20 +19,10 @@ 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)}`,
@@ -40,11 +30,13 @@ function jiraHeaders(cfg) {
   };
 }
 
-/**
- * Convert a plain-text description to Atlassian Document Format (ADF).
- * @param {string} text
- * @returns {object} ADF document
- */
+function xrayHeaders(xrayToken) {
+  return {
+    Authorization: `Bearer ${xrayToken}`,
+    "Content-Type": "application/json",
+  };
+}
+
 export function toAdf(text) {
   return {
     type: "doc",
@@ -58,11 +50,6 @@ export function toAdf(text) {
   };
 }
 
-/**
- * Sleep for `ms` milliseconds.
- * @param {number} ms
- * @returns {Promise<void>}
- */
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -71,7 +58,6 @@ function sleep(ms) {
 
 /**
  * Authenticate with Xray Cloud and return a JWT bearer token.
- *
  * @param {object} cfg  Config from loadConfig()
  * @returns {Promise<string>} JWT token string
  */
@@ -90,10 +76,9 @@ export async function authenticate(cfg) {
 
 /**
  * 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, ... }
+ * @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) {
@@ -119,11 +104,9 @@ export async function createIssue(cfg, issueType, fields) {
 
 /**
  * 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>}
+ * @param {object} cfg
+ * @param {string} issueKey
+ * @param {object} fields
  */
 export async function updateIssue(cfg, issueKey, fields) {
   const update = {};
@@ -141,10 +124,9 @@ export async function updateIssue(cfg, issueKey, fields) {
 
 /**
  * Fetch a JIRA issue by key.
- *
  * @param {object} cfg
- * @param {string} issueKey  e.g. "APIEE-6933"
- * @returns {Promise<object>} Full issue payload
+ * @param {string} issueKey
+ * @returns {Promise<object>}
  */
 export async function getIssue(cfg, issueKey) {
   const response = await axios.get(
@@ -154,162 +136,537 @@ export async function getIssue(cfg, issueKey) {
   return response.data;
 }
 
-// ─── Xray GraphQL — Test type & steps ──────────────────────────────────────────
+// ─── Xray GraphQL — queries ────────────────────────────────────────────────────
 
 /**
- * Set a test issue's type to "Automated" via Xray GraphQL.
- *
+ * Execute a GraphQL operation against Xray Cloud.
  * @param {object} cfg
- * @param {string} xrayToken  JWT from authenticate()
- * @param {string} issueId    Numeric JIRA issue ID (NOT the key)
+ * @param {string} xrayToken
+ * @param {string} query     GraphQL query or mutation string
+ * @param {object} variables
+ * @returns {Promise<object>} data object
  */
-export async function setTestTypeAutomated(cfg, xrayToken, issueId) {
-  const headers = {
-    Authorization: `Bearer ${xrayToken}`,
-    "Content-Type": "application/json",
-  };
-
+async function graphql(cfg, xrayToken, query, variables = {}) {
   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 }
+    { query, variables },
+    { httpsAgent, headers: xrayHeaders(xrayToken) }
   );
 
   if (response.data.errors) {
     throw new Error(`GraphQL errors: ${JSON.stringify(response.data.errors)}`);
   }
+
+  return response.data.data;
 }
 
 /**
- * Add a single test step via Xray GraphQL.
- *
+ * Get a single test by issue ID.
  * @param {object} cfg
- * @param {string} xrayToken  JWT
- * @param {string} issueId    Numeric JIRA issue ID
- * @param {object} step       { action, data, expected_result }
+ * @param {string} xrayToken
+ * @param {string} issueId  Numeric JIRA issue ID
+ * @returns {Promise<object>}
  */
-export async function addTestStep(cfg, xrayToken, issueId, step) {
-  const headers = {
-    Authorization: `Bearer ${xrayToken}`,
-    "Content-Type": "application/json",
-  };
+export async function getTest(cfg, xrayToken, issueId) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($issueId: String!) {
+      getTest(issueId: $issueId) {
+        issueId
+        projectId
+        testType { name kind }
+        steps { id action data result }
+        status { name description }
+        testSets(limit: 10) { results { issueId } }
+        testPlans(limit: 10) { results { issueId } }
+        folder { path }
+      }
+    }
+  `, { issueId: String(issueId) });
+  return data.getTest;
+}
 
-  const response = await axios.post(
-    cfg.xrayGraphqlUrl,
-    {
-      query: `mutation ($issueId: String!, $step: CreateStepInput!) {
-        addTestStep(issueId: $issueId, step: $step) {
+/**
+ * Get tests in a project (paginated).
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {object} opts   { projectId, jql, limit (1-100), start }
+ * @returns {Promise<{total, results}>}
+ */
+export async function getTests(cfg, xrayToken, opts = {}) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($projectId: String, $jql: String, $limit: Int!, $start: Int) {
+      getTests(projectId: $projectId, jql: $jql, limit: $limit, start: $start) {
+        total
+        start
+        limit
+        results {
+          issueId
+          projectId
+          testType { name kind }
+          steps { id action data result }
+          folder { path }
+          status { name }
+        }
+      }
+    }
+  `, {
+    projectId: opts.projectId || null,
+    jql: opts.jql || null,
+    limit: Math.min(opts.limit || 100, 100),
+    start: opts.start || 0,
+  });
+  return data.getTests;
+}
+
+/**
+ * Get a Test Plan by issue ID (includes its tests).
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ * @returns {Promise<object>}
+ */
+export async function getTestPlan(cfg, xrayToken, issueId) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($issueId: String!) {
+      getTestPlan(issueId: $issueId) {
+        issueId
+        projectId
+        tests(limit: 100) {
+          total
+          results {
+            issueId
+            testType { name }
+            status { name }
+          }
+        }
+        testExecutions(limit: 10) {
+          results {
+            issueId
+          }
+        }
+      }
+    }
+  `, { issueId: String(issueId) });
+  return data.getTestPlan;
+}
+
+/**
+ * Get test plans in a project.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} projectId  JIRA project ID (numeric)
+ * @param {number} limit
+ * @returns {Promise<{total, results}>}
+ */
+export async function getTestPlans(cfg, xrayToken, projectId, limit = 50) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($projectId: String!, $limit: Int!) {
+      getTestPlans(projectId: $projectId, limit: $limit) {
+        total
+        results {
+          issueId
+          projectId
+        }
+      }
+    }
+  `, { projectId: String(projectId), limit });
+  return data.getTestPlans;
+}
+
+/**
+ * Get a test execution by issue ID (includes test runs).
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ * @returns {Promise<object>}
+ */
+export async function getTestExecution(cfg, xrayToken, issueId) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($issueId: String!) {
+      getTestExecution(issueId: $issueId) {
+        issueId
+        projectId
+        testRuns(limit: 100) {
+          total
+          results {
+            id
+            status { name }
+            test { issueId }
+            startedOn
+            finishedOn
+          }
+        }
+        testPlans(limit: 10) {
+          results { issueId }
+        }
+      }
+    }
+  `, { issueId: String(issueId) });
+  return data.getTestExecution;
+}
+
+/**
+ * Get test runs for a given test.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} testIssueId
+ * @param {number} limit
+ * @returns {Promise<{total, results}>}
+ */
+export async function getTestRuns(cfg, xrayToken, testIssueId, limit = 10) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($testIssueId: String!, $limit: Int!) {
+      getTestRuns(testIssueId: $testIssueId, limit: $limit) {
+        total
+        results {
           id
-          action
+          status { name color }
+          startedOn
+          finishedOn
+          testExecution { issueId }
         }
-      }`,
-      variables: {
-        issueId: String(issueId),
-        step: {
-          action: step.action,
-          data: step.data || "",
-          result: step.expected_result || "",
-        },
-      },
-    },
-    { httpsAgent, headers }
-  );
+      }
+    }
+  `, { testIssueId: String(testIssueId), limit });
+  return data.getTestRuns;
+}
 
-  if (response.data.errors) {
-    throw new Error(`GraphQL errors: ${JSON.stringify(response.data.errors)}`);
-  }
+/**
+ * Get folder by path within a project.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} projectId
+ * @param {string} folderPath  e.g. "/API/Auth"
+ * @returns {Promise<object|null>}
+ */
+export async function getFolder(cfg, xrayToken, projectId, folderPath) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($projectId: String!, $path: String!) {
+      getFolder(projectId: $projectId, path: $path) {
+        name
+        path
+        testsCount
+      }
+    }
+  `, { projectId: String(projectId), path: folderPath });
+  return data.getFolder;
+}
 
-  return response.data.data.addTestStep;
+/**
+ * Get project settings (statuses, test types, custom fields).
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} projectId
+ * @returns {Promise<object>}
+ */
+export async function getProjectSettings(cfg, xrayToken, projectId) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($projectId: String!) {
+      getProjectSettings(projectId: $projectId) {
+        testTypes { name kind }
+        testStepSettings {
+          fields { id name }
+        }
+      }
+    }
+  `, { projectId: String(projectId) });
+  return data.getProjectSettings;
 }
 
+// ─── Xray GraphQL — Test mutations ────────────────────────────────────────────
+
 /**
- * Remove all existing test steps via Xray GraphQL (for update/replace flow).
- *
+ * Set a test issue's type via Xray GraphQL.
  * @param {object} cfg
  * @param {string} xrayToken
  * @param {string} issueId
+ * @param {string} typeName  "Generic" | "Manual" | "Cucumber"
  */
-export async function removeAllTestSteps(cfg, xrayToken, issueId) {
-  const headers = {
-    Authorization: `Bearer ${xrayToken}`,
-    "Content-Type": "application/json",
-  };
+export async function setTestType(cfg, xrayToken, issueId, typeName = "Generic") {
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testType: UpdateTestTypeInput!) {
+      updateTestType(issueId: $issueId, testType: $testType) {
+        issueId
+        testType { name kind }
+      }
+    }
+  `, { issueId: String(issueId), testType: { name: typeName } });
+}
+
+/** @deprecated Use setTestType("Generic") */
+export async function setTestTypeAutomated(cfg, xrayToken, issueId) {
+  return setTestType(cfg, xrayToken, issueId, "Generic");
+}
 
-  // First, get existing steps
-  const getResponse = await axios.post(
+/**
+ * Add a single test step.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ * @param {object} step  { action, data, expected_result }
+ * @returns {Promise<object>}
+ */
+export async function addTestStep(cfg, xrayToken, issueId, step) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $step: CreateStepInput!) {
+      addTestStep(issueId: $issueId, step: $step) {
+        id
+        action
+      }
+    }
+  `, {
+    issueId: String(issueId),
+    step: {
+      action: step.action,
+      data: step.data || "",
+      result: step.expected_result || "",
+    },
+  });
+  return data.addTestStep;
+}
+
+/**
+ * Remove all existing test steps (for update/replace flow).
+ * Uses the removeAllTestSteps mutation directly — faster than looping.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ * @returns {Promise<number>} count of removed steps
+ */
+export async function removeAllTestSteps(cfg, xrayToken, issueId) {
+  // Get existing steps count first
+  const response = await axios.post(
     cfg.xrayGraphqlUrl,
     {
       query: `query ($issueId: String!) {
         getTest(issueId: $issueId) {
-          steps {
-            id
-          }
+          steps { id }
         }
       }`,
       variables: { issueId: String(issueId) },
     },
-    { httpsAgent, headers }
+    { httpsAgent, headers: xrayHeaders(xrayToken) }
   );
 
-  const steps = getResponse.data?.data?.getTest?.steps || [];
+  const steps = response.data?.data?.getTest?.steps || [];
+  if (steps.length === 0) return 0;
 
-  // 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 }
-    );
-  }
+  // Use removeAllTestSteps mutation (single call instead of N calls)
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!) {
+      removeAllTestSteps(issueId: $issueId)
+    }
+  `, { issueId: String(issueId) });
 
   return steps.length;
 }
 
+/**
+ * Update the unstructured (Generic) test definition.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ * @param {string} definition  Free-form test definition string
+ */
+export async function updateTestDefinition(cfg, xrayToken, issueId, definition) {
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $unstructured: String!) {
+      updateUnstructuredTestDefinition(issueId: $issueId, unstructured: $unstructured) {
+        issueId
+      }
+    }
+  `, { issueId: String(issueId), unstructured: definition });
+}
+
+/**
+ * Update test's folder in the Xray Test Repository.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} issueId
+ * @param {string} folderPath  e.g. "/API/Auth"
+ */
+export async function updateTestFolder(cfg, xrayToken, issueId, folderPath) {
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $folderPath: String!) {
+      updateTestFolder(issueId: $issueId, folderPath: $folderPath) {
+        warnings
+      }
+    }
+  `, { issueId: String(issueId), folderPath });
+}
+
+// ─── Xray GraphQL — Test Plan mutations ───────────────────────────────────────
+
+/**
+ * Create a new Test Plan issue via GraphQL.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {object} opts  { projectId, summary, description }
+ * @returns {Promise<{issueId: string, warnings: string[]}>}
+ */
+export async function createTestPlan(cfg, xrayToken, opts) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($projectId: String!, $summary: String!, $description: String) {
+      createTestPlan(projectId: $projectId, summary: $summary, description: $description) {
+        testPlan {
+          issueId
+          projectId
+        }
+        warnings
+      }
+    }
+  `, {
+    projectId: opts.projectId || cfg.jiraProjectKey,
+    summary: opts.summary,
+    description: opts.description || null,
+  });
+  return data.createTestPlan;
+}
+
+/**
+ * Add tests to a Test Plan.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   planIssueId
+ * @param {string[]} testIssueIds  Numeric JIRA issue IDs of test issues
+ * @returns {Promise<object>}
+ */
+export async function addTestsToTestPlan(cfg, xrayToken, planIssueId, testIssueIds) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testIssueIds: [String]!) {
+      addTestsToTestPlan(issueId: $issueId, testIssueIds: $testIssueIds) {
+        addedTests
+        warnings
+      }
+    }
+  `, {
+    issueId: String(planIssueId),
+    testIssueIds: testIssueIds.map(String),
+  });
+  return data.addTestsToTestPlan;
+}
+
+/**
+ * Remove tests from a Test Plan.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   planIssueId
+ * @param {string[]} testIssueIds
+ */
+export async function removeTestsFromTestPlan(cfg, xrayToken, planIssueId, testIssueIds) {
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testIssueIds: [String]!) {
+      removeTestsFromTestPlan(issueId: $issueId, testIssueIds: $testIssueIds) {
+        warnings
+      }
+    }
+  `, {
+    issueId: String(planIssueId),
+    testIssueIds: testIssueIds.map(String),
+  });
+}
+
+// ─── Xray GraphQL — Folder mutations ──────────────────────────────────────────
+
+/**
+ * Create a folder in the Xray Test Repository.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} projectId  JIRA project ID (numeric)
+ * @param {string} folderPath  Full path e.g. "/API/Auth"
+ * @returns {Promise<object>}
+ */
+export async function createFolder(cfg, xrayToken, projectId, folderPath) {
+  // Derive name and parent path
+  const parts = folderPath.split("/").filter(Boolean);
+  const name = parts[parts.length - 1];
+  const parentPath = "/" + parts.slice(0, -1).join("/");
+
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($projectId: String!, $path: String!) {
+      createFolder(projectId: $projectId, path: $path) {
+        folder { name path testsCount }
+        warnings
+      }
+    }
+  `, { projectId: String(projectId), path: folderPath });
+  return data.createFolder;
+}
+
+/**
+ * Move tests into a repository folder.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   projectId
+ * @param {string}   folderPath  e.g. "/API/Auth"
+ * @param {string[]} testIssueIds
+ * @returns {Promise<object>}
+ */
+export async function addTestsToFolder(cfg, xrayToken, projectId, folderPath, testIssueIds) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($projectId: String!, $path: String!, $testIssueIds: [String]!) {
+      addTestsToFolder(projectId: $projectId, path: $path, testIssueIds: $testIssueIds) {
+        folder { path testsCount }
+        warnings
+      }
+    }
+  `, {
+    projectId: String(projectId),
+    path: folderPath,
+    testIssueIds: testIssueIds.map(String),
+  });
+  return data.addTestsToFolder;
+}
+
+// ─── Xray GraphQL — Test Execution mutations ───────────────────────────────────
+
+/**
+ * Add test environments to an existing test execution.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   execIssueId   JIRA issue ID of execution (numeric)
+ * @param {string[]} environments  e.g. ["IOP-QA"]
+ */
+export async function addTestEnvironmentsToTestExecution(cfg, xrayToken, execIssueId, environments) {
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testEnvironments: [String]!) {
+      addTestEnvironmentsToTestExecution(issueId: $issueId, testEnvironments: $testEnvironments) {
+        addedTestEnvironments
+        warnings
+      }
+    }
+  `, {
+    issueId: String(execIssueId),
+    testEnvironments: environments,
+  });
+}
+
 // ─── Issue linking ─────────────────────────────────────────────────────────────
 
 /**
- * Link a test issue to a container (Test Execution or Test Plan) via JIRA issue links.
- *
+ * Link a test issue to a container 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
+ * @param {string} testKey       Inward issue key (Test)
+ * @param {string} containerKey  Outward issue key (Execution / Plan)
  */
 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,
+    {
+      type: { name: "Test" },
+      inwardIssue: { key: testKey },
+      outwardIssue: { key: containerKey },
+    },
     { 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
+ * @param {string}   containerKey
  * @returns {Promise<{linked: string[], failed: string[]}>}
  */
 export async function linkMultiple(cfg, testKeys, containerKey) {
@@ -329,20 +686,17 @@ export async function linkMultiple(cfg, testKeys, containerKey) {
   return { linked, failed };
 }
 
-// ─── Xray import endpoints ─────────────────────────────────────────────────────
+// ─── Xray REST v2 — Import execution results ───────────────────────────────────
 
 /**
- * Import JUnit/XUnit XML results into Xray Cloud.
- *
+ * Import JUnit/XUnit XML results.
  * @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>}
+ * @param {string} xrayToken
+ * @param {Buffer} xmlBuffer
+ * @param {string} [testExecKey]
  */
 export async function importResults(cfg, xrayToken, xmlBuffer, testExecKey) {
-  const url = "https://xray.cloud.getxray.app/api/v2/import/execution/junit";
-
+  const url = `${cfg.xrayRestUrl}/import/execution/junit`;
   const params = {};
   if (testExecKey) params.testExecKey = testExecKey;
   if (cfg.jiraProjectKey) params.projectKey = cfg.jiraProjectKey;
@@ -360,17 +714,15 @@ export async function importResults(cfg, xrayToken, xmlBuffer, testExecKey) {
 }
 
 /**
- * Import test results using Xray's native JSON format.
- * This format supports detailed test information including custom fields and evidence.
- *
+ * Import test results using Xray JSON format (single JSON body).
+ * Creates a new Test Execution automatically.
  * @param {object} cfg
- * @param {string} xrayToken JWT
- * @param {object} xrayJson  Xray JSON format object
+ * @param {string} xrayToken
+ * @param {object} xrayJson  Full Xray JSON payload (info + tests)
  * @returns {Promise<object>}
  */
 export async function importResultsXrayJson(cfg, xrayToken, xrayJson) {
-  const url = "https://xray.cloud.getxray.app/api/v2/import/execution";
-
+  const url = `${cfg.xrayRestUrl}/import/execution`;
   try {
     const response = await axios.post(url, xrayJson, {
       httpsAgent,
@@ -379,59 +731,175 @@ export async function importResultsXrayJson(cfg, xrayToken, xrayJson) {
         "Content-Type": "application/json",
       },
     });
+    return response.data;
+  } catch (error) {
+    _handleImportError(error);
+  }
+}
+
+/**
+ * Import test results using Xray JSON multipart format.
+ * Provides full control over Jira issue fields on the created Test Execution.
+ *
+ * @param {object}  cfg
+ * @param {string}  xrayToken
+ * @param {object}  xrayJson         Xray results JSON (info.testPlanKey etc. — note: 'info' in this part IS used by multipart)
+ * @param {object}  [jiraFieldsJson] Jira issue fields for the new Test Execution (optional)
+ * @returns {Promise<object>}
+ */
+export async function importResultsMultipart(cfg, xrayToken, xrayJson, jiraFieldsJson = null) {
+  const url = `${cfg.xrayRestUrl}/import/execution/multipart`;
+
+  const form = new FormData();
+  form.append("results", JSON.stringify(xrayJson), {
+    contentType: "application/json",
+    filename: "results.json",
+  });
+
+  if (jiraFieldsJson) {
+    form.append("info", JSON.stringify(jiraFieldsJson), {
+      contentType: "application/json",
+      filename: "info.json",
+    });
+  }
 
+  try {
+    const response = await axios.post(url, form, {
+      httpsAgent,
+      headers: {
+        Authorization: `Bearer ${xrayToken}`,
+        ...form.getHeaders(),
+      },
+    });
     return response.data;
   } catch (error) {
-    // Enhanced error reporting for Xray API issues
-    if (error.response) {
-      const status = error.response.status;
-      const data = error.response.data;
-      
-      let errorMsg = `Xray API returned ${status} error`;
-      
-      if (typeof data === 'string') {
-        errorMsg += `: ${data}`;
-      } else if (data?.error) {
-        errorMsg += `: ${data.error}`;
-      } else if (data?.message) {
-        errorMsg += `: ${data.message}`;
-      } else if (data) {
-        errorMsg += `: ${JSON.stringify(data)}`;
-      }
-      
-      logger.error(errorMsg);
-      
-      // Common issues help
-      if (status === 400) {
-        logger.warn('\n💡 Common causes of 400 errors:');
-        logger.warn('   • Missing test annotations in Playwright tests');
-        logger.warn('   • Invalid test key format (should be PROJ-123)');
-        logger.warn('   • Test execution key not found');
-        logger.warn('   • Malformed JSON structure');
-        logger.warn('   • Test keys reference non-existent tests\n');
-      }
-      
-      throw new Error(errorMsg);
+    _handleImportError(error);
+  }
+}
+
+// ─── Xray REST v2 — Bulk test import ──────────────────────────────────────────
+
+/**
+ * Import tests in bulk (async — returns a jobId).
+ * Max 1000 tests per call. Use checkImportJobStatus() to poll.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {object[]} tests  Array of Xray test import objects
+ * @returns {Promise<{jobId: string}>}
+ */
+export async function importTestsBulk(cfg, xrayToken, tests) {
+  const url = `${cfg.xrayRestUrl}/import/test/bulk`;
+
+  const response = await axios.post(url, tests, {
+    httpsAgent,
+    headers: {
+      Authorization: `Bearer ${xrayToken}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  return response.data; // { jobId: "..." }
+}
+
+/**
+ * Check the status of a bulk test import job.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} jobId
+ * @returns {Promise<{status: string, result?: object}>}
+ */
+export async function checkImportJobStatus(cfg, xrayToken, jobId) {
+  const url = `${cfg.xrayRestUrl}/import/test/bulk/${jobId}/status`;
+
+  const response = await axios.get(url, {
+    httpsAgent,
+    headers: { Authorization: `Bearer ${xrayToken}` },
+  });
+
+  return response.data;
+}
+
+/**
+ * Poll a bulk import job until complete or timeout.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} jobId
+ * @param {object} [opts]           { pollInterval: ms, timeout: ms }
+ * @returns {Promise<object>} Final job status result
+ */
+export async function waitForImportJob(cfg, xrayToken, jobId, opts = {}) {
+  const pollInterval = opts.pollInterval || 2000;
+  const timeout = opts.timeout || 60000;
+  const start = Date.now();
+
+  while (Date.now() - start < timeout) {
+    const status = await checkImportJobStatus(cfg, xrayToken, jobId);
+    if (status.status === "successful" || status.status === "failed") {
+      return status;
     }
-    
-    throw error;
+    await sleep(pollInterval);
   }
+
+  throw new Error(`Bulk import job ${jobId} timed out after ${timeout}ms`);
+}
+
+// ─── Xray REST v2 — Attachments ───────────────────────────────────────────────
+
+/**
+ * Upload an attachment to Xray.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {Buffer} fileBuffer
+ * @param {string} filename
+ * @param {string} [contentType]
+ * @returns {Promise<{id: string, filename: string}>}
+ */
+export async function addAttachment(cfg, xrayToken, fileBuffer, filename, contentType = "application/octet-stream") {
+  const url = `${cfg.xrayRestUrl}/attachments`;
+
+  const form = new FormData();
+  form.append("file", fileBuffer, { filename, contentType });
+
+  const response = await axios.post(url, form, {
+    httpsAgent,
+    headers: {
+      Authorization: `Bearer ${xrayToken}`,
+      ...form.getHeaders(),
+    },
+  });
+
+  return response.data;
+}
+
+/**
+ * Get an attachment by its ID.
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {string} attachmentId
+ * @returns {Promise<Buffer>}
+ */
+export async function getAttachment(cfg, xrayToken, attachmentId) {
+  const url = `${cfg.xrayRestUrl}/attachments/${attachmentId}`;
+
+  const response = await axios.get(url, {
+    httpsAgent,
+    responseType: "arraybuffer",
+    headers: { Authorization: `Bearer ${xrayToken}` },
+  });
+
+  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<*>}
+ * Retry with exponential backoff — handles Xray indexing delays.
+ * Backoff: 2s → 4s → 8s → 16s → 32s
+ * @param {Function} fn
+ * @param {object}   [opts]
+ * @param {number}   [opts.maxRetries=5]
+ * @param {number}   [opts.baseDelay=2000]
+ * @param {string}   [opts.retryOn]  Error substring to match for retry
  */
 export async function withRetry(fn, opts = {}) {
   const maxRetries = opts.maxRetries ?? 5;
@@ -451,19 +919,10 @@ export async function withRetry(fn, opts = {}) {
       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` +
+            `Xray user authentication mismatch.\n\n` +
+              `Ensure JIRA_EMAIL matches the Xray API Key owner.\n` +
               `Original error: ${msg}`
           );
         }
@@ -473,3 +932,121 @@ export async function withRetry(fn, opts = {}) {
   }
   throw lastError;
 }
+
+// ─── Internal error handler ────────────────────────────────────────────────────
+
+function _handleImportError(error) {
+  if (error.response) {
+    const status = error.response.status;
+    const data = error.response.data;
+
+    let errorMsg = `Xray API returned ${status} error`;
+    if (typeof data === "string") errorMsg += `: ${data}`;
+    else if (data?.error) errorMsg += `: ${data.error}`;
+    else if (data?.message) errorMsg += `: ${data.message}`;
+    else if (data) errorMsg += `: ${JSON.stringify(data)}`;
+
+    logger.error(errorMsg);
+
+    if (status === 400) {
+      logger.warn("Common causes: missing test annotations, invalid test key, malformed JSON structure.");
+    }
+
+    throw new Error(errorMsg);
+  }
+  throw error;
+}
+
+// ─── Xray GraphQL — Test Execution mutations (cont.) ──────────────────────────
+
+/**
+ * Add tests to an existing Test Execution by their Xray issue IDs.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   execIssueId   Numeric Xray issue ID of the Test Execution
+ * @param {string[]} testIssueIds  Numeric Xray issue IDs of the tests to add
+ */
+export async function addTestsToTestExecution(cfg, xrayToken, execIssueId, testIssueIds) {
+  const { data } = await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testIssueIds: [String]!) {
+      addTestsToTestExecution(issueId: $issueId, testIssueIds: $testIssueIds) {
+        addedTests
+        warnings
+      }
+    }
+  `, {
+    issueId: String(execIssueId),
+    testIssueIds: testIssueIds.map(String),
+  });
+  return data.addTestsToTestExecution;
+}
+
+// ─── High-level — Test Execution creation ─────────────────────────────────────
+
+/**
+ * Create a new Test Execution in JIRA and configure it for Xray.
+ *
+ * Steps:
+ *   1. Create the JIRA issue of type "Test Execution"
+ *   2. Apply environment labels via GraphQL mutation
+ *   3. If testIssueIds supplied, add those tests to the execution
+ *
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {object}   opts
+ * @param {string}   opts.summary         Execution title
+ * @param {string}   [opts.description]   Optional description
+ * @param {string[]} [opts.environments]  e.g. ["IOP-QA"]
+ * @param {string[]} [opts.testIssueIds]  Numeric Xray issue IDs to add
+ * @param {string}   [opts.testPlanKey]   If set, link execution to this plan
+ * @returns {Promise<{key: string, id: string}>}
+ */
+export async function createTestExecution(cfg, xrayToken, opts) {
+  const {
+    summary,
+    description,
+    environments = [],
+    testIssueIds = [],
+    testPlanKey,
+  } = opts;
+
+  // 1. Create JIRA issue
+  const issue = await createIssue(cfg, "Test Execution", {
+    summary: summary || `Test Execution — ${new Date().toLocaleString()}`,
+    description: description || summary || "",
+  });
+
+  logger.step(`Test Execution created: ${issue.key}`);
+
+  // 2. Add environment labels
+  if (environments.length > 0) {
+    try {
+      await addTestEnvironmentsToTestExecution(cfg, xrayToken, issue.id, environments);
+      logger.step(`Environments set: ${environments.join(", ")}`);
+    } catch (err) {
+      logger.warn(`Could not set environments: ${err.message}`);
+    }
+  }
+
+  // 3. Link to Test Plan if provided
+  if (testPlanKey) {
+    try {
+      await linkIssues(cfg, issue.key, testPlanKey);
+      logger.step(`Linked to Test Plan: ${testPlanKey}`);
+    } catch (err) {
+      logger.warn(`Could not link to Test Plan ${testPlanKey}: ${err.message}`);
+    }
+  }
+
+  // 4. Add specific tests
+  if (testIssueIds.length > 0) {
+    try {
+      await addTestsToTestExecution(cfg, xrayToken, issue.id, testIssueIds);
+      logger.step(`${testIssueIds.length} test(s) added to execution`);
+    } catch (err) {
+      logger.warn(`Could not add tests to execution: ${err.message}`);
+    }
+  }
+
+  return { key: issue.key, id: issue.id };
+}