@msalaam/xray-qe-toolkit 1.4.0 → 1.5.0

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * @msalaam/xray-qe-toolkit — CLI Entry Point
@@ -7,17 +7,18 @@
  *   npx xqt <command> [options]
  *
  * Commands:
- *   init               Scaffold tests.json, xray-mapping.json, knowledge/ folder, .env.example
- *   gen-tests          Generate test cases from knowledge/ using AI
- *   edit-json          Launch browser-based QE review gate editor
- *   push-tests         Push / update tests in Xray Cloud
- *   gen-postman        Generate Postman collection from tests.json (with optional AI)
- *   create-execution   Create a new Test Execution in JIRA
- *   import-results     Import test results (JUnit XML or Playwright JSON) into Xray
- *   gen-pipeline       Generate an Azure Pipelines YAML template
- *   mcp-server         Start Model Context Protocol server for agent integration
- *   compare-openapi    Compare OpenAPI specs and fail if breaking changes are detected
- *   update-snapshot    Overwrite the QA snapshot baseline with the current spec
+ *   init       Scaffold project structure (tests/, playwright.config.ts, tests.json, .xrayrc)
+ *   edit       Launch browser-based editor for tests.json
+ *   push       Push/update tests in Xray Cloud + sync Test Plan + sync folders
+ *   pull       Pull test definitions from Xray Cloud into tests.json
+ *   exec       Create a new Test Execution with a specific set of tests
+ *   import     Import test results (JUnit XML or Playwright JSON) — new execution per run
+ *   plan       Create a new Xray Test Plan in JIRA
+ *   sync       Sync Xray repository folder structure from tests.json folder fields
+ *   status     Show local + remote project status summary
+ *   validate   Validate tests.json against its schema
+ *   pipeline   Generate Azure Pipelines YAML
+ *   mcp        Start the MCP server for GitHub Copilot agent-mode integration
  */
 
 import { Command } from "commander";
@@ -32,8 +33,8 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"),
 const program = new Command();
 
 program
-  .name("xray-qe")
-  .description("QE workflow toolkit for Xray Cloud — test management, Postman generation, and CI integration")
+  .name("xqt")
+  .description("QE workflow toolkit for Xray Cloud — test management, CI integration, and test planning")
   .version(pkg.version)
   .option("--verbose", "Enable debug output")
   .option("--env <path>", "Custom path to .env file");
@@ -42,121 +43,154 @@ program
 
 program
   .command("init")
-  .description("Initialize a new project with knowledge/ folder, tests.json, xray-mapping.json, and .env.example")
+  .description(
+    "Scaffold a QA project: resources/, tests/, playwright.config.ts, tests.json, .xrayrc, XQT-GUIDE.md"
+  )
   .action(async (opts, cmd) => {
     const mod = await import("../commands/init.js");
     await mod.default(cmd.optsWithGlobals());
   });
 
 program
-  .command("gen-tests")
-  .description("Generate test cases from knowledge/ folder using AI")
-  .option("--ai", "Enable AI-assisted generation (requires connected provider)")
-  .option("--spec <path>", "OpenAPI/Swagger spec file to analyze")
-  .option("--knowledge <path>", "Custom knowledge folder path")
-  .option("--ticket <key>", "JIRA ticket key to fetch and analyze")
-  .option("--prompt <text>", "Natural language prompt for test generation")
+  .command("edit")
+  .description("Launch browser-based editor for tests.json")
+  .option("--port <number>", "Port for local editor server", "0")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/genTests.js");
+    const mod = await import("../commands/editJson.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("edit-json")
-  .description("Launch browser-based QE review gate editor for tests.json")
-  .option("--port <number>", "Port for the local editor server", "0")
+  .command("push")
+  .alias("push-tests")
+  .description(
+    "Create/update tests in Xray Cloud, sync to Test Plan, sync folder structure"
+  )
+  .option("--plan <key>", "Test Plan key (overrides .xrayrc testPlanKey)")
+  .option("--create-execution", "Create a Test Execution linked to the Test Plan after pushing")
+  .option("--execution-env <label>", "Environment label for created execution (e.g. IOP-QA)")
+  .option("--execution-summary <text>", "Custom summary for created execution")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/editJson.js");
+    const mod = await import("../commands/pushTests.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("push-tests")
-  .description("Push or update tests in Xray Cloud from tests.json")
-  .option("--testExecKey <key>", "Link tests to an existing Test Execution key instead of creating a new one")
-  .option("--skip-exec", "Push tests without creating or linking a Test Execution")
+  .command("pull")
+  .alias("pull-tests")
+  .description("Pull test definitions from Xray Cloud into tests.json")
+  .option("--plan <key>", "Fetch tests from a specific Test Plan")
+  .option("--project <key>", "Fetch all tests in a JIRA project")
+  .option("--limit <n>", "Maximum number of tests to fetch (default: 100)")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/pushTests.js");
+    const mod = await import("../commands/pullTests.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("gen-postman")
-  .description("Generate a Postman collection from tests.json (with optional AI enhancement)")
-  .option("--base-url <url>", "Base URL for API requests", "{{baseUrl}}")
-  .option("--ai", "Enable AI-assisted generation for better assertions")
-  .option("--spec <path>", "OpenAPI/Swagger spec file for schema-driven generation")
-  .option("--knowledge <path>", "Custom knowledge folder path")
+  .command("exec")
+  .alias("create-execution")
+  .description(
+    "Create a new Test Execution with a specific set of tests. " +
+    "Use --quiet to print only the execution key for CI variable capture: " +
+    "EXEC_KEY=$(xqt exec --env IOP-QA --quiet)"
+  )
+  .option("--env <environment>", "Environment label (e.g. IOP-QA, IOP-PROD)")
+  .option("--plan <key>", "Test Plan key to link the execution to (overrides .xrayrc)")
+  .option("--tests <ids>", "Comma-separated testIds or JIRA keys to include (default: all mapped tests)")
+  .option("--summary <text>", "Custom Test Execution summary")
+  .option("--description <text>", "Custom description")
+  .option("--quiet", "Print ONLY the execution key (for CI variable capture)")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/genPostman.js");
+    const mod = await import("../commands/createExecution.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("create-execution")
-  .description("Create a new Test Execution issue in JIRA")
-  .requiredOption("--summary <text>", "Test Execution summary/title")
-  .option("--description <text>", "Test Execution description")
-  .option("--issue <key>", "Parent issue key to link the execution to")
+  .command("import")
+  .alias("import-results")
+  .description(
+    "Import test results into Xray Cloud — creates a NEW Test Execution per run (JUnit XML or Playwright JSON)"
+  )
+  .requiredOption("--file <path>", "Path to results file (.json for Playwright, .xml for JUnit)")
+  .option("--env <environment>", "Test environment label (e.g. IOP-DEV, IOP-QA, IOP-PROD)")
+  .option("--plan <key>", "Test Plan key to associate execution with (overrides .xrayrc)")
+  .option("--exec <key>", "Import INTO an existing Test Execution key (from xqt exec)")
+  .option("--version <version>", "Fix version / release version")
+  .option("--revision <revision>", "Revision / build number")
+  .option("--summary <text>", "Custom Test Execution summary")
+  .option("--description <text>", "Custom Test Execution description")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/createExecution.js");
+    const mod = await import("../commands/importResults.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("import-results")
-  .description("Import test results into Xray Cloud (JUnit XML or Playwright JSON)")
-  .requiredOption("--file <path>", "Path to the results file (.xml for JUnit, .json for Playwright)")
-  .option("--testExecKey <key>", "Test Execution key to associate results with (creates new if omitted)")
-  .option("--summary <text>", "Test Execution summary (for new executions)")
-  .option("--description <text>", "Test Execution description (for new executions)")
+  .command("plan")
+  .alias("create-plan")
+  .description("Create a new Test Plan in JIRA and save its key to .xrayrc and tests.json")
+  .requiredOption("--summary <text>", "Test Plan summary / title")
+  .option("--version <version>", "Fix version to associate with the plan")
+  .option("--label <labels>", "Comma-separated labels to apply")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/importResults.js");
+    const mod = await import("../commands/createPlan.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("gen-pipeline")
-  .description("Generate an Azure Pipelines YAML template")
-  .option("--output <path>", "Output file path", "azure-pipelines.yml")
+  .command("sync")
+  .alias("sync-folders")
+  .description("Sync Xray repository folder structure from the folder field in tests.json")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/genPipeline.js");
+    const mod = await import("../commands/syncFolders.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("mcp-server")
-  .description("Start Model Context Protocol server for Copilot agent integration")
-  .option("--port <number>", "Server port (default: stdio mode)")
+  .command("status")
+  .description("Show local and remote project status (tests.json, mapping, Test Plan)")
+  .option("--plan <key>", "Test Plan key to check (overrides .xrayrc)")
   .action(async (opts, cmd) => {
-    const mod = await import("../mcp/server.js");
+    const mod = await import("../commands/status.js");
+    await mod.default({ ...opts, ...cmd.optsWithGlobals() });
+  });
+
+program
+  .command("validate")
+  .description("Validate tests.json and business-rules.yaml against their schemas (exits 1 on errors)")
+  .option("--file <path>", "Override path to tests.json")
+  .option("--schema <name>", "Validate only one schema: tests | business-rules | all (default: all)")
+  .action(async (opts, cmd) => {
+    const mod = await import("../commands/validate.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("compare-openapi")
-  .description("Compare OpenAPI specs against a QA snapshot and fail if breaking changes are detected")
-  .requiredOption("--current <path>", "Path to the current (live) OpenAPI spec")
-  .requiredOption("--snapshot <path>", "Path to the approved QA snapshot")
-  .option("--report <path>", "Write a JSON diff report to this path (useful as a pipeline artifact)")
+  .command("pipeline")
+  .alias("gen-pipeline")
+  .description("Generate an Azure Pipelines YAML template")
+  .option("--output <path>", "Output file path", "azure-pipelines.yml")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/compareOpenapi.js");
+    const mod = await import("../commands/genPipeline.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("update-snapshot")
-  .description("Overwrite the QA snapshot baseline with the current spec (always a deliberate, manual action)")
-  .requiredOption("--current <path>", "Path to the current (live) OpenAPI spec to promote")
-  .requiredOption("--snapshot <path>", "Path to the snapshot file to overwrite")
+  .command("mcp")
+  .alias("mcp-server")
+  .description(
+    "Start the MCP server for GitHub Copilot agent-mode integration. " +
+    "Runs in stdio mode by default (for VS Code), or HTTP mode with --port."
+  )
+  .option("--port <number>", "Run in HTTP / StreamableHTTP mode on the given port")
   .action(async (opts, cmd) => {
-    const mod = await import("../commands/updateSnapshot.js");
+    const mod = await import("../mcp/server.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 // ─── Parse & run ───────────────────────────────────────────────────────────────
 
 program.parseAsync(process.argv).catch((err) => {
-  console.error(`\n❌ ${err.message}\n`);
+  console.error(`\n${err.message}\n`);
   process.exit(1);
-});
+});

package/commands/createExecution.js

@@ -1,46 +1,135 @@
 /**
- * Command: xray-qe create-execution --summary "..." [--description "..."] [--issue QE-123]
+ * Command: xqt create-execution
  *
- * Creates a standalone Test Execution issue in JIRA.
- * Optionally links it to a parent issue via --issue.
+ * Creates a new Xray Test Execution in JIRA with a defined set of tests.
+ *
+ * Use this when you want to PRE-CREATE an execution (to control which tests
+ * are included, set fields up-front, or know the execution key before running).
+ * Then run your tests and import results with:
+ *   xqt import-results --file results.json --exec <key>
+ *
+ * Alternatively, skip this command entirely — `xqt import-results` without
+ * --exec will auto-create a fresh execution from the results automatically.
+ *
+ * Usage examples:
+ *   # Create from all tests in the Test Plan (default):
+ *   xqt create-execution --env IOP-QA
+ *
+ *   # Create from a specific plan with a custom summary:
+ *   xqt create-execution --env IOP-PROD --plan APIEE-1234 --summary "Release 2.5 smoke"
+ *
+ *   # Create and only include specific tests (comma-separated testIds):
+ *   xqt create-execution --env IOP-QA --tests TC-API-001,TC-API-002,TC-API-003
+ *
+ *   # Print only the execution key (for CI variable capture):
+ *   EXEC_KEY=$(xqt create-execution --env IOP-QA --quiet)
  */
 
+import fs from "node:fs";
 import logger, { setVerbose } from "../lib/logger.js";
 import { loadConfig, validateConfig } from "../lib/config.js";
-import { createIssue, linkIssues } from "../lib/xrayClient.js";
+import { authenticate, createTestExecution, getIssue } from "../lib/xrayClient.js";
+import { loadMapping } from "../lib/testCaseBuilder.js";
 
 export default async function createExecution(opts = {}) {
   if (opts.verbose) setVerbose(true);
 
-  logger.rocket("@msalaam/xray-qe-toolkit — Create Execution\n");
+  const quiet = opts.quiet || false;
+
+  if (!quiet) logger.rocket("@msalaam/xray-qe-toolkit — Create Test Execution\n");
 
   const cfg = loadConfig({ envPath: opts.env });
   validateConfig(cfg);
 
-  logger.pin(`Creating Test Execution: "${opts.summary}"...`);
+  // ── Resolve environment ────────────────────────────────────────────────────
+  const environment = opts.environment || cfg.defaultEnvironment || "IOP-DEV";
+  const environments = [environment];
 
-  const execution = await createIssue(cfg, "Test Execution", {
-    summary: opts.summary,
-    description: opts.description || opts.summary,
-  });
-
-  logger.success(`${execution.key} created`);
-  logger.link(`View: ${cfg.jiraUrl}/browse/${execution.key}`);
+  // ── Resolve plan key ───────────────────────────────────────────────────────
+  let planKey = opts.plan || cfg.testPlanKey;
+  if (!opts.plan) {
+    // Also check tests.json for testPlan.key
+    if (fs.existsSync(cfg.testsPath)) {
+      const testsConfig = JSON.parse(fs.readFileSync(cfg.testsPath, "utf8"));
+      planKey = planKey || testsConfig.testPlan?.key;
+    }
+  }
 
-  // Optionally link to parent issue
-  if (opts.issue) {
+  if (!quiet) {
+    logger.info(`Environment: ${environment}`);
+    if (planKey) logger.info(`Test Plan:   ${planKey}`);
     logger.blank();
-    logger.link(`Linking to ${opts.issue}...`);
-    try {
-      await linkIssues(cfg, execution.key, opts.issue);
-      logger.step(`Linked to ${opts.issue}`);
-    } catch (err) {
-      logger.warn(`Could not link: ${err.message}`);
+  }
+
+  // ── Authenticate ───────────────────────────────────────────────────────────
+  const xrayToken = await authenticate(cfg);
+
+  // ── Resolve which tests to include ────────────────────────────────────────
+  let testIssueIds = [];
+
+  if (opts.tests) {
+    // User specified specific test IDs (local testId values or JIRA keys)
+    const mapping = loadMapping(cfg.mappingPath);
+    const requestedIds = opts.tests.split(",").map((s) => s.trim());
+
+    for (const id of requestedIds) {
+      const entry = mapping[id];
+      if (entry?.id) {
+        testIssueIds.push(String(entry.id));
+      } else {
+        // Might be a JIRA key — look it up
+        try {
+          const issue = await getIssue(cfg, id);
+          if (issue?.id) testIssueIds.push(String(issue.id));
+          else if (!quiet) logger.warn(`Could not resolve test ID: ${id}`);
+        } catch {
+          if (!quiet) logger.warn(`Skipping unresolvable test ID: ${id}`);
+        }
+      }
     }
+
+    if (!quiet) logger.info(`Using ${testIssueIds.length}/${requestedIds.length} specified test(s)`);
+  } else if (planKey) {
+    // Default: pull all test IDs from the plan via mapping
+    const mapping = loadMapping(cfg.mappingPath);
+    testIssueIds = Object.values(mapping)
+      .filter((v) => v.id && !String(v.id).startsWith("_"))
+      .map((v) => String(v.id));
+
+    if (!quiet) logger.info(`Using all ${testIssueIds.length} mapped test(s) from plan`);
   }
 
+  // ── Build summary ──────────────────────────────────────────────────────────
+  const summary =
+    opts.summary ||
+    `${environment} Test Run — ${new Date().toLocaleString()}`;
+
+  // ── Create execution ───────────────────────────────────────────────────────
+  if (!quiet) logger.send("Creating Test Execution...");
+
+  const { key, id } = await createTestExecution(cfg, xrayToken, {
+    summary,
+    description: opts.description,
+    environments,
+    testIssueIds,
+    testPlanKey: planKey || undefined,
+  });
+
+  if (quiet) {
+    // Output only the key — suitable for CI variable capture:
+    // EXEC_KEY=$(xqt create-execution --env IOP-QA --quiet)
+    process.stdout.write(key + "\n");
+    return;
+  }
+
+  logger.blank();
+  logger.success(`Test Execution created: ${key}`);
+  logger.link(`${cfg.jiraUrl}/browse/${key}`);
   logger.blank();
-  console.log(`Test Execution Key: ${execution.key}`);
-  console.log(`Test Execution ID:  ${execution.id}`);
+
+  console.log("Next steps:");
+  console.log(`  1. Run your tests (e.g. npx playwright test)`);
+  console.log(`  2. Import results into this execution:`);
+  console.log(`     xqt import-results --file test-results/results.json --exec ${key}`);
   logger.blank();
 }

package/commands/createPlan.js

@@ -0,0 +1,110 @@
+/**
+ * Command: xqt create-plan --summary <text> [--version <ver>]
+ *
+ * Creates a new Xray Test Plan in JIRA, then writes its key to .xrayrc
+ * and to the testPlan.key field in tests.json.
+ *
+ * Usage examples:
+ *   xqt create-plan --summary "Payments v2.0 Regression"
+ *   xqt create-plan --summary "Sprint 12 Smoke" --version "2024.12"
+ */
+
+import fs from "node:fs";
+import logger, { setVerbose } from "../lib/logger.js";
+import { loadConfig, validateConfig } from "../lib/config.js";
+import { authenticate, createIssue, createTestPlan, getIssue } from "../lib/xrayClient.js";
+
+export default async function createPlan(opts = {}) {
+  if (opts.verbose) setVerbose(true);
+
+  logger.rocket("@msalaam/xray-qe-toolkit — Create Test Plan\n");
+
+  const cfg = loadConfig({ envPath: opts.env });
+  validateConfig(cfg);
+
+  const summary = opts.summary;
+  if (!summary) {
+    logger.error("--summary is required");
+    logger.info("Usage: xqt create-plan --summary 'My Test Plan'");
+    process.exit(1);
+  }
+
+  logger.info(`Summary:  ${summary}`);
+  if (opts.version) logger.info(`Version:  ${opts.version}`);
+  if (opts.label)   logger.info(`Labels:   ${opts.label}`);
+  logger.blank();
+
+  // ── Authenticate ───────────────────────────────────────────────────────────
+  const xrayToken = await authenticate(cfg);
+
+  // ── Create the Test Plan via JIRA REST ────────────────────────────────────
+  logger.send("Creating Test Plan in JIRA...");
+
+  let planKey;
+  try {
+    const fields = {
+      summary,
+      description: summary,
+      ...(opts.label && {
+        labels: opts.label.split(",").map((l) => l.trim()),
+      }),
+    };
+
+    const issue = await createIssue(cfg, "Test Plan", fields);
+    planKey = issue.key;
+  } catch (err) {
+    // Fallback: try via Xray GraphQL createTestPlan mutation
+    logger.debug(`JIRA REST failed, trying Xray GraphQL: ${err.message}`);
+    try {
+      const result = await createTestPlan(cfg, xrayToken, {
+        projectId: cfg.jiraProjectKey,
+        summary,
+        description: summary,
+      });
+
+      // GraphQL returns { testPlan: { issueId, projectId } } — resolve key via JIRA
+      const issueId = result?.testPlan?.issueId;
+      if (issueId) {
+        try {
+          const issue = await getIssue(cfg, issueId);
+          planKey = issue?.key;
+        } catch {
+          logger.debug(`Could not resolve JIRA key for issueId ${issueId}`);
+        }
+      }
+    } catch (gqlErr) {
+      logger.error(`Could not create Test Plan: ${gqlErr.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (!planKey) {
+    logger.error("Test Plan created but no key was returned. Check JIRA.");
+    process.exit(1);
+  }
+
+  logger.success(`Test Plan created: ${planKey}`);
+  logger.link(`${cfg.jiraUrl}/browse/${planKey}`);
+  logger.blank();
+
+  // ── Update .xrayrc ─────────────────────────────────────────────────────────
+  const xrayrcPath = ".xrayrc";
+  if (fs.existsSync(xrayrcPath)) {
+    const xrayrc = JSON.parse(fs.readFileSync(xrayrcPath, "utf8"));
+    xrayrc.testPlanKey = planKey;
+    fs.writeFileSync(xrayrcPath, JSON.stringify(xrayrc, null, 2));
+    logger.save(`.xrayrc updated with testPlanKey: ${planKey}`);
+  }
+
+  // ── Update tests.json ──────────────────────────────────────────────────────
+  if (fs.existsSync(cfg.testsPath)) {
+    const testsConfig = JSON.parse(fs.readFileSync(cfg.testsPath, "utf8"));
+    testsConfig.testPlan = { key: planKey, summary };
+    fs.writeFileSync(cfg.testsPath, JSON.stringify(testsConfig, null, 2));
+    logger.save(`tests.json updated with testPlan.key: ${planKey}`);
+  }
+
+  logger.blank();
+  logger.success("Done — run 'xqt push-tests' to sync your tests to this plan");
+  logger.blank();
+}

package/commands/editJson.js

@@ -1,5 +1,5 @@
 /**
- * Command: xray-qe edit-json [--port <number>]
+ * Command: xqt edit [--port <number>]
  *
  * QE Review Gate — launches a local Express server with a browser-based
  * JSON editor that lets QEs:

package/commands/genPipeline.js

@@ -40,6 +40,6 @@ export default async function genPipeline(opts = {}) {
   console.log("   5. Playwright tests must have xray annotations to map results:");
   console.log("      test.info().annotations.push({ type: 'xray', description: 'PROJ-123' })");
   console.log("");
-  console.log("⚠️  Remember: edit-json and QE review gates are NOT part of CI.");
+  console.log("⚠️  Remember: xqt edit and QE review gates are NOT part of CI.");
   console.log("   Run those steps locally before committing.\n");
 }