@msalaam/xray-qe-toolkit 1.5.0 → 1.6.1

package/lib/testCaseBuilder.js

@@ -18,10 +18,16 @@ import {
   removeAllTestSteps,
   updateTestDefinition,
   addTestsToTestPlan,
+  removeTestsFromTestPlan,
+  getTestPlan,
   createTestSet,
   addTestsToTestSet,
+  addPreconditionsToTest,
   createFolder,
   addTestsToFolder,
+  importTestsBulk,
+  waitForImportJob,
+  searchIssues,
   withRetry,
 } from "./xrayClient.js";
 
@@ -60,8 +66,10 @@ export function saveMapping(mappingPath, mapping) {
  * Flow per test:
  *  1. If test_id exists in mapping → update JIRA issue + replace steps
  *  2. If test_id is new → create JIRA Test issue, set type (Generic/Manual), add steps
- *  3. Save mapping after each test (crash-safe)
- *  4. 300ms rate-limit delay between tests
+ *  3. When new-test count ≥ cfg.bulkImportThreshold, new tests are created via bulk REST API
+ *  4. After create/update, link any preconditions defined on the test
+ *  5. Save mapping after each test (crash-safe)
+ *  6. 300ms rate-limit delay between serial tests
  *
  * @param {object}   cfg        Config from loadConfig()
  * @param {object[]} tests      Array of test definitions from tests.json
@@ -69,109 +77,237 @@ export function saveMapping(mappingPath, mapping) {
  * @param {string}   xrayToken  JWT token (pass to avoid re-authenticating)
  * @returns {Promise<{created: string[], updated: string[], failed: string[]}>}
  */
-export async function buildAndPush(cfg, tests, mapping, xrayToken) {
+export async function buildAndPush(cfg, tests, mapping, xrayToken, opts = {}) {
   const created = [];
   const updated = [];
   const failed = [];
 
-  for (const test of tests) {
-    try {
-      const existing = mapping[test.test_id];
-      const testType = test.xray?.testType || "Generic";
-      // Merge tags into labels (deduped)
-      const labels = [...new Set([
-        ...(test.xray?.labels || []),
-        ...(test.tags || []),
-      ])];
+  const toCreate = tests.filter((t) => !mapping[t.test_id]);
+  const toUpdate = tests.filter((t) => mapping[t.test_id]);
+
+  const threshold = cfg.bulkImportThreshold ?? 50;
+  const useBulk = opts.forceBulk ? toCreate.length > 0 : toCreate.length >= threshold;
+
+  // ── Bulk create path ───────────────────────────────────────────────────────
+  if (useBulk) {
+    logger.send(`Bulk creating ${toCreate.length} new test(s) via Xray REST${opts.forceBulk ? " (--bulk)" : ""}...`);
 
-      if (existing) {
-        // ── Update existing test ──────────────────────────────
-        logger.send(`${test.test_id} (update → ${existing.key})`);
+    const bulkPayload = toCreate.map((test) => {
+      const testType = test.xray?.testType || "Generic";
+      const labels = [...new Set([...(test.xray?.labels || []), ...(test.tags || [])])];
 
-        await updateIssue(cfg, existing.key, {
+      const obj = {
+        fields: {
+          project: { key: cfg.jiraProjectKey },
           summary: test.xray.summary,
-          description: test.xray.description,
-          priority: test.xray.priority,
-          labels,
+          issuetype: { name: "Test" },
+          ...(test.xray.description ? { description: test.xray.description } : {}),
+          ...(test.xray.priority ? { priority: { name: test.xray.priority } } : {}),
+          ...(labels.length > 0 ? { labels } : {}),
+        },
+        testtype: testType,
+      };
+
+      if (testType === "Generic" && test.xray?.definition) {
+        obj.unstructured = test.xray.definition;
+      } else if (testType === "Manual" && test.xray?.steps?.length > 0) {
+        obj.steps = test.xray.steps.map((s) => ({
+          action: s.action,
+          data: s.data || "",
+          result: s.expected_result || "",
+        }));
+      }
+
+      return obj;
+    });
+
+    try {
+      const { jobId } = await importTestsBulk(cfg, xrayToken, bulkPayload);
+      logger.step(`Bulk job started: ${jobId} — polling...`);
+
+      const jobResult = await waitForImportJob(cfg, xrayToken, jobId, { timeout: 120000 });
+
+      if (jobResult.status === "successful") {
+        const createdIssues = jobResult.result?.updatedOrCreatedTests || [];
+
+        createdIssues.forEach((issue, idx) => {
+          const test = toCreate[idx];
+          if (!test) return;
+          mapping[test.test_id] = { key: issue.key, id: String(issue.id) };
+          created.push(issue.key);
+          logger.step(`${test.test_id} → ${issue.key}`);
         });
-        logger.step("Fields updated");
-
-        // Replace steps for Manual tests
-        if (testType === "Manual" && test.xray.steps && test.xray.steps.length > 0) {
-          await withRetry(
-            async () => {
-              const removed = await removeAllTestSteps(cfg, xrayToken, existing.id);
-              logger.debug(`Removed ${removed} existing step(s)`);
-
-              for (const step of test.xray.steps) {
-                await addTestStep(cfg, xrayToken, existing.id, step);
-              }
-            },
-            { retryOn: "issueId provided is not valid" }
-          );
-          logger.step(`${test.xray.steps.length} step(s) replaced`);
-        }
 
-        // Update Generic definition
-        if (testType === "Generic" && test.xray?.definition) {
-          await withRetry(
-            async () => updateTestDefinition(cfg, xrayToken, existing.id, test.xray.definition),
-            { retryOn: "issueId provided is not valid" }
-          );
+        saveMapping(cfg.mappingPath, mapping);
+
+        // Link preconditions for bulk-created tests
+        for (const test of toCreate) {
+          if (!test.preconditions?.length) continue;
+          const entry = mapping[test.test_id];
+          if (!entry?.id) continue;
+          try {
+            const precondIds = await resolvePreconditionIds(cfg, test.preconditions);
+            if (precondIds.length > 0) {
+              await addPreconditionsToTest(cfg, xrayToken, entry.id, precondIds);
+              logger.step(`Preconditions linked: ${test.preconditions.join(", ")}`);
+            }
+          } catch (err) {
+            logger.warn(`Precondition linking failed for ${test.test_id}: ${err.message}`);
+          }
         }
-
-        updated.push(existing.key);
       } else {
-        // ── Create new test ───────────────────────────────────
-        logger.send(`${test.test_id}`);
+        logger.warn(`Bulk import job failed — falling back to serial create`);
+        // Fallback: push failing tests serially
+        for (const test of toCreate) {
+          await pushSingleTest(cfg, xrayToken, test, mapping, created, failed);
+        }
+        saveMapping(cfg.mappingPath, mapping);
+      }
+    } catch (err) {
+      logger.warn(`Bulk import failed (${err.message}) — falling back to serial create`);
+      for (const test of toCreate) {
+        await pushSingleTest(cfg, xrayToken, test, mapping, created, failed);
+      }
+      saveMapping(cfg.mappingPath, mapping);
+    }
+  } else {
+    // ── Serial create path ─────────────────────────────────────────────────
+    for (const test of toCreate) {
+      await pushSingleTest(cfg, xrayToken, test, mapping, created, failed);
+    }
+  }
 
-        const issue = await createIssue(cfg, "Test", {
-          summary: test.xray.summary,
-          description: test.xray.description,
-          priority: test.xray.priority,
-          labels,
-        });
-        logger.step(`${issue.key} (ID: ${issue.id})`);
+  // ── Serial update path (always serial — needs step diff) ──────────────────
+  for (const test of toUpdate) {
+    await pushSingleTest(cfg, xrayToken, test, mapping, updated, failed);
+  }
+
+  return { created, updated, failed };
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve JIRA keys/IDs for precondition issue keys.
+ * Preconditions are referenced by JIRA key in tests.json.
+ */
+async function resolvePreconditionIds(cfg, preconditionKeys) {
+  const ids = [];
+  for (const key of preconditionKeys) {
+    try {
+      const issues = await searchIssues(cfg, `issue = "${key}"`, ["id"], 1);
+      if (issues[0]?.id) ids.push(String(issues[0].id));
+    } catch { /* skip unresolvable */ }
+  }
+  return ids;
+}
 
-        // Set test type + add steps/definition with retry (Xray indexing delay)
+/**
+ * Create or update a single test and link preconditions.
+ */
+async function pushSingleTest(cfg, xrayToken, test, mapping, successList, failedList) {
+  try {
+    const existing = mapping[test.test_id];
+    const testType = test.xray?.testType || "Generic";
+    const labels = [...new Set([...(test.xray?.labels || []), ...(test.tags || [])])];
+
+    if (existing) {
+      // ── Update ──────────────────────────────────────────────────────────
+      logger.send(`${test.test_id} (update → ${existing.key})`);
+
+      await updateIssue(cfg, existing.key, {
+        summary: test.xray.summary,
+        description: test.xray.description,
+        priority: test.xray.priority,
+        labels,
+      });
+      logger.step("Fields updated");
+
+      if (testType === "Manual" && test.xray.steps && test.xray.steps.length > 0) {
         await withRetry(
           async () => {
-            await setTestType(cfg, xrayToken, issue.id, testType);
-
-            if (testType === "Manual" && test.xray.steps && test.xray.steps.length > 0) {
-              for (const step of test.xray.steps) {
-                await addTestStep(cfg, xrayToken, issue.id, step);
-              }
-            } else if (testType === "Generic" && test.xray?.definition) {
-              await updateTestDefinition(cfg, xrayToken, issue.id, test.xray.definition);
+            const removed = await removeAllTestSteps(cfg, xrayToken, existing.id);
+            logger.debug(`Removed ${removed} existing step(s)`);
+            for (const step of test.xray.steps) {
+              await addTestStep(cfg, xrayToken, existing.id, step);
             }
           },
           { retryOn: "issueId provided is not valid" }
         );
+        logger.step(`${test.xray.steps.length} step(s) replaced`);
+      }
 
-        if (testType === "Manual" && test.xray.steps) {
-          logger.step(`${test.xray.steps.length} step(s) added`);
-        }
+      if (testType === "Generic" && test.xray?.definition) {
+        await withRetry(
+          async () => updateTestDefinition(cfg, xrayToken, existing.id, test.xray.definition),
+          { retryOn: "issueId provided is not valid" }
+        );
+      }
 
-        mapping[test.test_id] = { key: issue.key, id: issue.id };
-        created.push(issue.key);
+      successList.push(existing.key);
+    } else {
+      // ── Create ──────────────────────────────────────────────────────────
+      logger.send(`${test.test_id}`);
+
+      const issue = await createIssue(cfg, "Test", {
+        summary: test.xray.summary,
+        description: test.xray.description,
+        priority: test.xray.priority,
+        labels,
+      });
+      logger.step(`${issue.key} (ID: ${issue.id})`);
+
+      await withRetry(
+        async () => {
+          await setTestType(cfg, xrayToken, issue.id, testType);
+
+          if (testType === "Manual" && test.xray.steps && test.xray.steps.length > 0) {
+            for (const step of test.xray.steps) {
+              await addTestStep(cfg, xrayToken, issue.id, step);
+            }
+          } else if (testType === "Generic" && test.xray?.definition) {
+            await updateTestDefinition(cfg, xrayToken, issue.id, test.xray.definition);
+          }
+        },
+        // Xray is eventually consistent: new issues take a moment to be indexed.
+        // Retry on both the "not found" timing error and the legacy "issueId" error.
+        { retryOn: ["not found", "issueId provided is not valid"], baseDelay: 1500 }
+      );
+
+      if (testType === "Manual" && test.xray.steps) {
+        logger.step(`${test.xray.steps.length} step(s) added`);
       }
 
-      // Save mapping after each test (crash-safe)
-      saveMapping(cfg.mappingPath, mapping);
-      logger.blank();
+      mapping[test.test_id] = { key: issue.key, id: issue.id };
+      successList.push(issue.key);
+    }
 
-      // Rate limiting
-      await new Promise((r) => setTimeout(r, 300));
-    } catch (err) {
-      const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
-      logger.stepFail(`Failed: ${detail}`);
-      logger.blank();
-      failed.push(test.test_id);
+    // ── Precondition linking ───────────────────────────────────────────────
+    if (test.preconditions?.length > 0) {
+      const issueId = existing?.id || mapping[test.test_id]?.id;
+      if (issueId) {
+        try {
+          const precondIds = await resolvePreconditionIds(cfg, test.preconditions);
+          if (precondIds.length > 0) {
+            await addPreconditionsToTest(cfg, xrayToken, issueId, precondIds);
+            logger.step(`Preconditions: ${test.preconditions.join(", ")}`);
+          }
+        } catch (err) {
+          logger.warn(`Precondition linking failed for ${test.test_id}: ${err.message}`);
+        }
+      }
     }
-  }
 
-  return { created, updated, failed };
+    saveMapping(cfg.mappingPath, mapping);
+    logger.blank();
+
+    await new Promise((r) => setTimeout(r, 300));
+  } catch (err) {
+    const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+    logger.stepFail(`Failed: ${detail}`);
+    logger.blank();
+    failedList.push({ testId: test.test_id, reason: detail });
+  }
 }
 
 // ─── Test Set sync ───────────────────────────────────────────────────────────
@@ -194,14 +330,18 @@ export async function buildAndPush(cfg, tests, mapping, xrayToken) {
  * @returns {Promise<{created: number, synced: number, failed: string[]}>}
  */
 export async function syncTestSets(cfg, xrayToken, tests, mapping, mappingPath) {
-  // Group test issue IDs by testSet name
+  // Group test issue IDs by testSet name — supports both string and array values
   const setGroups = new Map();
   for (const test of tests) {
     if (!test.testSet) continue;
     const mapped = mapping[test.test_id];
     if (!mapped?.id) continue;
-    if (!setGroups.has(test.testSet)) setGroups.set(test.testSet, []);
-    setGroups.get(test.testSet).push(String(mapped.id));
+    const setNames = Array.isArray(test.testSet) ? test.testSet : [test.testSet];
+    for (const setName of setNames) {
+      if (!setName) continue;
+      if (!setGroups.has(setName)) setGroups.set(setName, []);
+      setGroups.get(setName).push(String(mapped.id));
+    }
   }
 
   if (setGroups.size === 0) {
@@ -220,6 +360,28 @@ export async function syncTestSets(cfg, xrayToken, tests, mapping, mappingPath)
     try {
       let setEntry = mapping._testSets[setName];
 
+      if (!setEntry) {
+        // Search JIRA for an existing Test Set with this name before creating
+        logger.send(`Looking up Test Set "${setName}"...`);
+        try {
+          const safeQ = setName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+          const existing = await searchIssues(
+            cfg,
+            `project = "${cfg.jiraProjectKey}" AND issuetype = "Test Set" AND summary = "${safeQ}"`,
+            ["id", "key", "summary"],
+            1
+          );
+          if (existing.length > 0) {
+            setEntry = { key: existing[0].key, id: String(existing[0].id) };
+            mapping._testSets[setName] = setEntry;
+            saveMapping(mappingPath, mapping);
+            logger.step(`Found existing Test Set: ${setEntry.key}`);
+          }
+        } catch (err) {
+          logger.debug(`JIRA search for Test Set "${setName}" failed: ${err.message}`);
+        }
+      }
+
       if (!setEntry) {
         // Create new Test Set issue
         logger.send(`Creating Test Set "${setName}"...`);
@@ -257,33 +419,77 @@ export async function syncTestSets(cfg, xrayToken, tests, mapping, mappingPath)
 // ─── Test Plan sync ────────────────────────────────────────────────────────────
 
 /**
- * Ensure all test issues are members of the configured Test Plan.
+ * Bi-directionally sync Test Plan membership.
+ *
+ * Queries the plan's current members, then:
+ *   - Adds tests that are mapped locally but not in the plan
+ *   - Removes tests that are in the plan but no longer in the local mapping
  *
  * @param {object}   cfg
  * @param {string}   xrayToken
  * @param {string}   planIssueId  Numeric JIRA issue ID of the Test Plan
- * @param {string[]} testIssueIds Numeric JIRA issue IDs to add
- * @returns {Promise<{added: number, warnings: string[]}>}
+ * @param {string[]} testIssueIds Numeric JIRA issue IDs that should be in the plan
+ * @returns {Promise<{added: number, removed: number, unchanged: number}>}
  */
 export async function syncTestPlan(cfg, xrayToken, planIssueId, testIssueIds) {
-  if (!testIssueIds.length) return { added: 0, warnings: [] };
-
-  logger.pin(`Syncing ${testIssueIds.length} test(s) to Test Plan (ID: ${planIssueId})...`);
+  if (!testIssueIds.length) return { added: 0, removed: 0, unchanged: 0 };
 
-  // Batch into groups of 50 (API limit suggestion)
   const BATCH = 50;
-  let totalAdded = 0;
-  const allWarnings = [];
+  const targetSet = new Set(testIssueIds.map(String));
+
+  // ── Query existing plan membership ────────────────────────────────────────
+  let existingIds = new Set();
+  try {
+    // Paginate through all plan members (100 per call)
+    let start = 0;
+    const limit = 100;
+    let total = null;
+
+    while (total === null || start < total) {
+      const plan = await getTestPlan(cfg, xrayToken, planIssueId, { limit, start });
+      const results = plan?.tests?.results || [];
+      if (total === null) total = plan?.tests?.total ?? results.length;
+
+      for (const t of results) {
+        if (t.issueId) existingIds.add(String(t.issueId));
+      }
 
-  for (let i = 0; i < testIssueIds.length; i += BATCH) {
-    const batch = testIssueIds.slice(i, i + BATCH);
-    const result = await addTestsToTestPlan(cfg, xrayToken, planIssueId, batch);
+      if (results.length < limit) break;
+      start += results.length;
+    }
+
+    logger.pin(`Plan has ${existingIds.size} existing test(s)`);
+  } catch (err) {
+    logger.warn(`Could not query plan members: ${err.message} — falling back to add-only`);
+    // Fallback: add all (idempotent), skip removes
+    let totalAdded = 0;
+    for (let i = 0; i < testIssueIds.length; i += BATCH) {
+      const result = await addTestsToTestPlan(cfg, xrayToken, planIssueId, testIssueIds.slice(i, i + BATCH));
+      totalAdded += result.addedTests?.length || 0;
+    }
+    return { added: totalAdded, removed: 0, unchanged: 0 };
+  }
+
+  const toAdd    = [...targetSet].filter((id) => !existingIds.has(id));
+  const toRemove = [...existingIds].filter((id) => !targetSet.has(id));
+  const unchanged = testIssueIds.filter((id) => existingIds.has(String(id))).length;
+
+  // ── Add new tests ─────────────────────────────────────────────────────────
+  let totalAdded = 0;
+  for (let i = 0; i < toAdd.length; i += BATCH) {
+    const result = await addTestsToTestPlan(cfg, xrayToken, planIssueId, toAdd.slice(i, i + BATCH));
     totalAdded += result.addedTests?.length || 0;
-    if (result.warnings?.length) allWarnings.push(...result.warnings);
   }
 
-  logger.step(`${totalAdded} test(s) added to Test Plan`);
-  return { added: totalAdded, warnings: allWarnings };
+  // ── Remove stale tests ────────────────────────────────────────────────────
+  let totalRemoved = 0;
+  for (let i = 0; i < toRemove.length; i += BATCH) {
+    const batch = toRemove.slice(i, i + BATCH);
+    await removeTestsFromTestPlan(cfg, xrayToken, planIssueId, batch);
+    totalRemoved += batch.length;
+  }
+
+  return { added: totalAdded, removed: totalRemoved, unchanged };
 }
 
 // ─── Folder sync ──────────────────────────────────────────────────────────────
@@ -334,13 +540,13 @@ export async function syncFolders(cfg, xrayToken, projectId, tests, mapping) {
       await addTestsToFolder(cfg, xrayToken, projectId, folderPath, testIds);
       synced += testIds.length;
 
-      logger.step(`${folderPath} — ${testIds.length} test(s).__`);
+      logger.step(`${folderPath} — ${testIds.length} test(s)`);
     } catch (err) {
       logger.warn(`Failed to sync folder ${folderPath}: ${err.message}`);
     }
   }
 
-  return { synced, created: createdFolders };
+  return { created: createdFolders.length, assigned: synced };
 }