@msalaam/xray-qe-toolkit 1.4.0 → 1.5.0

package/commands/validate.js

@@ -0,0 +1,136 @@
+/**
+ * Command: xqt validate [--file <path>] [--schema <schema>]
+ *
+ * Validates local project files against their JSON schemas.
+ * By default validates both tests.json and resources/business-rules.yaml.
+ *
+ * Schema options: tests | business-rules | all (default: all)
+ *
+ * Exit code 1 if any validation errors are found (useful in CI).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import logger, { setVerbose } from "../lib/logger.js";
+import { loadConfig } from "../lib/config.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SCHEMA_DIR = path.join(__dirname, "..", "schema");
+
+export default async function validate(opts = {}) {
+  if (opts.verbose) setVerbose(true);
+
+  logger.rocket("@msalaam/xray-qe-toolkit — Validate\n");
+
+  const cfg = loadConfig({ envPath: opts.env });
+
+  const schemaFilter = opts.schema || "all";
+
+  let totalErrors = 0;
+
+  // ── Require AJV ────────────────────────────────────────────────────────────
+  let Ajv;
+  try {
+    const require = createRequire(import.meta.url);
+    Ajv = require("ajv");
+  } catch {
+    logger.error("ajv is required for validation. Run: npm install ajv");
+    process.exit(1);
+  }
+
+  const ajv = new Ajv({ allErrors: true });
+
+  // ── 1. Validate tests.json ────────────────────────────────────────────────
+  if (schemaFilter === "all" || schemaFilter === "tests") {
+    const filePath = opts.file || cfg.testsPath;
+    const schemaPath = path.join(SCHEMA_DIR, "tests.schema.json");
+
+    console.log(`Validating ${filePath}...`);
+
+    if (!fs.existsSync(filePath)) {
+      logger.warn(`  File not found: ${filePath}`);
+    } else if (!fs.existsSync(schemaPath)) {
+      logger.warn(`  Schema not found: ${schemaPath}`);
+    } else {
+      const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+      const data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      const validate = ajv.compile(schema);
+
+      if (validate(data)) {
+        logger.success("  tests.json: valid");
+      } else {
+        logger.error(`  tests.json: ${validate.errors.length} error(s)`);
+        for (const err of validate.errors) {
+          const location = err.instancePath || "/";
+          console.log(`    • ${location}: ${err.message}`);
+          if (err.params && Object.keys(err.params).length) {
+            console.log(`      params: ${JSON.stringify(err.params)}`);
+          }
+        }
+        totalErrors += validate.errors.length;
+      }
+    }
+  }
+
+  // ── 2. Validate business-rules.yaml ───────────────────────────────────────
+  if (schemaFilter === "all" || schemaFilter === "business-rules") {
+    const yamlPath = path.join(
+      path.dirname(cfg.testsPath),   // project root
+      cfg.resourcesPath || "resources",
+      "business-rules.yaml"
+    );
+    const schemaPath = path.join(SCHEMA_DIR, "business-rules.schema.json");
+
+    logger.blank();
+    console.log(`Validating ${yamlPath}...`);
+
+    if (!fs.existsSync(yamlPath)) {
+      logger.info(`  Not found (${yamlPath}) — skipping`);
+    } else if (!fs.existsSync(schemaPath)) {
+      logger.warn(`  Schema not found: ${schemaPath}`);
+    } else {
+      // Dynamically import js-yaml
+      let yaml;
+      try {
+        const { default: yamlModule } = await import("js-yaml");
+        yaml = yamlModule;
+      } catch {
+        logger.warn("  js-yaml not installed — skipping business-rules validation");
+        logger.info("  Run: npm install js-yaml");
+      }
+
+      if (yaml) {
+        const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+        const data = yaml.load(fs.readFileSync(yamlPath, "utf8"));
+
+        // Need a fresh Ajv instance — compiled schemas are keyed by $id
+        const ajv2 = new Ajv({ allErrors: true });
+        const validate = ajv2.compile(schema);
+
+        if (validate(data)) {
+          logger.success("  business-rules.yaml: valid");
+        } else {
+          logger.error(`  business-rules.yaml: ${validate.errors.length} error(s)`);
+          for (const err of validate.errors) {
+            const location = err.instancePath || "/";
+            console.log(`    • ${location}: ${err.message}`);
+          }
+          totalErrors += validate.errors.length;
+        }
+      }
+    }
+  }
+
+  // ── Summary ────────────────────────────────────────────────────────────────
+  logger.blank();
+  if (totalErrors === 0) {
+    logger.success("All files valid");
+  } else {
+    logger.error(`Validation failed with ${totalErrors} error(s)`);
+    process.exit(1);
+  }
+  logger.blank();
+}

package/lib/config.js

@@ -9,14 +9,25 @@ 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",
-];
+// ─── Region → endpoint mapping ─────────────────────────────────────────────────
+
+const XRAY_REGIONS = {
+  us: {
+    graphql: "https://us.xray.cloud.getxray.app/api/v2/graphql",
+    rest: "https://us.xray.cloud.getxray.app/api/v2",
+    auth: "https://xray.cloud.getxray.app/api/v2/authenticate",
+  },
+  eu: {
+    graphql: "https://eu.xray.cloud.getxray.app/api/v2/graphql",
+    rest: "https://eu.xray.cloud.getxray.app/api/v2",
+    auth: "https://xray.cloud.getxray.app/api/v2/authenticate",
+  },
+  au: {
+    graphql: "https://au.xray.cloud.getxray.app/api/v2/graphql",
+    rest: "https://au.xray.cloud.getxray.app/api/v2",
+    auth: "https://xray.cloud.getxray.app/api/v2/authenticate",
+  },
+};
 
 /**
  * Load configuration from .env file and optional .xrayrc JSON file.
@@ -49,18 +60,30 @@ export function loadConfig(opts = {}) {
     }
   }
 
+  // Resolve Xray region endpoints
+  const region = (process.env.XRAY_REGION || rcConfig.xrayRegion || "us").toLowerCase();
+  const regionEndpoints = XRAY_REGIONS[region] || XRAY_REGIONS.us;
+
+  // Valid environments list
+  const defaultEnvironments = ["IOP-DEV", "IOP-QA", "IOP-PROD"];
+
   const cfg = {
     // Xray Cloud
     xrayId: process.env.XRAY_ID || rcConfig.xrayId,
     xraySecret: process.env.XRAY_SECRET || rcConfig.xraySecret,
+    xrayRegion: region,
     xrayGraphqlUrl:
       process.env.XRAY_GRAPHQL_URL ||
       rcConfig.xrayGraphqlUrl ||
-      "https://us.xray.cloud.getxray.app/api/v2/graphql",
+      regionEndpoints.graphql,
+    xrayRestUrl:
+      process.env.XRAY_REST_URL ||
+      rcConfig.xrayRestUrl ||
+      regionEndpoints.rest,
     xrayAuthUrl:
       process.env.XRAY_AUTH_URL ||
       rcConfig.xrayAuthUrl ||
-      "https://xray.cloud.getxray.app/api/v2/authenticate",
+      regionEndpoints.auth,
 
     // JIRA
     jiraProjectKey: process.env.JIRA_PROJECT_KEY || rcConfig.jiraProjectKey,
@@ -68,12 +91,17 @@ export function loadConfig(opts = {}) {
     jiraApiToken: process.env.JIRA_API_TOKEN || rcConfig.jiraApiToken,
     jiraEmail: process.env.JIRA_EMAIL || rcConfig.jiraEmail,
 
+    // Test Plan & environments (per-repo config)
+    testPlanKey: process.env.XQT_TEST_PLAN_KEY || rcConfig.testPlanKey || null,
+    defaultEnvironment: process.env.XQT_DEFAULT_ENV || rcConfig.defaultEnvironment || "IOP-DEV",
+    environments: rcConfig.environments || defaultEnvironments,
+    folderRoot: rcConfig.folderRoot || null,
+
     // 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"),
+    resourcesPath: path.resolve(cwd, rcConfig.resourcesPath || "resources"),
+    playwrightDir: path.resolve(cwd, rcConfig.playwrightDir || "tests"),
   };
 
   return Object.freeze(cfg);
@@ -106,3 +134,12 @@ export function validateConfig(cfg) {
     );
   }
 }
+
+/**
+ * Get the list of valid test environments from config.
+ * @param {object} cfg
+ * @returns {string[]}
+ */
+export function getEnvironments(cfg) {
+  return cfg.environments || ["IOP-DEV", "IOP-QA", "IOP-PROD"];
+}

package/lib/index.js

@@ -5,27 +5,66 @@
  * Consumers can also use the CLI (bin/cli.js) for interactive workflows.
  */
 
-export { loadConfig, validateConfig } from "./config.js";
+export { loadConfig, validateConfig, getEnvironments } from "./config.js";
 export { default as logger, setVerbose } from "./logger.js";
 export {
+  // Auth
   authenticate,
+  // JIRA REST
   createIssue,
   updateIssue,
   getIssue,
+  // GraphQL — test queries
+  getTest,
+  getTests,
+  getTestPlan,
+  getTestPlans,
+  getTestExecution,
+  getTestRuns,
+  getFolder,
+  getProjectSettings,
+  // GraphQL — test mutations
+  setTestType,
   setTestTypeAutomated,
   addTestStep,
   removeAllTestSteps,
+  updateTestDefinition,
+  updateTestFolder,
+  // GraphQL — test plan mutations
+  createTestPlan,
+  addTestsToTestPlan,
+  removeTestsFromTestPlan,
+  // GraphQL — folder mutations
+  createFolder,
+  addTestsToFolder,
+  // GraphQL — execution mutations
+  addTestEnvironmentsToTestExecution,
+  addTestsToTestExecution,
+  // High-level helpers
+  createTestExecution,
+  // Linking
   linkIssues,
   linkMultiple,
+  // Xray REST v2 — import
   importResults,
+  importResultsXrayJson,
+  importResultsMultipart,
+  // Xray REST v2 — bulk test import
+  importTestsBulk,
+  checkImportJobStatus,
+  waitForImportJob,
+  // Xray REST v2 — attachments
+  addAttachment,
+  getAttachment,
+  // Utilities
   withRetry,
   toAdf,
 } from "./xrayClient.js";
 export {
   buildAndPush,
-  createExecutionAndLink,
-  linkToExistingExecution,
+  syncTestPlan,
+  syncFolders,
   loadMapping,
   saveMapping,
 } from "./testCaseBuilder.js";
-export { generate as generatePostmanCollection } from "./postmanGenerator.js";
+