@msalaam/xray-qe-toolkit 1.1.0

package/commands/init.js

@@ -0,0 +1,141 @@
+/**
+ * Command: xray-qe init
+ *
+ * Scaffolds a new project with starter templates:
+ *   - tests.json        (test definitions)
+ *   - xray-mapping.json (empty mapping)
+ *   - .env.example      (environment variable template)
+ *   - .xrayrc           (optional project-level config)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import logger from "../lib/logger.js";
+import { setVerbose } from "../lib/logger.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES = path.join(__dirname, "..", "templates");
+
+export default async function init(opts = {}) {
+  if (opts.verbose) setVerbose(true);
+
+  const cwd = process.cwd();
+  logger.rocket("@msalaam/xray-qe-toolkit — Project Init\n");
+
+  let created = 0;
+  let skipped = 0;
+
+  // Create knowledge/ directory structure
+  const knowledgeDirs = [
+    { path: "knowledge", desc: "Knowledge base folder" },
+    { path: "knowledge/api-specs", desc: "API specifications (OpenAPI, Swagger)" },
+    { path: "knowledge/requirements", desc: "Business requirements and docs" },
+    { path: "knowledge/tickets", desc: "JIRA/Confluence exports" },
+  ];
+
+  for (const dir of knowledgeDirs) {
+    const dirPath = path.join(cwd, dir.path);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+      logger.success(`${dir.path}/ created (${dir.desc})`);
+      created++;
+    } else {
+      logger.warn(`${dir.path}/ already exists — skipping`);
+      skipped++;
+    }
+  }
+
+  // Copy knowledge README
+  const knowledgeReadmeSrc = path.join(TEMPLATES, "knowledge-README.md");
+  const knowledgeReadmeDest = path.join(cwd, "knowledge", "README.md");
+  if (!fs.existsSync(knowledgeReadmeDest)) {
+    fs.copyFileSync(knowledgeReadmeSrc, knowledgeReadmeDest);
+    logger.success("knowledge/README.md created (Knowledge base guide)");
+    created++;
+  } else {
+    logger.warn("knowledge/README.md already exists — skipping");
+    skipped++;
+  }
+
+  // Copy main README
+  const readmeSrc = path.join(TEMPLATES, "README.template.md");
+  const readmeDest = path.join(cwd, "README.md");
+  if (!fs.existsSync(readmeDest)) {
+    fs.copyFileSync(readmeSrc, readmeDest);
+    logger.success("README.md created (Getting started guide)");
+    created++;
+  } else {
+    logger.warn("README.md already exists — skipping");
+    skipped++;
+  }
+
+  // Create .gitkeep files in knowledge subdirs to ensure they're tracked
+  for (const subdir of ["api-specs", "requirements", "tickets"]) {
+    const gitkeepPath = path.join(cwd, "knowledge", subdir, ".gitkeep");
+    if (!fs.existsSync(gitkeepPath)) {
+      fs.writeFileSync(gitkeepPath, "");
+    }
+  }
+
+  const files = [
+    { src: "tests.json", dest: "tests.json", desc: "Test definitions" },
+    { src: "xray-mapping.json", dest: "xray-mapping.json", desc: "Xray mapping (empty)" },
+  ];
+
+  for (const file of files) {
+    const destPath = path.join(cwd, file.dest);
+    if (fs.existsSync(destPath)) {
+      logger.warn(`${file.dest} already exists — skipping`);
+      skipped++;
+    } else {
+      fs.copyFileSync(path.join(TEMPLATES, file.src), destPath);
+      logger.success(`${file.dest} created (${file.desc})`);
+      created++;
+    }
+  }
+
+  // Copy .env.example from package root
+  const envExampleSrc = path.join(__dirname, "..", ".env.example");
+  const envExampleDest = path.join(cwd, ".env.example");
+  if (!fs.existsSync(envExampleDest)) {
+    fs.copyFileSync(envExampleSrc, envExampleDest);
+    logger.success(".env.example created");
+    created++;
+  } else {
+    logger.warn(".env.example already exists — skipping");
+    skipped++;
+  }
+
+  // Create .xrayrc if it doesn't exist
+  const xrayrcPath = path.join(cwd, ".xrayrc");
+  if (!fs.existsSync(xrayrcPath)) {
+    const xrayrc = {
+      testsPath: "tests.json",
+      mappingPath: "xray-mapping.json",
+      collectionPath: "collection.postman.json",
+      knowledgePath: "knowledge",
+      playwrightDir: "playwright-tests",
+    };
+    fs.writeFileSync(xrayrcPath, JSON.stringify(xrayrc, null, 2));
+    logger.success(".xrayrc created (project config)");
+    created++;
+  } else {
+    logger.warn(".xrayrc already exists — skipping");
+    skipped++;
+  }
+
+  logger.success(`${created} file(s)/folder(s) created, ${skipped} skipped\n`);
+
+  // Print next steps
+  console.log("📖 Next steps:");
+  console.log("   1. Copy .env.example → .env and fill in your credentials");
+  console.log("   2. Add API specs and docs to knowledge/ folder (see knowledge/README.md)");
+  console.log("   3. Generate test cases: npx xray-qe gen-tests --ai (or edit tests.json manually)");
+  console.log("   4. Review tests: npx xray-qe edit-json");
+  console.log("   5. Push tests to Xray: npx xray-qe push-tests");
+  console.log("   6. Generate Postman collection: npx xray-qe gen-postman --ai");
+  console.log("   7. Generate CI pipeline: npx xray-qe gen-pipeline");
+  console.log("");
+}

package/commands/pushTests.js

@@ -0,0 +1,114 @@
+/**
+ * Command: xray-qe push-tests [--testExecKey QE-123] [--skip-exec]
+ *
+ * Validates tests.json against schema, then pushes tests to Xray Cloud.
+ * Idempotent: updates existing tests (via xray-mapping.json) and creates new ones.
+ *
+ * If --testExecKey is provided, links all tests to that existing Test Execution.
+ * If --skip-exec is set, tests are pushed without creating/linking any execution.
+ * Otherwise, creates a new Test Execution from tests.json config and links all tests.
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import logger, { setVerbose } from "../lib/logger.js";
+import { loadConfig, validateConfig } from "../lib/config.js";
+import {
+  buildAndPush,
+  loadMapping,
+  createExecutionAndLink,
+  linkToExistingExecution,
+  saveMapping,
+} from "../lib/testCaseBuilder.js";
+
+export default async function pushTests(opts = {}) {
+  if (opts.verbose) setVerbose(true);
+
+  logger.rocket("@msalaam/xray-qe-toolkit — Push Tests\n");
+
+  // Load & validate config
+  const cfg = loadConfig({ envPath: opts.env });
+  validateConfig(cfg);
+
+  // Load tests.json
+  if (!fs.existsSync(cfg.testsPath)) {
+    logger.error(`tests.json not found at ${cfg.testsPath}`);
+    logger.info("Run 'npx xray-qe init' to create a starter tests.json");
+    process.exit(1);
+  }
+
+  const testsConfig = JSON.parse(fs.readFileSync(cfg.testsPath, "utf8"));
+  const allTests = testsConfig.tests || [];
+
+  // Filter out skipped tests
+  const tests = allTests.filter((t) => !t.skip);
+  const skippedCount = allTests.length - tests.length;
+
+  if (tests.length === 0) {
+    logger.error("No tests to push (all tests are skipped or tests array is empty)");
+    process.exit(1);
+  }
+
+  logger.info(`${tests.length} test(s) to push${skippedCount > 0 ? ` (${skippedCount} skipped)` : ""}\n`);
+
+  // Validate against schema (soft validation — warn but continue)
+  try {
+    const require = createRequire(import.meta.url);
+    const Ajv = require("ajv");
+    const schema = JSON.parse(
+      fs.readFileSync(new URL("../schema/tests.schema.json", import.meta.url), "utf8")
+    );
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    if (!validate(testsConfig)) {
+      logger.warn("tests.json has schema validation warnings:");
+      for (const err of validate.errors) {
+        console.log(`   ⚠️  ${err.instancePath || "/"}: ${err.message}`);
+      }
+      logger.blank();
+    }
+  } catch {
+    logger.debug("Schema validation skipped (ajv not available)");
+  }
+
+  // Load existing mapping
+  const mapping = loadMapping(cfg.mappingPath);
+
+  // Build & push
+  const result = await buildAndPush(cfg, tests, mapping);
+
+  logger.blank();
+  logger.success(
+    `${result.created.length} created, ${result.updated.length} updated, ${result.failed.length} failed`
+  );
+
+  // Handle Test Execution linking
+  const allTestKeys = [
+    ...result.created,
+    ...result.updated,
+    ...Object.values(mapping)
+      .filter((v) => v.key && !v.key.startsWith("_"))
+      .map((v) => v.key),
+  ];
+  // Deduplicate
+  const testKeys = [...new Set(allTestKeys)];
+
+  if (opts.skipExec) {
+    logger.info("Skipping Test Execution (--skip-exec)");
+  } else if (opts.testExecKey) {
+    // Link to existing execution
+    logger.blank();
+    const linkResult = await linkToExistingExecution(cfg, opts.testExecKey, testKeys);
+    logger.link(`View: ${cfg.jiraUrl}/browse/${opts.testExecKey}`);
+  } else if (testsConfig.testExecution) {
+    // Create new execution and link
+    logger.blank();
+    const execResult = await createExecutionAndLink(cfg, testsConfig.testExecution, testKeys, mapping);
+    saveMapping(cfg.mappingPath, mapping);
+    logger.link(`View Test Execution: ${cfg.jiraUrl}/browse/${execResult.key}`);
+  }
+
+  logger.blank();
+  logger.save(`Mapping saved to ${cfg.mappingPath}`);
+  logger.blank();
+}

package/lib/config.js

@@ -0,0 +1,108 @@
+/**
+ * @msalaam/xray-qe-toolkit — Configuration Loader
+ *
+ * Loads and validates environment variables from .env and optional .xrayrc file.
+ * All 6 required env vars must be present before any API call.
+ */
+
+import { config as dotenvConfig } from "dotenv";
+import fs from "node:fs";
+import path from "node:path";
+
+const REQUIRED_VARS = [
+  "XRAY_ID",
+  "XRAY_SECRET",
+  "JIRA_PROJECT_KEY",
+  "JIRA_EMAIL",
+  "JIRA_API_TOKEN",
+  "JIRA_URL",
+];
+
+/**
+ * Load configuration from .env file and optional .xrayrc JSON file.
+ *
+ * @param {object}  [opts]           Options
+ * @param {string}  [opts.envPath]   Custom path to .env file
+ * @param {string}  [opts.cwd]       Working directory (defaults to process.cwd())
+ * @returns {object} Frozen configuration object
+ */
+export function loadConfig(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+
+  // Load .env — custom path takes precedence
+  const envPath = opts.envPath || path.join(cwd, ".env");
+  if (fs.existsSync(envPath)) {
+    dotenvConfig({ path: envPath });
+  } else {
+    // Try default dotenv resolution
+    dotenvConfig();
+  }
+
+  // Merge optional .xrayrc (non-sensitive project defaults)
+  const rcPath = path.join(cwd, ".xrayrc");
+  let rcConfig = {};
+  if (fs.existsSync(rcPath)) {
+    try {
+      rcConfig = JSON.parse(fs.readFileSync(rcPath, "utf8"));
+    } catch {
+      // Ignore malformed .xrayrc — env vars take precedence anyway
+    }
+  }
+
+  const cfg = {
+    // Xray Cloud
+    xrayId: process.env.XRAY_ID || rcConfig.xrayId,
+    xraySecret: process.env.XRAY_SECRET || rcConfig.xraySecret,
+    xrayGraphqlUrl:
+      process.env.XRAY_GRAPHQL_URL ||
+      rcConfig.xrayGraphqlUrl ||
+      "https://us.xray.cloud.getxray.app/api/v2/graphql",
+    xrayAuthUrl:
+      process.env.XRAY_AUTH_URL ||
+      rcConfig.xrayAuthUrl ||
+      "https://xray.cloud.getxray.app/api/v2/authenticate",
+
+    // JIRA
+    jiraProjectKey: process.env.JIRA_PROJECT_KEY || rcConfig.jiraProjectKey,
+    jiraUrl: (process.env.JIRA_URL || rcConfig.jiraUrl || "").replace(/\/+$/, ""),
+    jiraApiToken: process.env.JIRA_API_TOKEN || rcConfig.jiraApiToken,
+    jiraEmail: process.env.JIRA_EMAIL || rcConfig.jiraEmail,
+
+    // Paths (resolved relative to consuming project)
+    testsPath: path.resolve(cwd, rcConfig.testsPath || "tests.json"),
+    mappingPath: path.resolve(cwd, rcConfig.mappingPath || "xray-mapping.json"),
+    collectionPath: path.resolve(cwd, rcConfig.collectionPath || "collection.postman.json"),
+    knowledgePath: path.resolve(cwd, rcConfig.knowledgePath || "knowledge"),
+    playwrightDir: path.resolve(cwd, rcConfig.playwrightDir || "playwright-tests"),
+  };
+
+  return Object.freeze(cfg);
+}
+
+/**
+ * Validate that all required environment variables are set.
+ *
+ * @param {object} cfg  Config object from loadConfig()
+ * @throws {Error} If any required variable is missing
+ */
+export function validateConfig(cfg) {
+  const map = {
+    XRAY_ID: cfg.xrayId,
+    XRAY_SECRET: cfg.xraySecret,
+    JIRA_PROJECT_KEY: cfg.jiraProjectKey,
+    JIRA_URL: cfg.jiraUrl,
+    JIRA_API_TOKEN: cfg.jiraApiToken,
+    JIRA_EMAIL: cfg.jiraEmail,
+  };
+
+  const missing = Object.entries(map)
+    .filter(([, v]) => !v)
+    .map(([k]) => k);
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required configuration: ${missing.join(", ")}.\n` +
+        `Set them in your .env file or .xrayrc. See .env.example for reference.`
+    );
+  }
+}

package/lib/index.js

@@ -0,0 +1,31 @@
+/**
+ * @msalaam/xray-qe-toolkit — Public API
+ *
+ * Re-exports all library modules for programmatic usage.
+ * Consumers can also use the CLI (bin/cli.js) for interactive workflows.
+ */
+
+export { loadConfig, validateConfig } from "./config.js";
+export { default as logger, setVerbose } from "./logger.js";
+export {
+  authenticate,
+  createIssue,
+  updateIssue,
+  getIssue,
+  setTestTypeAutomated,
+  addTestStep,
+  removeAllTestSteps,
+  linkIssues,
+  linkMultiple,
+  importResults,
+  withRetry,
+  toAdf,
+} from "./xrayClient.js";
+export {
+  buildAndPush,
+  createExecutionAndLink,
+  linkToExistingExecution,
+  loadMapping,
+  saveMapping,
+} from "./testCaseBuilder.js";
+export { generate as generatePostmanCollection } from "./postmanGenerator.js";

package/lib/logger.js

@@ -0,0 +1,43 @@
+/**
+ * @msalaam/xray-qe-toolkit — Logger
+ *
+ * Emoji-prefixed, level-aware console logger.
+ * Mirrors the output style of the original @oldmutual/xray-test-automation package.
+ */
+
+let verbose = false;
+
+/**
+ * Enable or disable verbose (debug) output.
+ * @param {boolean} flag
+ */
+export function setVerbose(flag) {
+  verbose = !!flag;
+}
+
+/** @returns {boolean} */
+export function isVerbose() {
+  return verbose;
+}
+
+const logger = {
+  info:    (...args) => console.log("📋", ...args),
+  success: (...args) => console.log("✅", ...args),
+  warn:    (...args) => console.log("⚠️ ", ...args),
+  error:   (...args) => console.error("❌", ...args),
+  step:    (...args) => console.log("   ✅", ...args),
+  stepFail:(...args) => console.log("   ❌", ...args),
+  send:    (...args) => console.log("📤", ...args),
+  link:    (...args) => console.log("🔗", ...args),
+  auth:    (...args) => console.log("🔐", ...args),
+  save:    (...args) => console.log("💾", ...args),
+  wait:    (...args) => console.log("⏳", ...args),
+  rocket:  (...args) => console.log("🚀", ...args),
+  pin:     (...args) => console.log("📌", ...args),
+  debug:   (...args) => {
+    if (verbose) console.log("🐛", ...args);
+  },
+  blank:   () => console.log(""),
+};
+
+export default logger;