@msalaam/xray-qe-toolkit 1.1.0

package/lib/postmanGenerator.js

@@ -0,0 +1,305 @@
+/**
+ * @msalaam/xray-qe-toolkit — Postman Collection Generator
+ *
+ * Generates a Postman Collection v2.1 JSON from tests.json.
+ * Each test becomes a request folder; steps map to request items with
+ * pre-request scripts and test assertions.
+ *
+ * The output is a working starting point — QEs or agents can further
+ * refine the generated collection.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import logger from "./logger.js";
+
+/**
+ * Generate a Postman v2.1 collection from tests.json config.
+ *
+ * @param {object}   testsConfig   Parsed tests.json content
+ * @param {string}   outputPath    Where to write collection.postman.json
+ * @param {object}   [opts]        Options
+ * @param {string}   [opts.baseUrl]  Base URL placeholder (default: "{{baseUrl}}")
+ * @param {object}   [opts.mapping]  xray-mapping.json content (for embedding JIRA keys)
+ * @returns {object} The generated collection object
+ */
+export function generate(testsConfig, outputPath, opts = {}) {
+  const baseUrl = opts.baseUrl || "{{baseUrl}}";
+  const mapping = opts.mapping || {};
+  const tests = testsConfig.tests || [];
+
+  // Filter for API tests only (type: "api" or unset for backward compatibility)
+  const apiTests = tests.filter((t) => !t.type || t.type === "api");
+
+  const collection = {
+    info: {
+      name: testsConfig.testExecution?.summary || "Generated Test Collection",
+      description:
+        (testsConfig.testExecution?.description || "Auto-generated by @msalaam/xray-qe-toolkit") +
+        "\n\n⚠️ SCAFFOLD: This is a generated starting point. Review and enhance each request with proper assertions, environment variables, and edge cases before use.",
+      schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+      _postman_id: generateUUID(),
+    },
+    variable: [
+      {
+        key: "baseUrl",
+        value: "https://api.example.com",
+        type: "string",
+      },
+      {
+        key: "authToken",
+        value: "",
+        type: "string",
+      },
+    ],
+    auth: {
+      type: "bearer",
+      bearer: [
+        {
+          key: "token",
+          value: "{{authToken}}",
+          type: "string",
+        },
+      ],
+    },
+    item: apiTests.map((test) => buildTestFolder(test, baseUrl, mapping)),
+  };
+
+  fs.writeFileSync(outputPath, JSON.stringify(collection, null, 2));
+  logger.save(`Collection written to ${path.basename(outputPath)}`);
+  logger.info(`${apiTests.length} API test(s) → ${countRequests(collection)} request(s)`);
+  if (tests.length > apiTests.length) {
+    logger.info(`${tests.length - apiTests.length} non-API tests skipped (use type: "api" to include)`);
+  }
+
+  return collection;
+}
+
+// ─── Internal builders ────────────────────────────────────────────────────────
+
+/**
+ * Convert a single test definition into a Postman folder with request items.
+ */
+function buildTestFolder(test, baseUrl, mapping = {}) {
+  // Use JIRA key if available in mapping, otherwise use test_id
+  const testKey = mapping[test.test_id]?.key || test.test_id;
+  
+  const folder = {
+    name: `[${testKey}] ${test.xray.summary}`,
+    description: test.xray.description || "",
+    item: [],
+  };
+
+  if (!test.xray.steps || test.xray.steps.length === 0) {
+    // No steps — create a single placeholder request
+    folder.item.push(buildPlaceholderRequest(test, baseUrl));
+    return folder;
+  }
+
+  test.xray.steps.forEach((step, idx) => {
+    folder.item.push(buildStepRequest(test, step, idx + 1, baseUrl));
+  });
+
+  return folder;
+}
+
+/**
+ * Build a request item from a test step.
+ */
+function buildStepRequest(test, step, stepNum, baseUrl) {
+  // Try to infer HTTP method and path from the step action/data
+  const { method, endpoint } = inferEndpoint(step);
+
+  const item = {
+    name: `Step ${stepNum}: ${truncate(step.action, 80)}`,
+    request: {
+      method,
+      header: [
+        {
+          key: "Content-Type",
+          value: "application/json",
+        },
+      ],
+      url: {
+        raw: `${baseUrl}${endpoint}`,
+        host: [baseUrl],
+        path: endpoint.split("/").filter(Boolean),
+      },
+    },
+    event: [],
+  };
+
+  // Add pre-request script with step data context
+  if (step.data) {
+    item.event.push({
+      listen: "prerequest",
+      script: {
+        type: "text/javascript",
+        exec: [
+          `// Step Data: ${step.data}`,
+          `// Action: ${step.action}`,
+          `console.log("Executing: ${escapeJs(step.action)}");`,
+        ],
+      },
+    });
+
+    // Try to extract request body from step data
+    const body = extractBody(step.data);
+    if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      item.request.body = {
+        mode: "raw",
+        raw: body,
+        options: { raw: { language: "json" } },
+      };
+    }
+  }
+
+  // Add test script with expected result assertion
+  if (step.expected_result) {
+    item.event.push({
+      listen: "test",
+      script: {
+        type: "text/javascript",
+        exec: buildTestScript(step),
+      },
+    });
+  }
+
+  return item;
+}
+
+/**
+ * Build a placeholder request when a test has no steps.
+ */
+function buildPlaceholderRequest(test, baseUrl) {
+  return {
+    name: test.xray.summary,
+    request: {
+      method: "GET",
+      header: [],
+      url: {
+        raw: `${baseUrl}/TODO`,
+        host: [baseUrl],
+        path: ["TODO"],
+      },
+      description: `TODO: Configure this request for test ${test.test_id}`,
+    },
+  };
+}
+
+/**
+ * Infer HTTP method and endpoint from step action/data text.
+ */
+function inferEndpoint(step) {
+  const combined = `${step.action} ${step.data || ""}`;
+  const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+  let method = "GET";
+  let endpoint = "/api/TODO";
+
+  // Look for explicit HTTP method
+  for (const m of methods) {
+    if (combined.toUpperCase().includes(m)) {
+      method = m;
+      break;
+    }
+  }
+
+  // Look for a path pattern like /api/something or /endpoint
+  const pathMatch = combined.match(/(?:\/[\w{}\-]+){1,10}/);
+  if (pathMatch) {
+    endpoint = pathMatch[0];
+  }
+
+  return { method, endpoint };
+}
+
+/**
+ * Build Postman test script lines from an expected result.
+ */SCAFFOLD: Expected - ${step.expected_result}`,
+    `// SCAFFOLD: Enhance this assertion based on actual API behavior
+function buildTestScript(step) {
+  const lines = [
+    `// Expected: ${step.expected_result}`,
+    "",
+  ];
+
+  const expected = step.expected_result.toLowerCase();
+
+  // Infer status code assertions
+  const statusMatch = expected.match(/(\d{3})\s/);
+  if (statusMatch) {
+    lines.push(`pm.test("Status code is ${statusMatch[1]}", function () {`);
+    lines.push(`    pm.response.to.have.status(${statusMatch[1]});`);
+    lines.push(`});`);
+    lines.push("");
+  }
+
+  // Check for schema vSCAFFOLDation mentions
+  if (expected.includes("schema") || expected.includes("required fields")) {
+    lines.push(`pm.test("Response has expected schema", function () {`);
+    lines.push(`    const json = pm.response.json();`);
+    lines.push(`    // TODO: Add schema assertions based on expected fields`);
+    lines.push(`    pm.expect(json).to.be.an("object");`);
+    lines.push(`});`);
+    lines.push("");
+  }
+
+  // Check for error message mentions
+  if (expected.includes("error") || expected.includes("400") || expected.includes("401")) {
+    lines.push(`pm.test("Error response format", function () {`);
+    lines.push(`    const json = pm.response.json();`);
+    lines.push(`    pm.expect(json).to.have.property("error");`);
+    lines.push(`});`);
+    lines.push("");
+  }
+
+  // Always add a general assertion
+  lines.push(`pm.test("${escapeJs(truncate(step.expected_result, 100))}", function () {`);
+  lines.push(`    pm.response.to.be.ok;`);
+  lines.push(`});`);
+
+  return lines;
+}
+
+/**
+ * Try to extract a JSON body from step data text.
+ */
+function extractBody(data) {
+  // Look for JSON object in the data field
+  const jsonMatch = data.match(/\{[\s\S]*\}/);
+  if (jsonMatch) {
+    try {
+      JSON.parse(jsonMatch[0]);
+      return jsonMatch[0];
+    } catch {
+      return jsonMatch[0]; // Return raw even if not valid JSON
+    }
+  }
+  return null;
+}
+
+// ─── Utilities ────────────────────────────────────────────────────────────────
+
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max - 3) + "..." : str;
+}
+
+function escapeJs(str) {
+  return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+
+function generateUUID() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}
+
+function countRequests(collection) {
+  let count = 0;
+  for (const folder of collection.item) {
+    count += folder.item ? folder.item.length : 1;
+  }
+  return count;
+}

package/lib/testCaseBuilder.js

@@ -0,0 +1,202 @@
+/**
+ * @msalaam/xray-qe-toolkit — Test Case Builder
+ *
+ * Orchestrates the creation / update of Xray test cases and their linkage
+ * to Test Executions.  Supports idempotent push: if a test_id already exists
+ * in xray-mapping.json the issue is updated rather than duplicated.
+ */
+
+import fs from "node:fs";
+import logger from "./logger.js";
+import {
+  authenticate,
+  createIssue,
+  updateIssue,
+  setTestTypeAutomated,
+  addTestStep,
+  removeAllTestSteps,
+  linkMultiple,
+  withRetry,
+} from "./xrayClient.js";
+
+// ─── Mapping helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Load xray-mapping.json from disk (or return empty object).
+ * @param {string} mappingPath
+ * @returns {object}
+ */
+export function loadMapping(mappingPath) {
+  if (fs.existsSync(mappingPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(mappingPath, "utf8"));
+    } catch {
+      logger.warn("Could not load existing mapping file, creating new one");
+    }
+  }
+  return {};
+}
+
+/**
+ * Persist mapping object to disk (JSON, 2-space indent).
+ * @param {string} mappingPath
+ * @param {object} mapping
+ */
+export function saveMapping(mappingPath, mapping) {
+  fs.writeFileSync(mappingPath, JSON.stringify(mapping, null, 2));
+}
+
+// ─── Core build & push ────────────────────────────────────────────────────────
+
+/**
+ * Create or update Xray test cases from a tests.json configuration.
+ *
+ * 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 Automated type, add steps
+ *  3. Save mapping after each test (crash-safe)
+ *  4. 300ms rate-limit delay between tests
+ *
+ * @param {object}   cfg        Config from loadConfig()
+ * @param {object[]} tests      Array of test definitions from tests.json
+ * @param {object}   mapping    Current xray-mapping.json contents (mutated in place)
+ * @returns {Promise<{created: string[], updated: string[], failed: string[]}>}
+ */
+export async function buildAndPush(cfg, tests, mapping) {
+  const xrayToken = await authenticate(cfg);
+
+  const created = [];
+  const updated = [];
+  const failed = [];
+
+  for (const test of tests) {
+    try {
+      const existing = mapping[test.test_id];
+
+      if (existing) {
+        // ── Update existing test ──────────────────────────────
+        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: test.xray.labels,
+        });
+        logger.step("Fields updated");
+
+        // Replace steps: remove all existing, re-add from tests.json
+        if (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`);
+        }
+
+        updated.push(existing.key);
+      } else {
+        // ── Create new test ───────────────────────────────────
+        logger.send(`${test.test_id}`);
+
+        const issue = await createIssue(cfg, "Test", {
+          summary: test.xray.summary,
+          description: test.xray.description,
+          priority: test.xray.priority,
+          labels: test.xray.labels,
+        });
+        logger.step(`${issue.key} (ID: ${issue.id})`);
+
+        // Set type + add steps with retry (Xray indexing delay)
+        if (test.xray.steps && test.xray.steps.length > 0) {
+          await withRetry(
+            async () => {
+              await setTestTypeAutomated(cfg, xrayToken, issue.id);
+
+              for (const step of test.xray.steps) {
+                await addTestStep(cfg, xrayToken, issue.id, step);
+              }
+            },
+            { retryOn: "issueId provided is not valid" }
+          );
+          logger.step(`${test.xray.steps.length} step(s) added`);
+        }
+
+        mapping[test.test_id] = { key: issue.key, id: issue.id };
+        created.push(issue.key);
+      }
+
+      // Save mapping after each test (crash-safe)
+      saveMapping(cfg.mappingPath, mapping);
+      logger.blank();
+
+      // 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);
+    }
+  }
+
+  return { created, updated, failed };
+}
+
+/**
+ * Create a Test Execution and link all tests to it.
+ *
+ * @param {object}   cfg              Config
+ * @param {object}   execConfig       { summary, description }
+ * @param {string[]} testKeys         JIRA keys to link
+ * @param {object}   mapping          Mapping object (mutated — adds _testexecution)
+ * @returns {Promise<{key: string, id: string, linked: string[]}>}
+ */
+export async function createExecutionAndLink(cfg, execConfig, testKeys, mapping) {
+  logger.pin(`Creating Test Execution: "${execConfig.summary}"...`);
+
+  const execution = await createIssue(cfg, "Test Execution", {
+    summary: execConfig.summary,
+    description: execConfig.description || execConfig.summary,
+  });
+  logger.step(execution.key);
+
+  mapping._testexecution = { key: execution.key, id: execution.id };
+  saveMapping(cfg.mappingPath, mapping);
+
+  // Wait for Xray indexing
+  logger.wait("Waiting for Xray to index tests...");
+  await new Promise((r) => setTimeout(r, 3000));
+
+  // Link tests
+  logger.link(`Linking ${testKeys.length} test(s) to Test Execution...`);
+  const { linked } = await linkMultiple(cfg, testKeys, execution.key);
+  logger.step(`${linked.length} test(s) linked`);
+
+  return { key: execution.key, id: execution.id, linked };
+}
+
+/**
+ * Link tests to an existing Test Execution key.
+ *
+ * @param {object}   cfg
+ * @param {string}   testExecKey  e.g. "QE-123"
+ * @param {string[]} testKeys
+ * @returns {Promise<{linked: string[], failed: string[]}>}
+ */
+export async function linkToExistingExecution(cfg, testExecKey, testKeys) {
+  logger.pin(`Using existing Test Execution: ${testExecKey}`);
+  logger.link(`Linking ${testKeys.length} test(s)...`);
+
+  const result = await linkMultiple(cfg, testKeys, testExecKey);
+  logger.step(`${result.linked.length} test(s) linked`);
+
+  return result;
+}