@msalaam/xray-qe-toolkit 1.4.1 → 1.6.0

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 })) }
+        : {}),
     },
   };
 
@@ -219,19 +222,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 +252,7 @@ export async function getTestPlan(cfg, xrayToken, issueId) {
         }
       }
     }
-  `, { issueId: String(issueId) });
+  `, { issueId: String(issueId), limit, start });
   return data.getTestPlan;
 }
 
@@ -373,8 +379,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 +551,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 ───────────────────────────────────────
 
 /**
@@ -566,6 +647,80 @@ export async function removeTestsFromTestPlan(cfg, xrayToken, planIssueId, testI
   });
 }
 
+/**
+ * Remove tests from a Test Plan.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   planIssueId
+ * @param {string[]} testIssueIds
+ */
+export async function removeTestsFromTestPlanById(cfg, xrayToken, planIssueId, testIssueIds) {
+  await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testIssueIds: [String]!) {
+      removeTestsFromTestPlan(issueId: $issueId, testIssueIds: $testIssueIds) {
+        warnings
+      }
+    }
+  `, {
+    issueId: String(planIssueId),
+    testIssueIds: testIssueIds.map(String),
+  });
+}
+
+// ─── Xray GraphQL — Test Set mutations ────────────────────────────────────────
+
+/**
+ * Create a new Test Set issue via Xray GraphQL.
+ *
+ * Test Sets are persistent groupings of tests by feature/area.
+ * They live across sprints — Test Plans reference Test Sets per sprint.
+ *
+ * @param {object} cfg
+ * @param {string} xrayToken
+ * @param {object} opts  { summary, projectId? }
+ * @returns {Promise<{testSet: {issueId: string, projectId: string}, warnings: string[]}>}
+ */
+export async function createTestSet(cfg, xrayToken, opts) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($projectId: String!, $summary: String!) {
+      createTestSet(projectId: $projectId, summary: $summary) {
+        testSet {
+          issueId
+          projectId
+        }
+        warnings
+      }
+    }
+  `, {
+    projectId: opts.projectId || cfg.jiraProjectKey,
+    summary: opts.summary,
+  });
+  return data.createTestSet;
+}
+
+/**
+ * Add tests to an existing Test Set.
+ * @param {object}   cfg
+ * @param {string}   xrayToken
+ * @param {string}   testSetIssueId  Numeric Xray issue ID of the Test Set
+ * @param {string[]} testIssueIds    Numeric Xray issue IDs of tests to add
+ * @returns {Promise<{addedTests: string[], warnings: string[]}>}
+ */
+export async function addTestsToTestSet(cfg, xrayToken, testSetIssueId, testIssueIds) {
+  const data = await graphql(cfg, xrayToken, `
+    mutation ($issueId: String!, $testIssueIds: [String]!) {
+      addTestsToTestSet(issueId: $issueId, testIssueIds: $testIssueIds) {
+        addedTests
+        warnings
+      }
+    }
+  `, {
+    issueId: String(testSetIssueId),
+    testIssueIds: testIssueIds.map(String),
+  });
+  return data.addTestsToTestSet;
+}
+
 // ─── Xray GraphQL — Folder mutations ──────────────────────────────────────────
 
 /**
@@ -909,11 +1064,6 @@ export async function withRetry(fn, opts = {}) {
   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;
@@ -928,6 +1078,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;
@@ -1008,12 +1163,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.4.1",
+  "version": "1.6.0",
   "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.5.0",
     "axios": "^1.13.4",
     "commander": "^13.1.0",
     "dotenv": "^17.2.3",

package/schema/tests.schema.json

@@ -44,7 +44,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "enum": ["regression", "smoke", "edge", "critical", "integration", "e2e", "security", "performance"]
+              "enum": ["regression", "smoke", "edge", "critical", "integration", "e2e", "security", "performance", "contract", "functional", "negative", "positive", "boundary", "acceptance", "sanity", "data-driven", "exploratory", "accessibility"]
             },
             "description": "QE-assigned tags for categorisation. Also used as labels on the Xray Test issue."
           },
@@ -60,8 +60,27 @@
             "pattern": "^/"
           },
           "testSet": {
-            "type": "string",
-            "description": "Test Set name in Jira. Tests with the same testSet value are grouped into the same Xray Test Set. Typically matches the feature name from business-rules.yaml."
+            "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",
@@ -107,7 +126,7 @@
               },
               "steps": {
                 "type": "array",
-                "description": "Ordered manual test steps (used for Manual test type).",
+                "description": "Ordered test steps. Dual purpose: (1) uploaded to Xray as Manual test steps visible in JIRA, (2) used by code generators to scaffold Playwright test bodies. Required when testType is Manual.",
                 "items": {
                   "type": "object",
                   "required": ["action", "expected_result"],
@@ -115,21 +134,121 @@
                     "action": {
                       "type": "string",
                       "minLength": 1,
-                      "description": "What action to perform in this step."
+                      "description": "Human-readable description of the action (e.g. 'Send GET /v1/path/{param} with a valid value'). Used as the step title in Xray and as a generation hint."
                     },
                     "data": {
                       "type": "string",
-                      "description": "Input data or parameters for the step."
+                      "description": "Input data or environment variable references for the step (e.g. 'clientNo: env.TEST_CLIENT_NO')."
                     },
                     "expected_result": {
                       "type": "string",
                       "minLength": 1,
-                      "description": "Expected outcome of the step."
+                      "description": "Expected outcome (e.g. 'HTTP 200, Content-Type: application/json, body matches MySchema')."
                     }
                   }
                 }
               }
             }
+          },
+          "spec": {
+            "type": "object",
+            "description": "Structured test specification used for Playwright test code generation. Contains the operation, expected response values, and input data hints.",
+            "properties": {
+              "operation": {
+                "type": "object",
+                "required": ["method", "path"],
+                "properties": {
+                  "method": {
+                    "type": "string",
+                    "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+                    "description": "HTTP method."
+                  },
+                  "path": {
+                    "type": "string",
+                    "description": "API path, with path parameters in {curly} notation (e.g. /v1/resource/{id})."
+                  },
+                  "operationId": {
+                    "type": "string",
+                    "description": "OpenAPI operationId for traceability."
+                  }
+                }
+              },
+              "expectations": {
+                "type": "object",
+                "description": "Expected response values used to generate assertions.",
+                "properties": {
+                  "statusCodes": {
+                    "type": "array",
+                    "items": { "type": "integer" },
+                    "description": "List of acceptable HTTP status codes."
+                  },
+                  "contentType": {
+                    "type": "string",
+                    "description": "Expected Content-Type header value."
+                  },
+                  "responseSchemaHints": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "OpenAPI schema refs for the expected response body (e.g. ['#/components/schemas/MyResponse'])."
+                  }
+                }
+              },
+              "dataHints": {
+                "type": "object",
+                "description": "Input data hints used to scaffold test fixtures and parameter substitution.",
+                "properties": {
+                  "pathParams": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Names of path parameters (matched to env[] values by convention)."
+                  },
+                  "queryParams": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Names of query parameters."
+                  },
+                  "body": {
+                    "type": "string",
+                    "description": "Request body description or JSON schema ref (empty string for no body)."
+                  },
+                  "env": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Environment variable names required to run the test (e.g. ['TEST_CLIENT_NO'])."
+                  }
+                }
+              }
+            }
+          },
+          "contract": {
+            "type": "object",
+            "description": "OpenAPI contract validation specifics. Only required when testKind is 'contract'.",
+            "properties": {
+              "operationId": {
+                "type": "string",
+                "description": "OpenAPI operationId this contract test covers."
+              },
+              "expectedStatus": {
+                "type": "integer",
+                "description": "HTTP status code the contract expects."
+              },
+              "expectedContentType": {
+                "type": "string",
+                "description": "Expected Content-Type header."
+              },
+              "responseSchemaRef": {
+                "type": "string",
+                "description": "OpenAPI schema $ref for the response body (e.g. '#/components/schemas/MyResponse')."
+              },
+              "validationScope": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["status-code", "content-type", "required-fields", "type-checks", "headers"]
+                },
+                "description": "Which contract assertions to enforce."
+              }
+            }
           }
         }
       }

package/templates/README.template.md

@@ -152,6 +152,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 +176,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 +215,19 @@ 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
+- 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 --verbose
 ```
 
 ### `xqt pull-tests`
@@ -232,15 +239,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 +257,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 +334,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 +345,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 +382,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 +421,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 +515,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 +585,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 |
 |---|---|