@msalaam/xray-qe-toolkit 1.4.1 → 1.6.0

package/README.md

@@ -55,17 +55,17 @@ openapi.yaml + business-rules.yaml
       ↓ (AI agent generates tests.json)
 tests.json — structured test definitions
       ↓
-xqt validate            ← schema check
+xqt validate   ← schema check
       ↓
-xqt push-tests          ← creates/updates Tests + Test Sets in Xray
+xqt push       ← creates/updates Tests + Test Sets in Xray
       ↓
 xray-mapping.json       ← auto-populated with Jira issue keys
       ↓
 Playwright API tests    ← created by Copilot (reads tests.json + xray-mapping.json)
       ↓
-Sprint starts           ← xqt create-plan → link Test Sets to Test Plan
+Sprint starts  ← xqt plan → link Test Sets to Test Plan
       ↓
-CI runs tests           ← xqt import-results → Test Execution in Xray
+CI runs tests  ← xqt import → Test Execution in Xray
 ```
 
 **Key design decisions:**
@@ -118,18 +118,18 @@ cp .env.example .env
 
 # 5. Validate and push to Xray
 npx xqt validate
-npx xqt push-tests
+npx xqt push
 #    → Tests + Test Sets created in Jira
 #    → xray-mapping.json populated with issue keys
 
 # 6. Create Playwright tests (done by Copilot skill — reads tests.json + xray-mapping.json)
 
 # 7. When entering a sprint, create a Test Plan and link Test Sets
-npx xqt create-plan --summary "Sprint 12 — My Service Regression"
+npx xqt plan --summary "Sprint 12 — My Service Regression"
 
 # 8. Run tests and import results
 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
 ```
 
 ---
@@ -167,13 +167,14 @@ npx xqt edit --port 3000
 
 ---
 
-### `xqt create-plan`
+### `xqt plan`
 
 Create a new Xray Test Plan in JIRA. Automatically saves the key to `.xrayrc` and `tests.json`.
+`create-plan` is accepted as a legacy alias.
 
 ```bash
-npx xqt create-plan --summary "My Service v2 Regression"
-npx xqt create-plan --summary "Sprint 12 Smoke Tests" --version "2024.12"
+npx xqt plan --summary "My Service v2 Regression"
+npx xqt plan --summary "Sprint 12 Smoke Tests" --version "2024.12"
 ```
 
 | Flag | Description |
@@ -184,35 +185,43 @@ npx xqt create-plan --summary "Sprint 12 Smoke Tests" --version "2024.12"
 
 ---
 
-### `xqt push-tests`
+### `xqt push`
 
 Create or update tests in Xray Cloud, then sync Test Plan membership and the Xray folder structure.
+Optionally create a Test Execution linked to the plan in a single command.
+`push-tests` is accepted as a legacy alias.
 
 ```bash
-npx xqt push-tests
-npx xqt push-tests --plan APIEE-1234
+npx xqt push
+npx xqt push --plan APIEE-1234
+npx xqt push --plan APIEE-1234 --create-execution --execution-env IOP-QA
 ```
 
 | Flag | Description |
 |---|---|
 | `--plan <key>` | Test Plan key (overrides `.xrayrc testPlanKey`) |
+| `--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 |
 
 **Behaviour:**
 - Tests in `xray-mapping.json` → **updated** in Xray
 - Tests not in mapping → **created** in Xray, mapping entry added
 - Tests with `"skip": true` → excluded entirely
-- Tests are added to **Test Sets** based on the `testSet` field in `tests.json`
+- **Test Sets auto-created** from the `testSet` field and tests added to them (see below)
 - Xray folder structure synced from `folder` fields
+- With `--create-execution`, a new Test Execution is created and linked to the Test Plan
 
 ---
 
-### `xqt pull-tests`
+### `xqt pull`
 
 Pull test definitions from Xray Cloud and merge them into `tests.json`. Useful for onboarding to an existing Xray project.
+`pull-tests` is accepted as a legacy alias.
 
 ```bash
-npx xqt pull-tests --plan APIEE-1234
-npx xqt pull-tests --project APIEE --limit 200
+npx xqt pull --plan APIEE-1234
+npx xqt pull --project APIEE --limit 200
 ```
 
 | Flag | Description |
@@ -223,20 +232,21 @@ npx xqt pull-tests --project APIEE --limit 200
 
 ---
 
-### `xqt create-execution`
+### `xqt exec`
 
 Pre-create a Test Execution with a specific set of tests before running them.
-Use `--quiet` to capture the key in CI for use with `import-results --exec`.
+Use `--quiet` to capture the key in CI for use with `import --exec`.
+`create-execution` is accepted as a legacy alias.
 
 ```bash
 # Standard output
-npx xqt create-execution --env IOP-QA
+npx xqt exec --env IOP-QA
 
 # CI mode — prints ONLY the key
-EXEC_KEY=$(npx xqt create-execution --env IOP-QA --quiet)
+EXEC_KEY=$(npx xqt exec --env IOP-QA --quiet)
 
 # Specific test selection
-npx xqt create-execution --env IOP-QA --plan APIEE-1234 --tests TC-001,TC-002
+npx xqt exec --env IOP-QA --plan APIEE-1234 --tests TC-001,TC-002
 ```
 
 | Flag | Description |
@@ -245,15 +255,17 @@ npx xqt create-execution --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 |
 
-> `import-results` creates an execution automatically — this command is only needed when pre-selecting a specific subset of tests.
+> `xqt import` creates an execution automatically — this command is only needed when pre-selecting a specific subset of tests.
 
 ---
 
-### `xqt import-results`
+### `xqt import`
 
 Import test execution results into Xray Cloud.
+`import-results` is accepted as a legacy alias.
 
 - **Without `--exec`** — creates a **new** Test Execution linked to the Test Plan
 - **With `--exec`** — imports results INTO a pre-created execution
@@ -262,20 +274,20 @@ Supported: Playwright JSON (`.json`) and JUnit XML (`.xml`).
 
 ```bash
 # Auto-create execution (standard CI)
-npx xqt import-results --file test-results/results.json --env IOP-QA
+npx xqt import --file test-results/results.json --env IOP-QA
 
 # Import into a pre-created execution
-npx xqt import-results --file test-results/results.json --exec APIEE-9876
+npx xqt import --file test-results/results.json --exec APIEE-9876
 
 # JUnit XML
-npx xqt import-results --file test-results/results.xml --env IOP-PROD
+npx xqt import --file test-results/results.xml --env IOP-PROD
 
-# Full options
-npx xqt import-results \
+# 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"
 ```
 
@@ -284,19 +296,21 @@ npx xqt import-results \
 | `--file <path>` | Path to results file **(required)** |
 | `--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 `create-execution`) |
-| `--version <ver>` | Fix version / release label |
+| `--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 <rev>` | Build number or git SHA |
 | `--summary <text>` | Custom execution summary |
 
 ---
 
-### `xqt sync-folders`
+### `xqt sync`
 
 Sync the Xray Test Repository folder structure from `folder` fields in `tests.json` without touching test content.
+`sync-folders` is accepted as a legacy alias.
 
 ```bash
-npx xqt sync-folders
+npx xqt sync
 ```
 
 ---
@@ -327,13 +341,14 @@ npx xqt validate --file path/to/tests.json
 
 ---
 
-### `xqt gen-pipeline`
+### `xqt pipeline`
 
 Generate an Azure Pipelines YAML template for the current project.
+`gen-pipeline` is accepted as a legacy alias.
 
 ```bash
-npx xqt gen-pipeline
-npx xqt gen-pipeline --output .azure/ci.yml
+npx xqt pipeline
+npx xqt pipeline --output .azure/ci.yml
 ```
 
 ---
@@ -381,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"
+  }
+}
+```
 
 ---
 
@@ -419,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",
@@ -440,9 +486,10 @@ JIRA_EMAIL=your.email@company.com
 | `test_id` | string | Yes | Stable local ID — maps to the Xray key in `xray-mapping.json` |
 | `type` | string | — | `api` / `ui` / `e2e` (informational) |
 | `skip` | boolean | — | `true` to exclude from `push-tests` |
-| `tags` | string[] | — | QE tags for categorisation and filtering |
+| `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 |
@@ -457,27 +504,53 @@ JIRA_EMAIL=your.email@company.com
 
 ### Test Sets (persistent groupings)
 
-Tests live in **Test Sets** in Jira. Each Test Set groups related tests — typically by feature (matching the feature name in `business-rules.yaml`).
+Tests live in **Test Sets** in Jira. Each Test Set groups related tests by feature or area — they persist across every sprint.
 
-- Created automatically by `push-tests` from the `testSet` field in `tests.json`
-- Persistent across sprints — they represent what tests exist
-- Link Test Sets to Test Plans when entering a sprint
+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", "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 (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`
+
+```json
+// xray-mapping.json (auto-managed)
+{
+  "_testSets": {
+    "Client Lookup": { "key": "APIEE-99", "id": "123456" },
+    "Health Check":  { "key": "APIEE-100", "id": "123457" }
+  },
+  "TC-001": { "key": "APIEE-200", "id": "234001" },
+  ...
+}
+```
+
+Test Sets are **not deleted** when tests are removed from `tests.json`. They persist in Jira as a record of all tests that have ever existed for that feature.
 
 ### Test Plans (per-sprint)
 
 A Test Plan scopes testing work for a specific sprint or release.
 
-- Create with `xqt create-plan --summary "Sprint 12 — My Service"`
-- Link relevant Test Sets to the Test Plan in Jira
+- Create with `xqt plan --summary "Sprint 12 — My Service"`
+- Link relevant Test Sets to the Test Plan in Jira (manual step in Jira UI)
 - Key stored in `.xrayrc` (`testPlanKey`)
-- `import-results` links executions to the active plan
+- `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.
 
-- **Auto-created** by `xqt import-results` — one new execution per run
-- **Pre-created** by `xqt create-execution` for controlled test selection
+- **Auto-created** by `xqt import` — one new execution per run
+- **Pre-created** by `xqt exec` for controlled test selection
 - Tagged with environment labels (`IOP-DEV`, `IOP-QA`, `IOP-PROD`)
 - Linked to the Test Plan automatically
 
@@ -489,18 +562,25 @@ A Test Execution represents a single CI run.
 | **Test Plan** | Per-sprint | Scopes testing for a sprint — links Test Sets |
 | **Test Execution** | Per-CI-run | Records pass/fail for one run |
 
-### Two execution modes
+### Three execution modes
 
 **Mode A — Auto (standard CI):**
 ```bash
-npx xqt import-results --file results.json --env IOP-QA
+npx xqt import --file results.json --env IOP-QA
 ```
 
 **Mode B — Pre-create (controlled test selection):**
 ```bash
-EXEC_KEY=$(npx xqt create-execution --env IOP-QA --plan APIEE-1234 --quiet)
+EXEC_KEY=$(npx xqt exec --env IOP-QA --plan APIEE-1234 --quiet)
 npx playwright test
-npx xqt import-results --file results.json --exec $EXEC_KEY
+npx xqt import --file results.json --exec $EXEC_KEY
+```
+
+**Mode C — Push & execute (single command):**
+```bash
+npx xqt push --plan APIEE-1234 --create-execution --execution-env IOP-QA
+npx playwright test
+npx xqt import --file results.json --env IOP-QA
 ```
 
 ---
@@ -538,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 }) => {
@@ -571,7 +651,7 @@ Tests are organised in the Xray Test Repository using the `folder` field in `tes
 
 - Paths must start with `/`
 - `folderRoot` in `.xrayrc` sets the base path
-- Folders are created automatically by `push-tests` and `sync-folders`
+- Folders are created automatically by `xqt push` and `xqt sync`
 
 ---
 
@@ -579,7 +659,7 @@ Tests are organised in the Xray Test Repository using the `folder` field in `tes
 
 ### Azure DevOps pipeline
 
-Generate a template: `npx xqt gen-pipeline`
+Generate a template: `npx xqt pipeline`
 
 ```yaml
 - script: npx xqt validate
@@ -590,9 +670,11 @@ Generate a template: `npx xqt gen-pipeline`
   continueOnError: true
 
 - script: |
-    npx xqt import-results \
+    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)
@@ -614,12 +696,13 @@ Generate a template: `npx xqt gen-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)
 
 ```yaml
 - script: |
-    EXEC_KEY=$(npx xqt create-execution --env $(XQT_ENV) --quiet)
+    EXEC_KEY=$(npx xqt exec --env $(XQT_ENV) --quiet)
     echo "##vso[task.setvariable variable=EXEC_KEY]$EXEC_KEY"
   displayName: Pre-create Test Execution
 
@@ -627,7 +710,7 @@ Generate a template: `npx xqt gen-pipeline`
   continueOnError: true
 
 - script: |
-    npx xqt import-results --file test-results/results.json --exec $(EXEC_KEY)
+    npx xqt import --file test-results/results.json --exec $(EXEC_KEY)
   displayName: Import results into pre-created execution
 ```
 
@@ -657,13 +740,13 @@ 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`.
 
 ---
 
 ## xray-mapping.json
 
-Auto-managed by `push-tests`. Maps local `test_id` → JIRA issue key and numeric Xray ID.
+Auto-managed by `xqt push`. Maps local `test_id` → JIRA issue key and numeric Xray ID.
 
 ```json
 {
@@ -696,7 +779,7 @@ Ensure `.env` exists and is populated.
 **Test not found in mapping after push**
 ```bash
 npx xqt status
-npx xqt push-tests --verbose
+npx xqt push --verbose
 ```
 
 **Import results — 0 tests matched**
@@ -708,6 +791,9 @@ 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**
+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**
 Set `XRAY_REGION=eu` in `.env` or `"xrayRegion": "eu"` in `.xrayrc`.
 

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * @msalaam/xray-qe-toolkit — CLI Entry Point
@@ -7,18 +7,18 @@
  *   npx xqt <command> [options]
  *
  * Commands:
- *   init             Scaffold project structure (tests/, playwright.config.ts, tests.json, .xrayrc)
- *   edit             Launch browser-based editor for tests.json
- *   push-tests       Push/update tests in Xray Cloud + sync Test Plan + sync folders
- *   pull-tests       Pull test definitions from Xray Cloud into tests.json
- *   create-execution Create a new Test Execution with a specific set of tests
- *   import-results   Import test results (JUnit XML or Playwright JSON) — new execution per run
- *   create-plan      Create a new Xray Test Plan in JIRA
- *   sync-folders     Sync Xray repository folder structure from tests.json folder fields
- *   status           Show local + remote project status summary
- *   validate         Validate tests.json against its schema
- *   gen-pipeline     Generate Azure Pipelines YAML
- *   mcp-server       Start the MCP server for GitHub Copilot agent-mode integration
+ *   init       Scaffold project structure (tests/, playwright.config.ts, tests.json, .xrayrc)
+ *   edit       Launch browser-based editor for tests.json
+ *   push       Push/update tests in Xray Cloud + sync Test Plan + sync folders
+ *   pull       Pull test definitions from Xray Cloud into tests.json
+ *   exec       Create a new Test Execution with a specific set of tests
+ *   import     Import test results (JUnit XML or Playwright JSON) — new execution per run
+ *   plan       Create a new Xray Test Plan in JIRA
+ *   sync       Sync Xray repository folder structure from tests.json folder fields
+ *   status     Show local + remote project status summary
+ *   validate   Validate tests.json against its schema
+ *   pipeline   Generate Azure Pipelines YAML
+ *   mcp        Start the MCP server for GitHub Copilot agent-mode integration
  */
 
 import { Command } from "commander";
@@ -61,18 +61,23 @@ program
   });
 
 program
-  .command("push-tests")
+  .command("push")
+  .alias("push-tests")
   .description(
     "Create/update tests in Xray Cloud, sync to Test Plan, sync folder structure"
   )
   .option("--plan <key>", "Test Plan key (overrides .xrayrc testPlanKey)")
+  .option("--create-execution", "Create a Test Execution linked to the Test Plan after pushing")
+  .option("--execution-env <label>", "Environment label for created execution (e.g. IOP-QA)")
+  .option("--execution-summary <text>", "Custom summary for created execution")
   .action(async (opts, cmd) => {
     const mod = await import("../commands/pushTests.js");
     await mod.default({ ...opts, ...cmd.optsWithGlobals() });
   });
 
 program
-  .command("pull-tests")
+  .command("pull")
+  .alias("pull-tests")
   .description("Pull test definitions from Xray Cloud into tests.json")
   .option("--plan <key>", "Fetch tests from a specific Test Plan")
   .option("--project <key>", "Fetch all tests in a JIRA project")
@@ -83,17 +88,19 @@ program
   });
 
 program
-  .command("create-execution")
+  .command("exec")
+  .alias("create-execution")
   .description(
     "Create a new Test Execution with a specific set of tests. " +
     "Use --quiet to print only the execution key for CI variable capture: " +
-    "EXEC_KEY=$(xqt create-execution --env IOP-QA --quiet)"
+    "EXEC_KEY=$(xqt exec --env IOP-QA --quiet)"
   )
   .option("--env <environment>", "Environment label (e.g. IOP-QA, IOP-PROD)")
   .option("--plan <key>", "Test Plan key to link the execution to (overrides .xrayrc)")
   .option("--tests <ids>", "Comma-separated testIds or JIRA keys to include (default: all mapped tests)")
   .option("--summary <text>", "Custom Test Execution summary")
   .option("--description <text>", "Custom description")
+  .option("--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");
@@ -101,16 +108,18 @@ program
   });
 
 program
-  .command("import-results")
+  .command("import")
+  .alias("import-results")
   .description(
     "Import test results into Xray Cloud — creates a NEW Test Execution per run (JUnit XML or Playwright JSON)"
   )
   .requiredOption("--file <path>", "Path to results file (.json for Playwright, .xml for JUnit)")
   .option("--env <environment>", "Test environment label (e.g. IOP-DEV, IOP-QA, IOP-PROD)")
   .option("--plan <key>", "Test Plan key to associate execution with (overrides .xrayrc)")
-  .option("--exec <key>", "Import INTO an existing Test Execution key (from create-execution)")
+  .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) => {
@@ -119,7 +128,8 @@ program
   });
 
 program
-  .command("create-plan")
+  .command("plan")
+  .alias("create-plan")
   .description("Create a new Test Plan in JIRA and save its key to .xrayrc and tests.json")
   .requiredOption("--summary <text>", "Test Plan summary / title")
   .option("--version <version>", "Fix version to associate with the plan")
@@ -130,7 +140,8 @@ program
   });
 
 program
-  .command("sync-folders")
+  .command("sync")
+  .alias("sync-folders")
   .description("Sync Xray repository folder structure from the folder field in tests.json")
   .action(async (opts, cmd) => {
     const mod = await import("../commands/syncFolders.js");
@@ -157,7 +168,8 @@ program
   });
 
 program
-  .command("gen-pipeline")
+  .command("pipeline")
+  .alias("gen-pipeline")
   .description("Generate an Azure Pipelines YAML template")
   .option("--output <path>", "Output file path", "azure-pipelines.yml")
   .action(async (opts, cmd) => {
@@ -166,7 +178,8 @@ program
   });
 
 program
-  .command("mcp-server")
+  .command("mcp")
+  .alias("mcp-server")
   .description(
     "Start the MCP server for GitHub Copilot agent-mode integration. " +
     "Runs in stdio mode by default (for VS Code), or HTTP mode with --port."
@@ -182,4 +195,4 @@ program
 program.parseAsync(process.argv).catch((err) => {
   console.error(`\n${err.message}\n`);
   process.exit(1);
-});
+});

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) {