@msalaam/xray-qe-toolkit 1.5.0 → 1.6.1

package/lib/xrayClient.js

@@ -90,6 +90,9 @@ export async function createIssue(cfg, issueType, fields) {
       issuetype: { name: issueType },
       ...(fields.priority ? { priority: { name: fields.priority } } : {}),
       ...(fields.labels && fields.labels.length > 0 ? { labels: fields.labels } : {}),
+      ...(fields.fixVersions && fields.fixVersions.length > 0
+        ? { fixVersions: fields.fixVersions.map((v) => ({ name: v })) }
+        : {}),
     },
   };
 
@@ -147,11 +150,25 @@ export async function getIssue(cfg, issueKey) {
  * @returns {Promise<object>} data object
  */
 async function graphql(cfg, xrayToken, query, variables = {}) {
-  const response = await axios.post(
-    cfg.xrayGraphqlUrl,
-    { query, variables },
-    { httpsAgent, headers: xrayHeaders(xrayToken) }
-  );
+  let response;
+  try {
+    response = await axios.post(
+      cfg.xrayGraphqlUrl,
+      { query, variables },
+      { httpsAgent, headers: xrayHeaders(xrayToken) }
+    );
+  } catch (err) {
+    // Extract the actual response body from axios HTTP errors (4xx/5xx)
+    if (err.response) {
+      const body = err.response.data
+        ? (typeof err.response.data === "string"
+            ? err.response.data
+            : JSON.stringify(err.response.data))
+        : "(no body)";
+      throw new Error(`HTTP ${err.response.status} from Xray GraphQL: ${body}`);
+    }
+    throw err;
+  }
 
   if (response.data.errors) {
     throw new Error(`GraphQL errors: ${JSON.stringify(response.data.errors)}`);
@@ -219,19 +236,22 @@ export async function getTests(cfg, xrayToken, opts = {}) {
 }
 
 /**
- * Get a Test Plan by issue ID (includes its tests).
+ * Get a Test Plan by issue ID (includes its tests, paginated).
  * @param {object} cfg
  * @param {string} xrayToken
  * @param {string} issueId
+ * @param {object} [opts]  { limit?: number, start?: number }
  * @returns {Promise<object>}
  */
-export async function getTestPlan(cfg, xrayToken, issueId) {
+export async function getTestPlan(cfg, xrayToken, issueId, opts = {}) {
+  const limit = opts.limit ?? 100;
+  const start = opts.start ?? 0;
   const data = await graphql(cfg, xrayToken, `
-    query ($issueId: String!) {
+    query ($issueId: String!, $limit: Int!, $start: Int) {
       getTestPlan(issueId: $issueId) {
         issueId
         projectId
-        tests(limit: 100) {
+        tests(limit: $limit, start: $start) {
           total
           results {
             issueId
@@ -246,7 +266,7 @@ export async function getTestPlan(cfg, xrayToken, issueId) {
         }
       }
     }
-  `, { issueId: String(issueId) });
+  `, { issueId: String(issueId), limit, start });
   return data.getTestPlan;
 }
 
@@ -373,8 +393,58 @@ export async function getProjectSettings(cfg, xrayToken, projectId) {
   return data.getProjectSettings;
 }
 
-// ─── Xray GraphQL — Test mutations ────────────────────────────────────────────
+// ─── JIRA REST — Issue search ──────────────────────────────────────────────────
+
+/**
+ * Search JIRA issues via JQL.
+ * @param {object} cfg
+ * @param {string} jql
+ * @param {string[]} [fields]    Fields to return (default: summary, id, key)
+ * @param {number}  [maxResults]
+ * @returns {Promise<object[]>}  Array of issue objects
+ */
+export async function searchIssues(cfg, jql, fields = ["summary", "id", "key"], maxResults = 10) {
+  const response = await axios.get(
+    `${cfg.jiraUrl}/rest/api/3/search`,
+    {
+      httpsAgent,
+      headers: jiraHeaders(cfg),
+      params: { jql, fields: fields.join(","), maxResults },
+    }
+  );
+  return response.data.issues || [];
+}
+
+// ─── Xray GraphQL — Test Set queries ──────────────────────────────────────────
 
+/**
+ * Get Test Sets in a project (paginated).
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {object} [opts]  { projectId, jql, limit, start }
+ * @returns {Promise<{total, results}>}
+ */
+export async function getTestSets(cfg, xrayToken, opts = {}) {
+  const data = await graphql(cfg, xrayToken, `
+    query ($projectId: String, $jql: String, $limit: Int!, $start: Int) {
+      getTestSets(projectId: $projectId, jql: $jql, limit: $limit, start: $start) {
+        total
+        results {
+          issueId
+          projectId
+        }
+      }
+    }
+  `, {
+    projectId: opts.projectId || null,
+    jql: opts.jql || null,
+    limit: Math.min(opts.limit || 100, 100),
+    start: opts.start || 0,
+  });
+  return data.getTestSets;
+}
+
+// ─── Xray GraphQL — Test mutations ────────────────────────────────────────────
 /**
  * Set a test issue's type via Xray GraphQL.
  * @param {object} cfg
@@ -495,6 +565,31 @@ export async function updateTestFolder(cfg, xrayToken, issueId, folderPath) {
   `, { issueId: String(issueId), folderPath });
 }
 
+// ─── Xray GraphQL — Precondition mutations ────────────────────────────────────
+
+/**
+ * Link precondition issues to a test.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   testIssueId          Numeric Xray issue ID of the test
+ * @param {string[]} preconditionIssueIds  Numeric Xray issue IDs of preconditions
+ * @returns {Promise<{addedPreconditions: string[], warnings: string[]}>}
+ */
+export async function addPreconditionsToTest(cfg, xrayToken, testIssueId, preconditionIssueIds) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $preconditionIssueIds: [String]!) {
+      addPreconditionsToTest(issueId: $issueId, preconditionIssueIds: $preconditionIssueIds) {
+        addedPreconditions
+        warnings
+      }
+    }
+  `, {
+    issueId: String(testIssueId),
+    preconditionIssueIds: preconditionIssueIds.map(String),
+  });
+  return data.addPreconditionsToTest;
+}
+
 // ─── Xray GraphQL — Test Plan mutations ───────────────────────────────────────
 
 /**
@@ -978,21 +1073,20 @@ export async function getAttachment(cfg, xrayToken, attachmentId) {
 export async function withRetry(fn, opts = {}) {
   const maxRetries = opts.maxRetries ?? 5;
   const baseDelay = opts.baseDelay ?? 2000;
-  const retryOn = opts.retryOn ?? "issueId provided is not valid";
+  // retryOn accepts a string or array of strings — retry if the error matches any
+  const retryPatterns = Array.isArray(opts.retryOn)
+    ? opts.retryOn
+    : [opts.retryOn ?? "issueId provided is not valid"];
 
   let lastError;
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     try {
-      const delay = baseDelay * Math.pow(2, attempt);
-      if (attempt > 0) {
-        logger.wait(`Retry ${attempt}/${maxRetries - 1} after ${delay}ms...`);
-      }
-      await sleep(delay);
       return await fn();
     } catch (err) {
       lastError = err;
       const msg = err.message || "";
-      if (!msg.includes(retryOn)) {
+      const shouldRetry = retryPatterns.some((p) => msg.includes(p));
+      if (!shouldRetry) {
         if (msg.includes("disallowed to impersonate") || msg.includes("no valid active user exists")) {
           throw new Error(
             `Xray user authentication mismatch.\n\n` +
@@ -1002,6 +1096,11 @@ export async function withRetry(fn, opts = {}) {
         }
         throw err;
       }
+      if (attempt < maxRetries - 1) {
+        const delay = baseDelay * Math.pow(2, attempt);
+        logger.wait(`Retry ${attempt + 1}/${maxRetries - 1} after ${delay}ms...`);
+        await sleep(delay);
+      }
     }
   }
   throw lastError;
@@ -1082,12 +1181,14 @@ export async function createTestExecution(cfg, xrayToken, opts) {
     environments = [],
     testIssueIds = [],
     testPlanKey,
+    fixVersion,
   } = opts;
 
   // 1. Create JIRA issue
   const issue = await createIssue(cfg, "Test Execution", {
     summary: summary || `Test Execution — ${new Date().toLocaleString()}`,
     description: description || summary || "",
+    ...(fixVersion ? { fixVersions: [fixVersion] } : {}),
   });
 
   logger.step(`Test Execution created: ${issue.key}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msalaam/xray-qe-toolkit",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "QE toolkit for Xray Cloud — test management, tests.json standardisation, Playwright result import, and CI pipeline integration.",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@msalaam/xray-qe-toolkit": "^1.6.0",
     "axios": "^1.13.4",
     "commander": "^13.1.0",
     "dotenv": "^17.2.3",

package/schema/tests.schema.json

@@ -60,8 +60,27 @@
             "pattern": "^/"
           },
           "testSet": {
-            "type": "string",
-            "description": "Name of the Xray Test Set this test belongs to. Tests sharing the same value are grouped into a single Test Set issue in JIRA. xqt push creates the Test Set automatically if it doesn't exist and adds the test to it. Test Set → JIRA key mappings are stored in xray-mapping.json under _testSets."
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "Name of a single Xray Test Set this test belongs to."
+              },
+              {
+                "type": "array",
+                "items": { "type": "string" },
+                "minItems": 1,
+                "description": "Names of multiple Xray Test Sets this test belongs to."
+              }
+            ],
+            "description": "Xray Test Set name(s) — string or array of strings. Tests are grouped into Test Set issues in JIRA. xqt push creates sets automatically and adds the test to each."
+          },
+          "preconditions": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9_]+-[0-9]+$"
+            },
+            "description": "JIRA issue keys of Xray Precondition issues linked to this test (e.g. [\"PROJ-5\"]). xqt push calls addPreconditionsToTest on each push."
           },
           "requirementKeys": {
             "type": "array",

package/templates/README.template.md

@@ -21,6 +21,7 @@
 10. [CI/CD Integration](#10-cicd-integration)
 11. [xray-mapping.json](#11-xray-mappingjson)
 12. [Configuration (.xrayrc)](#12-configuration-xrayrc)
+13. [Troubleshooting](#13-troubleshooting)
 
 > **This file covers the xqt toolkit commands and Xray configuration.**
 > For the full QE process — spec-driven workflow, greenfield/brownfield steps, AI agent
@@ -152,6 +153,7 @@ After running `npx xqt init`:
       "tags": ["smoke", "regression"],
       "folder": "/{{SERVICE_NAME}}/HealthCheck/Validation",
       "testSet": "Health Check",
+      "preconditions": ["APIEE-50"],
       "requirementKeys": [],
       "xray": {
         "summary": "Service returns 200 OK when healthy",
@@ -175,7 +177,8 @@ After running `npx xqt init`:
 | `skip` | boolean | — | `true` to exclude from push-tests |
 | `tags` | string[] | — | QE tags for categorisation and filtering |
 | `folder` | string | — | Xray repository folder path — must start with `/` |
-| `testSet` | string | — | Test Set name in Jira — groups tests by feature |
+| `testSet` | string **or** string[] | — | Test Set name(s) in Jira — use a string or an array to assign to multiple sets |
+| `preconditions` | string[] | — | JIRA keys of Xray Precondition issues to link (e.g. `["APIEE-50"]`) |
 | `requirementKeys` | string[] | — | JIRA issue keys this test covers (creates coverage links) |
 | `xray.summary` | string | Yes | Test case title (JIRA issue summary) |
 | `xray.description` | string | — | Detailed description |
@@ -213,14 +216,20 @@ npx xqt create-plan --summary "{{SERVICE_NAME}} v2 Regression"
 npx xqt create-plan --summary "Sprint 12 Smoke Tests" --version "2024.12"
 ```
 
-### `xqt push-tests`
+### `xqt push-tests` (alias: `push`)
 
 Create or update tests in Xray Cloud, then sync the Test Plan membership and folder structure.
 
+- New tests are **bulk-imported** via the Xray REST API when there are ≥ `bulkImportThreshold` (default: 50) to create — significantly faster for large suites. Force it at any count with `--bulk`
+- Test Plan membership is **bi-directionally synced**: new tests are added and tests removed from `tests.json` are removed from the plan
+- Test Sets are **deduplicated by name** — safe to run on a fresh clone, existing sets are found in JIRA before creating new ones
+- `preconditions` are linked after every create or update
+
 ```bash
-npx xqt push-tests
-npx xqt push-tests --plan APIEE-1234   # override plan key
-npx xqt push-tests --verbose
+npx xqt push
+npx xqt push --plan APIEE-1234          # override plan key
+npx xqt push --bulk                     # force bulk REST import regardless of test count
+npx xqt push --verbose
 ```
 
 ### `xqt pull-tests`
@@ -232,15 +241,15 @@ npx xqt pull-tests --plan APIEE-1234
 npx xqt pull-tests --project APIEE --limit 200
 ```
 
-### `xqt import-results`
+### `xqt import-results` (alias: `import`)
 
 Import test execution results into Xray. Creates a **new** Test Execution each time.
 
 ```bash
-npx xqt import-results --file test-results/results.json --env IOP-QA
-npx xqt import-results --file test-results/results.xml   --env IOP-PROD
-npx xqt import-results --file test-results/results.json --env IOP-DEV \
-  --plan APIEE-1234 --version "2024.12" --revision "a1b2c3d"
+npx xqt import --file test-results/results.json --env IOP-QA
+npx xqt import --file test-results/results.xml   --env IOP-PROD
+npx xqt import --file test-results/results.json --env IOP-DEV \
+  --plan APIEE-1234 --fix-version "2.5.0" --revision "a1b2c3d"
 ```
 
 **Options:**
@@ -250,10 +259,31 @@ npx xqt import-results --file test-results/results.json --env IOP-DEV \
 | `--file <path>` | Path to results file (`.json` = Playwright, `.xml` = JUnit) |
 | `--env <label>` | Environment label: `IOP-DEV`, `IOP-QA`, `IOP-PROD` |
 | `--plan <key>` | Test Plan key (overrides `.xrayrc`) |
-| `--version <ver>` | Fix version / release label |
-| `--revision <sha>` | Build number or git SHA |
+| `--exec <key>` | Import INTO an existing execution (from `xqt exec`) |
+| `--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 <sha>` | Build number or git SHA (enables traceability to a specific commit) |
 | `--summary <text>` | Custom execution summary |
 
+### `xqt create-execution` (alias: `exec`)
+
+Pre-create a Test Execution before running tests (for controlled test selection).
+
+```bash
+EXEC_KEY=$(npx xqt exec --env IOP-QA --quiet)
+npx playwright test
+npx xqt import --file test-results/results.json --exec $EXEC_KEY
+```
+
+| Flag | Description |
+|---|---|
+| `--env <label>` | Environment label |
+| `--plan <key>` | Test Plan to link to |
+| `--tests <ids>` | Comma-separated testIds or JIRA keys |
+| `--summary <text>` | Custom execution title |
+| `--fix-version <ver>` | JIRA Fix Version to stamp on the execution |
+| `--quiet` | Print only the execution key |
+
 ### `xqt sync-folders`
 
 Sync the Xray repository folder structure from `folder` fields in tests.json.
@@ -306,7 +336,10 @@ npx xqt gen-pipeline --output .azure/ci.yml
 
 Tests live in **Test Sets** in Jira, grouped by feature (matching the feature name in `business-rules.yaml`).
 
-- Created automatically by `push-tests` from the `testSet` field in `tests.json`
+- Assign a test to one set: `"testSet": "Health Check"`
+- Assign to multiple sets: `"testSet": ["Health Check", "Smoke"]`
+- Created automatically by `push` from the `testSet` field in `tests.json`
+- **Deduplicated by name** — if `xray-mapping.json` is lost (e.g. fresh clone), sets are found by searching JIRA before creating a new one
 - Persistent across sprints — they represent what tests exist
 - Link Test Sets to Test Plans when entering a sprint
 
@@ -314,17 +347,20 @@ Tests live in **Test Sets** in Jira, grouped by feature (matching the feature na
 
 A Test Plan scopes testing for a specific sprint or release.
 
-- Create per sprint: `npx xqt create-plan --summary "Sprint 12 — {{SERVICE_NAME}}"`
+- Create per sprint: `npx xqt plan --summary "Sprint 12 — {{SERVICE_NAME}}"`
 - Link relevant Test Sets to the Test Plan in Jira
 - The key is stored in `.xrayrc` (`testPlanKey`)
-- `import-results` links executions to the active plan
+- `import` links executions to the active plan
+- **`xqt push` performs a bi-directional sync** — new tests are added and tests removed from `tests.json` are removed from the plan
 
 ### Test Executions (ephemeral)
 
 A Test Execution represents one CI run.
-- Created automatically by `xqt import-results`
+- Created automatically by `xqt import`
+- **Pre-created** by `xqt exec` for controlled test selection (filter which tests run)
 - Tagged with the environment (`IOP-DEV`, `IOP-QA`, `IOP-PROD`)
 - Linked to the Test Plan
+- Stamped with `--fix-version` and `--revision` for release traceability
 
 ### Summary
 
@@ -348,7 +384,7 @@ Set the default environment and allowed values in `.xrayrc`:
 Override per run with `--env`:
 
 ```bash
-npx xqt import-results --file results.json --env IOP-PROD
+npx xqt import --file results.json --env IOP-PROD
 ```
 
 ---
@@ -387,12 +423,12 @@ The generated `playwright.config.ts` configures three reporters:
 
 ```bash
 # After running: npx playwright test
-npx xqt import-results --file test-results/results.json --env IOP-QA
+npx xqt import --file test-results/results.json --env IOP-QA
 ```
 
 ### Test steps in Xray
 
-Steps defined with `test.step()` are automatically mapped to Xray step results:
+Steps defined with `test.step()` are automatically mapped to Xray step results. **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 }) => {
@@ -481,9 +517,9 @@ Key import step (runs even on test failure):
 ```yaml
 - script: |
     REVISION=$(echo "$(Build.SourceVersion)" | cut -c1-8)
-    npx xqt import-results \
+    npx xqt import \
       --file test-results/results.json \
-      --version "$(Build.BuildNumber)" \
+      --fix-version "$(Build.BuildNumber)" \
       --revision "$REVISION"
   condition: succeededOrFailed()
   env:
@@ -551,11 +587,34 @@ Auto-managed by `push-tests` — do not edit manually.
   "defaultEnvironment": "IOP-DEV",
   "environments":       ["IOP-DEV", "IOP-QA", "IOP-PROD"],
   "folderRoot":         "/{{SERVICE_NAME}}",
-  "xrayRegion":         "us"
+  "xrayRegion":         "us",
+  "bulkImportThreshold": 50,
+  "statusMapping": {
+    "interrupted": "ABORTED",
+    "skipped":     "TODO"
+  }
 }
 ```
 
-### xrayRegion values
+| Field | Description |
+|---|---|
+| `testPlanKey` | Default Test Plan key |
+| `defaultEnvironment` | Fallback environment when `--env` is not provided |
+| `environments` | Allowed environment labels |
+| `folderRoot` | Base folder path in Xray Test Repository |
+| `xrayRegion` | `us` (default), `eu`, or `au` |
+| `bulkImportThreshold` | Min new-test count to switch to bulk REST import (default: `50`) |
+| `statusMapping` | Override default Playwright → Xray status mapping |
+
+#### Playwright status mapping
+
+By default: `passed→PASSED`, `failed→FAILED`, `timedOut→FAILED`, `interrupted→ABORTED`, `skipped→TODO`. Override any value:
+
+```json
+{ "statusMapping": { "interrupted": "FAILED", "skipped": "TODO" } }
+```
+
+You can also set `XQT_BULK_THRESHOLD=<n>` as an environment variable to override the bulk threshold at runtime.
 
 | Value | GraphQL endpoint |
 |---|---|
@@ -567,4 +626,54 @@ You can also set `XRAY_REGION=eu` in `.env`.
 
 ---
 
+## 13. Troubleshooting
+
+**Missing credentials**
+```
+Error: Missing required config: xrayId, xraySecret
+```
+Ensure `.env` exists and all required fields are populated. Copy from `.env.example`.
+
+**Test not found in mapping after push**
+```bash
+npx xqt status
+npx xqt push --verbose
+```
+
+**Test Set creation returns HTTP 400**
+Ensure the **Test Set** issue type exists in your JIRA project and the user can create it.
+> **Project Settings → Issue Types** — "Test Set" must appear in the list.
+
+**Folder sync — permission error**
+```
+User doesn't have permissions to view/edit test repository for project
+```
+The `JIRA_EMAIL` user needs **Test Repository** write access in Xray.
+> **Project Settings → Xray → Test Repository** → add your role or user.
+Folder errors are non-fatal — tests are still created/updated correctly without folder assignment.
+
+**`updateTestType` "not found" on newly created tests**
+Xray Cloud is eventually consistent. `xqt push` retries automatically with backoff. If a test still fails, rerun `xqt push` — it will update the existing test rather than duplicate it.
+
+**Too many tests for serial mode (slow push)**
+```bash
+npx xqt push --bulk          # force REST bulk import regardless of count
+# or lower the threshold in .xrayrc:
+{ "bulkImportThreshold": 10 }
+```
+
+**Import results — 0 tests matched**
+Playwright tests must be annotated with an Xray key:
+```typescript
+test.info().annotations.push({ type: 'xray', description: 'APIEE-1234' });
+```
+
+**"disallowed to impersonate" error**
+`JIRA_EMAIL` must match the email of the user who created the Xray API Key.
+
+**EU / AU region**
+Set `XRAY_REGION=eu` or `XRAY_REGION=au` in `.env`, or `"xrayRegion": "eu"` in `.xrayrc`.
+
+---
+
 *Generated by @msalaam/xray-qe-toolkit — See [npm package](https://www.npmjs.com/package/@msalaam/xray-qe-toolkit) for updates.*