@msalaam/xray-qe-toolkit 1.5.0 → 1.6.0

package/README.md

@@ -255,6 +255,7 @@ npx xqt exec --env IOP-QA --plan APIEE-1234 --tests TC-001,TC-002
 | `--plan <key>` | Test Plan to link to (overrides `.xrayrc`) |
 | `--tests <ids>` | Comma-separated testIds or JIRA keys (default: all mapped) |
 | `--summary <text>` | Custom execution title |
+| `--fix-version <ver>` | JIRA Fix Version to stamp on the execution (e.g. `2.5.0`) |
 | `--quiet` | Print only the execution key |
 
 > `xqt import` creates an execution automatically — this command is only needed when pre-selecting a specific subset of tests.
@@ -281,12 +282,12 @@ npx xqt import --file test-results/results.json --exec APIEE-9876
 # JUnit XML
 npx xqt import --file test-results/results.xml --env IOP-PROD
 
-# Full options
+# Full options — with Fix Version and git SHA
 npx xqt import \
   --file test-results/results.json \
   --env IOP-QA \
   --plan APIEE-1234 \
-  --version "2024.12" \
+  --fix-version "2.5.0" \
   --revision "a1b2c3d4"
 ```
 
@@ -296,7 +297,8 @@ npx xqt import \
 | `--env <label>` | Environment label (default: `defaultEnvironment` from `.xrayrc`) |
 | `--plan <key>` | Test Plan key (overrides `.xrayrc`; used when no `--exec`) |
 | `--exec <key>` | Import INTO an existing execution (from `xqt exec`) |
-| `--version <ver>` | Fix version / release label |
+| `--fix-version <ver>` | JIRA Fix Version name to stamp on the execution (e.g. `2.5.0`) |
+| `--version <ver>` | Xray version label (free-form, separate from Fix Version) |
 | `--revision <rev>` | Build number or git SHA |
 | `--summary <text>` | Custom execution summary |
 
@@ -394,23 +396,53 @@ JIRA_EMAIL=your.email@company.com
 
 ```json
 {
-  "testsPath":          "tests.json",
-  "mappingPath":        "xray-mapping.json",
-  "testPlanKey":        "APIEE-1234",
-  "defaultEnvironment": "IOP-DEV",
-  "environments":       ["IOP-DEV", "IOP-QA", "IOP-PROD"],
-  "folderRoot":         "/MyService",
-  "xrayRegion":         "us"
+  "testsPath":            "tests.json",
+  "mappingPath":          "xray-mapping.json",
+  "testPlanKey":          "APIEE-1234",
+  "defaultEnvironment":   "IOP-DEV",
+  "environments":         ["IOP-DEV", "IOP-QA", "IOP-PROD"],
+  "folderRoot":           "/MyService",
+  "xrayRegion":           "us",
+  "bulkImportThreshold":  50,
+  "statusMapping": {
+    "interrupted": "ABORTED",
+    "skipped":     "TODO"
+  }
 }
 ```
 
 | Field | Description |
 |---|---|
-| `testPlanKey` | Default Test Plan key for push-tests and import-results |
+| `testPlanKey` | Default Test Plan key for `push` and `import` |
 | `defaultEnvironment` | Fallback environment when `--env` is not provided |
 | `environments` | Allowed environment labels |
 | `folderRoot` | Base folder path in Xray Test Repository |
-| `xrayRegion` | `us` (default) or `eu` |
+| `xrayRegion` | `us` (default), `eu`, or `au` |
+| `bulkImportThreshold` | Min new-test count to use the Xray bulk REST API (default: `50`) — faster for large suites |
+| `statusMapping` | Override default Playwright → Xray status mapping (see below) |
+
+#### Playwright status mapping
+
+By default the converter maps:
+
+| Playwright status | Xray status |
+|---|---|
+| `passed` | `PASSED` |
+| `failed` | `FAILED` |
+| `timedOut` | `FAILED` |
+| `interrupted` | `ABORTED` |
+| `skipped` | `TODO` |
+
+Override any value in `.xrayrc`:
+
+```json
+{
+  "statusMapping": {
+    "skipped": "TODO",
+    "interrupted": "FAILED"
+  }
+}
+```
 
 ---
 
@@ -432,6 +464,7 @@ JIRA_EMAIL=your.email@company.com
       "tags": ["smoke", "regression"],
       "folder": "/MyService/HealthCheck/Validation",
       "testSet": "Health Check",
+      "preconditions": ["APIEE-50"],
       "requirementKeys": [],
       "xray": {
         "summary": "Service returns 200 OK when healthy",
@@ -455,7 +488,8 @@ JIRA_EMAIL=your.email@company.com
 | `skip` | boolean | — | `true` to exclude from `push-tests` |
 | `tags` | string[] | — | QE tags for categorisation and filtering. Allowed: `regression`, `smoke`, `edge`, `critical`, `integration`, `e2e`, `security`, `performance`, `contract`, `functional`, `negative`, `positive`, `boundary`, `acceptance`, `sanity`, `data-driven`, `exploratory`, `accessibility` |
 | `folder` | string | — | Xray repository folder path — must start with `/` |
-| `testSet` | string | — | Test Set name in Jira — tests are grouped into Test Sets by this value |
+| `testSet` | string **or** string[] | — | Test Set name(s) in Jira — a single string or an array to assign the test to multiple Test Sets |
+| `preconditions` | string[] | — | JIRA keys of Xray Precondition issues to link to this test (e.g. `["APIEE-50"]`) |
 | `requirementKeys` | string[] | — | JIRA keys this test covers (creates traceability links) |
 | `xray.summary` | string | Yes | Test case title (JIRA issue summary) |
 | `xray.description` | string | — | Detailed description |
@@ -472,17 +506,17 @@ JIRA_EMAIL=your.email@company.com
 
 Tests live in **Test Sets** in Jira. Each Test Set groups related tests by feature or area — they persist across every sprint.
 
-Set the `testSet` field on each test in `tests.json`:
+Set the `testSet` field on each test in `tests.json` — use a string or an array of strings to assign the test to multiple sets:
 
 ```json
 { "test_id": "TC-001", "testSet": "Client Lookup", ... }
 { "test_id": "TC-002", "testSet": "Client Lookup", ... }
-{ "test_id": "TC-003", "testSet": "Health Check",  ... }
+{ "test_id": "TC-003", "testSet": ["Health Check", "Smoke"], ... }
 ```
 
 When you run `xqt push`:
 1. Tests are created/updated in Xray
-2. For each unique `testSet` value, the Test Set JIRA issue is **created automatically** if it doesn't exist yet
+2. For each unique `testSet` value, the Test Set JIRA issue is **created automatically** if it doesn't exist yet (safe to run on a fresh clone — existing sets are found by name, not duplicated)
 3. Tests are added to their Test Set (idempotent — Xray ignores tests already in the set)
 4. Test Set → JIRA key mappings (e.g. `"Client Lookup" → APIEE-99`) are stored in `xray-mapping.json` under `_testSets`
 
@@ -509,6 +543,8 @@ A Test Plan scopes testing work for a specific sprint or release.
 - Key stored in `.xrayrc` (`testPlanKey`)
 - `xqt import` links executions to the active plan
 
+`xqt push` performs a **bi-directional sync** with the Test Plan: new tests are added **and** tests removed from `tests.json` are removed from the plan. Use `--plan <key>` to override the key.
+
 ### Test Executions (ephemeral per run)
 
 A Test Execution represents a single CI run.
@@ -582,7 +618,7 @@ reporter: [
 
 ### Test steps → Xray step results
 
-Steps created with `test.step()` are mapped to Xray step results automatically:
+Steps created with `test.step()` are mapped to Xray step results automatically. Screenshots captured on a **failing step** are attached directly to that step's evidence in Xray — giving per-step failure screenshots in the Xray UI. Traces and other attachments are attached at the test level.
 
 ```typescript
 test('Create and retrieve user', async ({ request }) => {
@@ -636,7 +672,9 @@ Generate a template: `npx xqt pipeline`
 - script: |
     npx xqt import \
       --file test-results/results.json \
-      --env $(XQT_ENV)
+      --env $(XQT_ENV) \
+      --fix-version $(BUILD_BUILDNUMBER) \
+      --revision $(Build.SourceVersion)
   displayName: Import results to Xray
   env:
     XRAY_ID:          $(XRAY_ID)
@@ -658,6 +696,7 @@ Generate a template: `npx xqt pipeline`
 | `JIRA_API_TOKEN` | JIRA API token |
 | `JIRA_EMAIL` | JIRA user email |
 | `XQT_ENV` | Environment label (`IOP-DEV` / `IOP-QA` / `IOP-PROD`) |
+| `XQT_BULK_THRESHOLD` | Override bulk-import threshold (default: `50`) |
 
 ### Pre-create execution in pipeline (Mode B)
 
@@ -701,7 +740,7 @@ const { key } = await createTestExecution(cfg, token, {
 });
 ```
 
-Key exports: `authenticate`, `createIssue`, `updateIssue`, `getIssue`, `getTest`, `getTests`, `getTestPlan`, `createTestPlan`, `addTestsToTestPlan`, `addTestsToTestExecution`, `createTestExecution`, `importResultsMultipart`, `importTestsBulk`, `syncTestPlan`, `syncFolders`, `buildAndPush`, `loadMapping`, `saveMapping`, `loadConfig`, `validateConfig`.
+Key exports: `authenticate`, `createIssue`, `updateIssue`, `getIssue`, `getTest`, `getTests`, `getTestPlan`, `createTestPlan`, `addTestsToTestPlan`, `removeTestsFromTestPlan`, `addTestsToTestExecution`, `createTestExecution`, `importResultsMultipart`, `importTestsBulk`, `waitForImportJob`, `searchIssues`, `getTestSets`, `addPreconditionsToTest`, `syncTestPlan`, `syncFolders`, `buildAndPush`, `loadMapping`, `saveMapping`, `loadConfig`, `validateConfig`.
 
 ---
 

package/bin/cli.js

@@ -100,6 +100,7 @@ program
   .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("--fix-version <version>", "JIRA Fix Version to stamp on the execution (e.g. '2.5.0')")
   .option("--quiet", "Print ONLY the execution key (for CI variable capture)")
   .action(async (opts, cmd) => {
     const mod = await import("../commands/createExecution.js");
@@ -117,7 +118,8 @@ program
   .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("--revision <revision>", "Revision / build number (e.g. git SHA)")
+  .option("--fix-version <version>", "JIRA Fix Version name to stamp on the Test Execution (e.g. '2.5.0')")
   .option("--summary <text>", "Custom Test Execution summary")
   .option("--description <text>", "Custom Test Execution description")
   .action(async (opts, cmd) => {

package/commands/createExecution.js

@@ -113,6 +113,7 @@ export default async function createExecution(opts = {}) {
     environments,
     testIssueIds,
     testPlanKey: planKey || undefined,
+    fixVersion: opts.fixVersion || undefined,
   });
 
   if (quiet) {

package/commands/importResults.js

@@ -88,6 +88,7 @@ export default async function importResults(opts = {}) {
     ...(!execKey && planKey && { testPlanKey: planKey }),
     ...(opts.version && { version: opts.version }),
     ...(opts.revision && { revision: opts.revision }),
+    ...(opts.fixVersion && { fixVersion: opts.fixVersion }),
   };
 
   let result;
@@ -101,6 +102,7 @@ export default async function importResults(opts = {}) {
 
     xrayJson = convertPlaywrightToXray(playwrightJson, {
       projectKey: cfg.jiraProjectKey,
+      statusMapping: cfg.statusMapping || undefined,
       infoOverrides: infoBase,
     });
 

package/commands/init.js

@@ -200,6 +200,8 @@ export default async function init(opts = {}) {
       environments: ["IOP-DEV", "IOP-QA", "IOP-PROD"],
       folderRoot: `/${serviceName}`,
       xrayRegion: "us",
+      bulkImportThreshold: 50,
+      // statusMapping: { interrupted: "ABORTED", skipped: "TODO" }
     };
     fs.writeFileSync(xrayrcPath, JSON.stringify(xrayrc, null, 2));
     logger.success(".xrayrc created — Project config");

package/commands/pushTests.js

@@ -19,6 +19,7 @@ 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 { readJsonFile } from "../lib/jsonFile.js";
 import { authenticate, getIssue, createTestExecution } from "../lib/xrayClient.js";
 import {
   buildAndPush,
@@ -44,7 +45,7 @@ export default async function pushTests(opts = {}) {
     process.exit(1);
   }
 
-  const testsConfig = JSON.parse(fs.readFileSync(cfg.testsPath, "utf8"));
+  const testsConfig = readJsonFile(cfg.testsPath);
   const allTests = testsConfig.tests || [];
   const tests = allTests.filter((t) => !t.skip);
   const skippedCount = allTests.length - tests.length;
@@ -61,9 +62,7 @@ export default async function pushTests(opts = {}) {
   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 schema = readJsonFile(new URL("../schema/tests.schema.json", import.meta.url));
     const ajv = new Ajv({ allErrors: true });
     const validate = ajv.compile(schema);
     if (!validate(testsConfig)) {
@@ -103,11 +102,11 @@ export default async function pushTests(opts = {}) {
   logger.save(`Mapping saved to ${cfg.mappingPath}`);
 
   // ── Sync Test Sets ──────────────────────────────────────────────────
-  const testsWithSets = tests.filter((t) => t.testSet);
+  const testsWithSets = tests.filter((t) => t.testSet && (Array.isArray(t.testSet) ? t.testSet.length > 0 : true));
 
   if (testsWithSets.length > 0) {
     logger.blank();
-    const uniqueSets = [...new Set(testsWithSets.map((t) => t.testSet))];
+    const uniqueSets = [...new Set(testsWithSets.flatMap((t) => Array.isArray(t.testSet) ? t.testSet : [t.testSet]))];
     logger.send(`Syncing ${uniqueSets.length} Test Set(s) (${testsWithSets.length} test(s))...`);
     try {
       const setResult = await syncTestSets(cfg, xrayToken, tests, mapping, cfg.mappingPath);

package/lib/config.js

@@ -97,6 +97,13 @@ export function loadConfig(opts = {}) {
     environments: rcConfig.environments || defaultEnvironments,
     folderRoot: rcConfig.folderRoot || null,
 
+    // Playwright status mapping (overrides defaults per-project)
+    // e.g. { "interrupted": "ABORTED", "skipped": "TODO" }
+    statusMapping: rcConfig.statusMapping || null,
+
+    // Bulk import threshold — use Xray REST bulk API when creating this many new tests
+    bulkImportThreshold: Number(process.env.XQT_BULK_THRESHOLD ?? rcConfig.bulkImportThreshold ?? 50),
+
     // Paths (resolved relative to consuming project)
     testsPath: path.resolve(cwd, rcConfig.testsPath || "tests.json"),
     mappingPath: path.resolve(cwd, rcConfig.mappingPath || "xray-mapping.json"),

package/lib/jsonFile.js

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+
+/**
+ * Parse a JSON file and tolerate UTF-8 BOM at file start.
+ * @param {string | URL} filePath
+ * @returns {any}
+ */
+export function readJsonFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const content = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  return JSON.parse(content);
+}

package/lib/playwrightConverter.js

@@ -20,8 +20,10 @@ import path from "node:path";
  * @param {object} playwrightJson - Playwright JSON reporter output
  * @param {object} options - Conversion options
  * @param {string} [options.projectKey]    - JIRA project key (for new test creation)
+ * @param {object} [options.statusMapping] - Override default Playwright→Xray status map
+ *   e.g. { interrupted: "ABORTED", skipped: "TODO" }
  * @param {object} [options.infoOverrides] - Merged into the Xray `info` object:
- *   testPlanKey, testEnvironments, version, revision, summary, description
+ *   testPlanKey, testEnvironments, version, revision, fixVersion, summary, description
  * @returns {object} Xray JSON format ready for import
  */
 export function convertPlaywrightToXray(playwrightJson, options = {}) {
@@ -110,7 +112,7 @@ function convertTest(test, spec, suite, options) {
   const result = test.results[test.results.length - 1];
 
   const testKey = extractTestKey(spec.title, test.annotations);
-  const status = mapStatus(result.status);
+  const status = mapStatus(result.status, options.statusMapping);
 
   const xrayTest = {
     status,
@@ -145,14 +147,16 @@ function convertTest(test, spec, suite, options) {
   }
 
   // ── Map Playwright steps to Xray step results ─────────────────────────────
-  if (result.steps && result.steps.length > 0) {
-    xrayTest.steps = result.steps
-      .filter((s) => s.category === "test.step" || s.category === "hook")
-      .map((s) => ({
-        status: s.error ? "FAILED" : "PASSED",
-        comment: s.title || s.category,
-        ...(s.duration && { duration: Math.round(s.duration) }),
-      }));
+  const relevantSteps = result.steps
+    ? result.steps.filter((s) => s.category === "test.step" || s.category === "hook")
+    : [];
+
+  if (relevantSteps.length > 0) {
+    xrayTest.steps = relevantSteps.map((s) => ({
+      status: s.error ? "FAILED" : "PASSED",
+      comment: s.title || s.category,
+      ...(s.duration && { duration: Math.round(s.duration) }),
+    }));
   }
 
   // ── Error details ──────────────────────────────────────────────────────────
@@ -162,35 +166,34 @@ function convertTest(test, spec, suite, options) {
     xrayTest.comment += `\n\nError: ${msg}${stack}`;
   }
 
-  // ── Attachments / Evidence ────────────────────────────────────────────────
+  // ── Attachments / Evidence (with per-step attachment for screenshots) ──────
   if (result.attachments && result.attachments.length > 0) {
-    xrayTest.evidence = [];
-    for (const attachment of result.attachments) {
-      let data = null;
-
-      if (attachment.body) {
-        // In-memory body (Buffer from Playwright)
-        data = Buffer.isBuffer(attachment.body)
-          ? attachment.body.toString("base64")
-          : Buffer.from(attachment.body).toString("base64");
-      } else if (attachment.path && fs.existsSync(attachment.path)) {
-        // File on disk
-        data = fs.readFileSync(attachment.path).toString("base64");
-      }
+    const screenshots = result.attachments.filter(
+      (a) => a.contentType?.startsWith("image/") || a.name?.match(/screenshot/i)
+    );
+    const traces = result.attachments.filter((a) => a.name?.match(/trace/i));
+    const other = result.attachments.filter(
+      (a) => !screenshots.includes(a) && !traces.includes(a)
+    );
 
-      if (data) {
-        xrayTest.evidence.push({
-          filename: attachment.name || path.basename(attachment.path || "attachment"),
-          contentType: attachment.contentType || "application/octet-stream",
-          data,
-        });
-      }
+    // Find the last failed step index for per-step evidence attachment
+    const lastFailedStepIdx =
+      relevantSteps.reduce((acc, s, i) => (s.error ? i : acc), -1);
+
+    // Attach screenshots to the last failed step (per-step evidence)
+    if (xrayTest.steps && lastFailedStepIdx >= 0 && screenshots.length > 0) {
+      xrayTest.steps[lastFailedStepIdx].evidences = screenshots
+        .map((a) => buildEvidenceItem(a))
+        .filter(Boolean);
     }
 
-    if (xrayTest.evidence.length > 0) {
-      xrayTest.comment += `\n\nAttachments: ${result.attachments.map((a) => a.name).join(", ")}`;
-    } else {
-      delete xrayTest.evidence;
+    // Everything else (traces, other) stays at test level
+    const testLevelAttachments = [...(lastFailedStepIdx >= 0 ? [] : screenshots), ...traces, ...other];
+    const testLevelEvidence = testLevelAttachments.map((a) => buildEvidenceItem(a)).filter(Boolean);
+
+    if (testLevelEvidence.length > 0) {
+      xrayTest.evidence = testLevelEvidence;
+      xrayTest.comment += `\n\nAttachments: ${testLevelAttachments.map((a) => a.name).join(", ")}`;
     }
   }
 
@@ -209,16 +212,36 @@ function extractTestKey(title, annotations) {
   return match ? match[1] : null;
 }
 
-function mapStatus(playwrightStatus) {
-  return (
-    {
-      passed: "PASSED",
-      failed: "FAILED",
-      timedOut: "FAILED",
-      interrupted: "ABORTED",
-      skipped: "TODO",
-    }[playwrightStatus] || "TODO"
-  );
+function mapStatus(playwrightStatus, customMapping) {
+  const defaults = {
+    passed: "PASSED",
+    failed: "FAILED",
+    timedOut: "FAILED",
+    interrupted: "ABORTED",
+    skipped: "TODO",
+  };
+  const map = customMapping ? { ...defaults, ...customMapping } : defaults;
+  return map[playwrightStatus] || "TODO";
+}
+
+function buildEvidenceItem(attachment) {
+  let data = null;
+
+  if (attachment.body) {
+    data = Buffer.isBuffer(attachment.body)
+      ? attachment.body.toString("base64")
+      : Buffer.from(attachment.body).toString("base64");
+  } else if (attachment.path && fs.existsSync(attachment.path)) {
+    data = fs.readFileSync(attachment.path).toString("base64");
+  }
+
+  if (!data) return null;
+
+  return {
+    filename: attachment.name || path.basename(attachment.path || "attachment"),
+    contentType: attachment.contentType || "application/octet-stream",
+    data,
+  };
 }
 
 function buildComment(result, spec, suite) {