@msalaam/xray-qe-toolkit 1.6.0 → 1.6.1

package/README.md

@@ -194,12 +194,14 @@ Optionally create a Test Execution linked to the plan in a single command.
 ```bash
 npx xqt push
 npx xqt push --plan APIEE-1234
+npx xqt push --bulk                                             # force bulk import regardless of count
 npx xqt push --plan APIEE-1234 --create-execution --execution-env IOP-QA
 ```
 
 | Flag | Description |
 |---|---|
 | `--plan <key>` | Test Plan key (overrides `.xrayrc testPlanKey`) |
+| `--bulk` | Force bulk Xray REST import regardless of new-test count (useful when count is below `bulkImportThreshold`) |
 | `--create-execution` | Create a Test Execution linked to the Test Plan after pushing |
 | `--execution-env <label>` | Environment label for the created execution (e.g. `IOP-QA`) |
 | `--execution-summary <text>` | Custom summary for the created execution |
@@ -791,7 +793,22 @@ test.info().annotations.push({ type: 'xray', description: 'APIEE-1234' });
 **Validate fails in CI**
 Fix schema errors before pushing. Common causes: missing `testId`, invalid `priority`, malformed `folder` path (must start with `/`).
 
-**Old command names still work**
+**`xqt push` — Test Repository folder errors**
+```
+GraphQL errors: User doesn't have permissions to view/edit test repository for project
+```
+The JIRA user in `JIRA_EMAIL` needs **Test Repository** write access in Xray. Fix in Jira:
+> **Project Settings → Xray → Test Repository** → add your role or user to the allowed list.
+Folder sync errors are non-fatal — tests are still created/updated correctly.
+
+**Test Set creation returns HTTP 400**
+Ensure the Xray **Test Set** issue type exists in your JIRA project and that the user has permission to create it.
+> **Project Settings → Issue Types** — "Test Set" must be present.
+
+**`updateTestType` "not found" on new tests**
+Xray Cloud is eventually consistent — a newly created issue may not be immediately visible to the GraphQL API. `xqt push` automatically retries with backoff. If failures persist, rerun `xqt push` (existing tests update, not duplicate).
+
+
 All previous multi-word commands (`push-tests`, `pull-tests`, `create-plan`, `create-execution`, `import-results`, `sync-folders`, `gen-pipeline`, `mcp-server`) remain valid as aliases.
 
 **EU region**

package/bin/cli.js

@@ -67,6 +67,7 @@ program
     "Create/update tests in Xray Cloud, sync to Test Plan, sync folder structure"
   )
   .option("--plan <key>", "Test Plan key (overrides .xrayrc testPlanKey)")
+  .option("--bulk", "Force bulk Xray REST import regardless of new-test count")
   .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")

package/commands/pushTests.js

@@ -84,7 +84,7 @@ export default async function pushTests(opts = {}) {
 
   // ── Build & push tests ─────────────────────────────────────────────────────
   logger.send("Pushing tests to Xray...");
-  const result = await buildAndPush(cfg, tests, mapping, xrayToken);
+  const result = await buildAndPush(cfg, tests, mapping, xrayToken, { forceBulk: !!opts.bulk });
 
   logger.blank();
   logger.success(

package/lib/testCaseBuilder.js

@@ -77,7 +77,7 @@ export function saveMapping(mappingPath, mapping) {
  * @param {string}   xrayToken  JWT token (pass to avoid re-authenticating)
  * @returns {Promise<{created: string[], updated: string[], failed: string[]}>}
  */
-export async function buildAndPush(cfg, tests, mapping, xrayToken) {
+export async function buildAndPush(cfg, tests, mapping, xrayToken, opts = {}) {
   const created = [];
   const updated = [];
   const failed = [];
@@ -85,9 +85,12 @@ export async function buildAndPush(cfg, tests, mapping, xrayToken) {
   const toCreate = tests.filter((t) => !mapping[t.test_id]);
   const toUpdate = tests.filter((t) => mapping[t.test_id]);
 
+  const threshold = cfg.bulkImportThreshold ?? 50;
+  const useBulk = opts.forceBulk ? toCreate.length > 0 : toCreate.length >= threshold;
+
   // ── Bulk create path ───────────────────────────────────────────────────────
-  if (toCreate.length > 0 && toCreate.length >= (cfg.bulkImportThreshold ?? 50)) {
-    logger.send(`Bulk creating ${toCreate.length} new test(s) via Xray REST...`);
+  if (useBulk) {
+    logger.send(`Bulk creating ${toCreate.length} new test(s) via Xray REST${opts.forceBulk ? " (--bulk)" : ""}...`);
 
     const bulkPayload = toCreate.map((test) => {
       const testType = test.xray?.testType || "Generic";
@@ -266,7 +269,9 @@ async function pushSingleTest(cfg, xrayToken, test, mapping, successList, failed
             await updateTestDefinition(cfg, xrayToken, issue.id, test.xray.definition);
           }
         },
-        { retryOn: "issueId provided is not valid" }
+        // Xray is eventually consistent: new issues take a moment to be indexed.
+        // Retry on both the "not found" timing error and the legacy "issueId" error.
+        { retryOn: ["not found", "issueId provided is not valid"], baseDelay: 1500 }
       );
 
       if (testType === "Manual" && test.xray.steps) {
@@ -301,7 +306,7 @@ async function pushSingleTest(cfg, xrayToken, test, mapping, successList, failed
     const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
     logger.stepFail(`Failed: ${detail}`);
     logger.blank();
-    failedList.push(test.test_id);
+    failedList.push({ testId: test.test_id, reason: detail });
   }
 }
 
@@ -535,13 +540,13 @@ export async function syncFolders(cfg, xrayToken, projectId, tests, mapping) {
       await addTestsToFolder(cfg, xrayToken, projectId, folderPath, testIds);
       synced += testIds.length;
 
-      logger.step(`${folderPath} — ${testIds.length} test(s).__`);
+      logger.step(`${folderPath} — ${testIds.length} test(s)`);
     } catch (err) {
       logger.warn(`Failed to sync folder ${folderPath}: ${err.message}`);
     }
   }
 
-  return { synced, created: createdFolders };
+  return { created: createdFolders.length, assigned: synced };
 }
 
 

package/lib/xrayClient.js

@@ -150,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)}`);
@@ -1059,7 +1073,10 @@ 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++) {
@@ -1068,7 +1085,8 @@ export async function withRetry(fn, opts = {}) {
     } 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` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msalaam/xray-qe-toolkit",
-  "version": "1.6.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,7 +30,7 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@msalaam/xray-qe-toolkit": "^1.5.0",
+    "@msalaam/xray-qe-toolkit": "^1.6.0",
     "axios": "^1.13.4",
     "commander": "^13.1.0",
     "dotenv": "^17.2.3",

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
@@ -219,14 +220,15 @@ npx xqt create-plan --summary "Sprint 12 Smoke Tests" --version "2024.12"
 
 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
+- 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
-npx xqt push --plan APIEE-1234   # override plan key
+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
 ```
 
@@ -624,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.*

package/templates/tests.json

@@ -1,4 +1,4 @@
-{
+{
   "testPlan": {
     "summary": "AML Verification V2 – Dual-Track Test Suite",
     "description": "Contract and business-rule tests for party-aml-verification-verify-api v2. Three endpoints: POST /person, POST /entity, GET /healthcheck. Business-rule tests cover the 5-tier data-source routing chain (CACHE → DHA-MASTER → CPB → DHA-NPR → DHA-HANIS) plus validation scenarios. Contract tests cover schema, status code, auth, and header validation per openapi.json."
@@ -26,7 +26,10 @@
         "smoke"
       ],
       "folder": "/Person Tests/Scenario Tests/Cache",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-01 | Cache – Deceased, Surname Pass",
       "xray": {
@@ -162,7 +165,8 @@
             "CACHE_DEAD_FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-02",
@@ -311,7 +315,8 @@
             "CACHE_DEAD_FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-03",
@@ -322,7 +327,10 @@
         "smoke"
       ],
       "folder": "/Person Tests/Scenario Tests/Cache",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-03 | Cache – Alive, Surname Pass",
       "planReason": "Request shape and test data derived from validCurl pipeline input — proven to return HTTP 200 in the target environment. IdentityNumber=9612235153080, FirstName=Muhammad, LastName=Salaam.",
@@ -463,7 +471,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-04",
@@ -600,7 +609,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-05",
@@ -747,7 +757,8 @@
             "DHA_MASTER_DEAD_FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-06",
@@ -897,7 +908,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-07",
@@ -1028,7 +1040,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-08",
@@ -1158,7 +1171,8 @@
             "CPB_SECOND_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-09",
@@ -1288,7 +1302,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-10",
@@ -1416,7 +1431,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-11",
@@ -1427,7 +1443,10 @@
         "smoke"
       ],
       "folder": "/Person Tests/Scenario Tests/DHA-NPR",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-11 | DHA-NPR – Alive, Surname Pass",
       "xray": {
@@ -1553,7 +1572,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-12",
@@ -1681,7 +1701,8 @@
             "DEAD_FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-14",
@@ -1817,7 +1838,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-ERR-02",
@@ -1935,7 +1957,8 @@
             "GRAVITEE_API_KEY"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-F-01",
@@ -1946,7 +1969,10 @@
         "smoke"
       ],
       "folder": "/Person Tests/UseCache FALSE",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-F-01 | UseCache=FALSE – Cache Bypass, DHA-NPR Called Directly",
       "planReason": "Request shape and test data derived from validCurl pipeline input — proven to return HTTP 200 in the target environment. UseCache: false bypasses all caches.",
@@ -2076,7 +2102,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-F-02",
@@ -2192,7 +2219,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-ID-01",
@@ -2203,7 +2231,10 @@
         "regression"
       ],
       "folder": "/Person Tests/ID Validation",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-ID-01 | ID Validation – Valid South African ID",
       "xray": {
@@ -2322,7 +2353,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-ID-02",
@@ -2333,7 +2365,10 @@
         "regression"
       ],
       "folder": "/Person Tests/ID Validation",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-ID-02 | ID Validation – Invalid ID Length",
       "planReason": "Equivalence Partitioning (invalid class) — ID shorter than 13 digits is an invalid class for IdentityNumber.",
@@ -2438,7 +2473,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-ID-03",
@@ -2449,7 +2485,10 @@
         "regression"
       ],
       "folder": "/Person Tests/ID Validation",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-ID-03 | ID Validation – Invalid Luhn Checksum",
       "planReason": "Error Guessing — SA ID numbers use Luhn algorithm for checksum validation. A 13-digit number with an incorrect final check digit is an invalid class per Equivalence Partitioning.",
@@ -2554,7 +2593,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-ID-04",
@@ -2565,7 +2605,10 @@
         "regression"
       ],
       "folder": "/Person Tests/ID Validation",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-ID-04 | ID Validation – Invalid Embedded Date of Birth",
       "planReason": "Error Guessing — SA ID number embeds YYMMDD in positions 1-6. Month '99' is an impossible date, making the ID invalid.",
@@ -2677,7 +2720,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-IN-01",
@@ -2688,7 +2732,10 @@
         "regression"
       ],
       "folder": "/Person Tests/Input Validation",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-IN-01 | Input Validation – UseCache Field Missing",
       "planReason": "Negative Testing — UseCache is a required header per OpenAPI spec. Missing it must return 400.",
@@ -2796,7 +2843,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-IN-02",
@@ -2807,7 +2855,10 @@
         "regression"
       ],
       "folder": "/Person Tests/Input Validation",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-IN-02 | Input Validation – UseCache Field Invalid Value",
       "planReason": "Equivalence Partitioning (invalid class) — UseCache accepts only boolean values (true/false). Sending 'MAYBE' is outside the valid enum.",
@@ -2920,7 +2971,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-PERSON-200",
@@ -2931,7 +2983,11 @@
         "smoke"
       ],
       "folder": "/Person Tests/Contract",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Contract Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Person – 200 OK contract",
       "planReason": "Request shape and test data derived from validCurl pipeline input — proven to return HTTP 2xx in the target environment.",
@@ -3029,7 +3085,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-PERSON-4XX-NEG_BADKEY",
@@ -3040,7 +3097,10 @@
         "regression"
       ],
       "folder": "/Person Tests/Contract",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Person – 401 Invalid Auth Key contract",
       "planReason": "Security/Authentication Planning — gateway must reject invalid API keys.",
@@ -3117,7 +3177,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-E-01",
@@ -3128,7 +3189,10 @@
         "smoke"
       ],
       "folder": "/Entity Tests/Scenario Tests",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "TC-E-01 | Entity Validation – All Directors Valid",
       "xray": {
@@ -3262,7 +3326,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-E-02",
@@ -3393,7 +3458,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-E-03",
@@ -3538,7 +3604,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-E-04",
@@ -3669,7 +3736,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-ENTITY-200",
@@ -3680,7 +3748,11 @@
         "smoke"
       ],
       "folder": "/Entity Tests/Contract",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Contract Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Entity – 200 OK contract",
       "xray": {
@@ -3770,7 +3842,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-ENTITY-4XX-NEG_BADKEY",
@@ -3781,7 +3854,10 @@
         "regression"
       ],
       "folder": "/Entity Tests/Contract",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Entity – 401 Invalid Auth Key contract",
       "planReason": "Security/Authentication Planning — gateway must reject invalid API keys.",
@@ -3857,7 +3933,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-GET-HEALTHCHECK-200",
@@ -3868,7 +3945,11 @@
         "smoke"
       ],
       "folder": "/Healthcheck Tests/Contract",
-      "testSet": "Healthcheck Tests",
+      "testSet": [
+        "Healthcheck Tests",
+        "Contract Tests",
+        "Smoke Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Health Check – 200 OK contract",
       "xray": {
@@ -3935,7 +4016,8 @@
             "GRAVITEE_API_KEY"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-GET-HEALTHCHECK-4XX-NEG_AUTH",
@@ -3946,7 +4028,10 @@
         "regression"
       ],
       "folder": "/Healthcheck Tests/Contract",
-      "testSet": "Healthcheck Tests",
+      "testSet": [
+        "Healthcheck Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Health Check – 401 No Auth Key contract",
       "planReason": "Security/Authentication Planning — Gravitee gateway enforces x-gravitee-api-key on all routes including healthcheck.",
@@ -4011,7 +4096,8 @@
           ],
           "env": []
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-PERSON-400-MISSING_BODY",
@@ -4022,7 +4108,10 @@
         "regression"
       ],
       "folder": "/Person Tests/Contract",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Person – 400 Missing Required Body Fields",
       "planReason": "ISTQB Negative Testing / Error Guessing: Sending an empty JSON body {} omits all required fields (IdentityNumber, LastName, FirstName); API must return 400 with ApiFailureResponse.",
@@ -4100,7 +4189,8 @@
             "GRAVITEE_API_KEY"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-PERSON-5XX",
@@ -4111,7 +4201,10 @@
         "regression"
       ],
       "folder": "/Person Tests/Contract",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Person – 5XX Server Error",
       "planReason": "ISTQB Error Guessing: OpenAPI documents a 5XX server-error path returning ApiFailureResponse. No deterministic fault-inducing input is known; skipped until a fault trigger is identified.",
@@ -4173,7 +4266,8 @@
             "GRAVITEE_API_KEY"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-ENTITY-400-MISSING_BODY",
@@ -4184,7 +4278,10 @@
         "regression"
       ],
       "folder": "/Entity Tests/Contract",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Entity – 400 Missing Required Body Fields",
       "planReason": "ISTQB Negative Testing / Error Guessing: Sending an empty JSON body {} omits all required fields (registrationNumber, registrationName); API must return 400 with ApiFailureResponse.",
@@ -4262,7 +4359,8 @@
             "GRAVITEE_API_KEY"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-ENTITY-5XX",
@@ -4273,7 +4371,10 @@
         "regression"
       ],
       "folder": "/Entity Tests/Contract",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Entity – 5XX Server Error",
       "planReason": "ISTQB Error Guessing: OpenAPI documents a 5XX server-error path returning ApiFailureResponse. No deterministic fault-inducing input is known; skipped until a fault trigger is identified.",
@@ -4335,7 +4436,8 @@
             "GRAVITEE_API_KEY"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-GET-HEALTHCHECK-4XX-NEG_BADKEY",
@@ -4346,7 +4448,10 @@
         "regression"
       ],
       "folder": "/Healthcheck Tests/Contract",
-      "testSet": "Healthcheck Tests",
+      "testSet": [
+        "Healthcheck Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Health Check – 401 Invalid Auth Key contract",
       "planReason": "ISTQB Negative Testing: Gravitee gateway must reject requests with an invalid API key. This mirrors the NEG_BADKEY pattern applied to /person and /entity but is missing for /healthcheck.",
@@ -4411,7 +4516,8 @@
           ],
           "env": []
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-PV-01",
@@ -4422,7 +4528,10 @@
         "regression"
       ],
       "folder": "/Person Validation Tests",
-      "testSet": "Person Validation Tests",
+      "testSet": [
+        "Person Validation Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Person Validation – FirstName Excluded Returns Fail",
       "planReason": "ISTQB Negative Testing / Error Guessing: Omitting FirstName from the request body means the API cannot match the firstName field; Levenshtein distance is maximum → overallResult=Fail → HTTP 422.",
@@ -4493,7 +4602,8 @@
             "LAST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-PV-02",
@@ -4504,7 +4614,10 @@
         "regression"
       ],
       "folder": "/Person Validation Tests",
-      "testSet": "Person Validation Tests",
+      "testSet": [
+        "Person Validation Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Person Validation – FirstName Levenshtein=1 Returns Pass With Warning",
       "planReason": "ISTQB Equivalence Partitioning (valid class with warning): A FirstName with Levenshtein distance of 1 from the source value is within the near-match threshold; the API must return 200 with overallResult=Pass with warning.",
@@ -4576,7 +4689,8 @@
             "LAST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-PV-03",
@@ -4587,7 +4701,10 @@
         "regression"
       ],
       "folder": "/Person Validation Tests",
-      "testSet": "Person Validation Tests",
+      "testSet": [
+        "Person Validation Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Person Validation – SecondName Levenshtein=1 Returns Pass With Warning",
       "planReason": "ISTQB Equivalence Partitioning (valid class with warning): SecondName with Levenshtein distance of 1 from the CPB source value (ANN → AN) triggers a near-match warning; overallResult must be Pass with warning with HTTP 200.",
@@ -4664,7 +4781,8 @@
             "CPB_FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-EV-01",
@@ -4675,7 +4793,10 @@
         "regression"
       ],
       "folder": "/Entity Validation Tests",
-      "testSet": "Entity Validation Tests",
+      "testSet": [
+        "Entity Validation Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Entity Validation – Director FirstName Excluded Returns Fail",
       "planReason": "ISTQB Negative Testing / Error Guessing: Omitting a director FirstName causes maximum Levenshtein distance against the source; that director gets result=Fail → overallResult=Fail → HTTP 422.",
@@ -4747,7 +4868,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-E-06",
@@ -4900,7 +5022,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-ENTITY-404",
@@ -4912,7 +5035,10 @@
         "contract"
       ],
       "folder": "/Entity Tests/Contract",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Entity – 404 Not Found contract",
       "planReason": "ISTQB Negative Testing: POST to a misspelled path (/entit instead of /entity) must return 404 — the gateway must not silently reroute or accept unknown paths.",
@@ -4982,7 +5108,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-ENTITY-422",
@@ -4994,7 +5121,10 @@
         "contract"
       ],
       "folder": "/Entity Tests/Contract",
-      "testSet": "Entity Tests",
+      "testSet": [
+        "Entity Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Entity – 422 Unprocessable Entity contract",
       "planReason": "ISTQB Equivalence Partitioning (invalid class): POST /entity with a director FirstName='sd' (Levenshtein >2 from source JACQUELINE) must return 422 Unprocessable Entity — confirms API correctly rejects grossly mismatched director name data.",
@@ -5075,7 +5205,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-PERSON-404",
@@ -5087,7 +5218,10 @@
         "contract"
       ],
       "folder": "/Person Tests/Contract",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Person – 404 Not Found contract",
       "planReason": "ISTQB Negative Testing: POST to a misspelled path (/perso instead of /person) must return 404 — the gateway must not silently reroute or accept unknown paths.",
@@ -5158,7 +5292,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-CT-POST-PERSON-422",
@@ -5170,7 +5305,10 @@
         "contract"
       ],
       "folder": "/Person Tests/Contract",
-      "testSet": "Person Tests",
+      "testSet": [
+        "Person Tests",
+        "Contract Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Verify Person – 422 Unprocessable Entity contract",
       "planReason": "ISTQB Equivalence Partitioning (invalid class): POST /person with LastName='Sala' (Levenshtein >2 from source surname) must return 422 Unprocessable Entity — confirms API correctly rejects clearly mismatched surname data.",
@@ -5251,7 +5389,8 @@
             "FIRST_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     },
     {
       "test_id": "TC-AMLVER-EV-02",
@@ -5262,7 +5401,10 @@
         "regression"
       ],
       "folder": "/Entity Validation Tests",
-      "testSet": "Entity Validation Tests",
+      "testSet": [
+        "Entity Validation Tests",
+        "Validation Tests"
+      ],
       "requirementKeys": [],
       "displayName": "Entity Validation – Director FirstName Levenshtein=1 Returns Pass With Warning",
       "planReason": "ISTQB Equivalence Partitioning (valid class with warning): A director FirstName with Levenshtein distance of 1 from source (JACQUELIN vs JACQUELINE) is within the near-match threshold; overallResult must be Pass with warning → HTTP 200.",
@@ -5335,7 +5477,8 @@
             "REGISTRATION_NAME"
           ]
         }
-      }
+      },
+      "preconditions": []
     }
   ]
 }