@msalaam/xray-qe-toolkit 1.4.0 → 1.5.0

package/README.md

@@ -1,1434 +1,768 @@
-# @msalaam/xray-qe-toolkit
-
-> Full QE workflow toolkit for Xray Cloud integration — test management, Postman generation, CI pipeline scaffolding, and browser-based review gates.
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [AI Setup (Optional)](#ai-setup-optional)
-- [Quick Start](#quick-start)
-- [Playwright Quick Start](#playwright-quick-start)
-- [CLI Commands](#cli-commands)
-  - [init](#xray-qe-init)
-  - [gen-tests](#xray-qe-gen-tests)
-  - [edit-json](#xray-qe-edit-json)
-  - [push-tests](#xray-qe-push-tests)
-  - [gen-postman](#xray-qe-gen-postman)
-  - [create-execution](#xray-qe-create-execution)
-  - [import-results](#xray-qe-import-results)
-  - [gen-pipeline](#xray-qe-gen-pipeline)
-  - [mcp-server](#xray-qe-mcp-server)
-  - [compare-openapi](#xray-qe-compare-openapi)
-  - [update-snapshot](#xray-qe-update-snapshot)
-- [Configuration](#configuration)
-  - [Environment Variables (.env)](#environment-variables-env)
-  - [Project Config (.xrayrc)](#project-config-xrayrc)
-- [File Reference](#file-reference)
-  - [tests.json](#testsjson)
-  - [xray-mapping.json](#xray-mappingjson)
-- [Multi-Company Test Format](#multi-company-test-format)
-- [Jira/Xray Project Setup](#jiraxray-project-setup)
-- [QE Workflow](#qe-workflow)
-- [Building Regression Packs](#building-regression-packs)
-- [Working with Existing Xray Tests](#working-with-existing-xray-tests)
-- [Idempotent Push](#idempotent-push)
-- [Programmatic API](#programmatic-api)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-`@msalaam/xray-qe-toolkit` (XQT) is a modular, CLI-driven toolkit for Xray Cloud and JIRA-based QE workflows. It provides:
-
-1. **`tests.json`** as the single source-of-truth for test logic
-2. **Browser-based QE review gate** (`edit-json`) for human governance before any push
-3. **Idempotent push** — updates existing tests, creates new ones, skips duplicates
-4. **Postman collection generation** from test definitions
-5. **CI pipeline template** for Azure DevOps (Newman + Xray import)
-6. **Playwright integration** — import Playwright JSON results with automatic test mapping
-7. **OpenAPI contract enforcement** — `compare-openapi` diffs a live spec against a QA snapshot and fails the pipeline on breaking changes; `update-snapshot` promotes a new baseline deliberately
-8. **Modular architecture** — every function is importable for programmatic use
-9. **AI-ready scaffolds** — optional AI assistance for test generation (manual workflow fully supported)
-
-### QE Review Gate Philosophy
-
-**The knowledge/ folder is your single source of truth** — OpenAPI specs, requirements docs, JIRA tickets, and business logic live here. The toolkit uses these sources to generate test cases with AI assistance.
-
-**Nothing is pushed to Xray until a QE manually reviews and approves** via the `edit-json` command. This ensures quality governance and prevents untested automation from reaching Xray Cloud.
-
-```
-init → populate knowledge/ → gen-tests (AI) → edit-json (QE gate) → push-tests → gen-postman (AI) → CI (run + import)
-```
-
-**Generated tests are scaffolds** — always review and enhance before pushing to Xray.
-
----
-
-## Prerequisites
-
-- **Node.js** >= 18.0.0
-- **npm** >= 8.0.0
-- **Xray Cloud** API Key (from Xray > Settings > API Keys)
-- **JIRA Cloud** API Token (from https://id.atlassian.com/manage-profile/security/api-tokens)
-- Both credentials must belong to the **same JIRA user** (Xray impersonation requirement)
-
----
-
-## Installation
-
-### From npm (public)
-
-```bash
-# Install as dev dependency
-npm install --save-dev @msalaam/xray-qe-toolkit
-```
-
-### Verify installation
-
-```bash
-npx xqt --version
-npx xqt --help
-```
-
----
-
-## AI Setup (Optional)
-
-**AI is completely optional.** The toolkit works fully without AI — you can create and edit tests manually using the `edit-json` UI editor.
-
-### Current AI Status
-
-🚧 **All AI features are scaffolds** — ready for implementation but not yet connected to AI providers.
-
-**What's included:**
-- ✅ `--ai` flags in `gen-tests` and `gen-postman` commands
-- ✅ `knowledge/` folder scanner for API specs, requirements, tickets
-- ✅ MCP (Model Context Protocol) server scaffold in `mcp/server.js`
-- ✅ VS Code chat participant extension scaffold in `.vscode/xray-qe-participant/`
-- ❌ **Not included:** Actual AI provider connections (Azure OpenAI, GitHub Copilot, etc.)
-
-### To Enable AI Features (Future)
-
-Choose one of three integration paths:
-
-#### Option 1: MCP Server (for GitHub Copilot CLI/Desktop)
-
-1. Implement AI provider in `mcp/server.js` (Azure OpenAI, Anthropic, etc.)
-2. Configure MCP client to connect to toolkit server
-3. Start server: `npx xqt mcp-server`
-4. Use `gen-tests --ai` with AI provider connected
-
-**Requires:** MCP client setup, AI provider API keys (Azure OpenAI, etc.)
-
-#### Option 2: VS Code Chat Participant (for GitHub Copilot in VS Code)
-
-1. Implement AI provider in `.vscode/xray-qe-participant/extension.js`
-2. Install extension: Copy folder to `~/.vscode/extensions/`
-3. Reload VS Code
-4. Use `@xray-qe` in chat with commands like `/generate`, `/postman`
-
-**Requires:** GitHub Copilot subscription, VS Code extension development
-
-#### Option 3: Direct CLI Integration
-
-1. Modify `commands/genTests.js` to call your preferred AI service directly
-2. Add provider credentials to `.env` (e.g., `AZURE_OPENAI_KEY`)
-3. Use `gen-tests --ai` with integrated provider
-
-**Requires:** AI provider API keys, custom implementation
-
-### Manual Workflow (No AI Required)
-
-**This workflow works TODAY without any AI setup:**
-
-```bash
-# 1. Create tests manually using the UI editor
-npx xqt init
-npx xqt edit-json  # Create tests from scratch or edit templates
-
-# 2. Push to Xray
-npx xqt push-tests
-
-# 3. Generate Postman collection (no AI)
-npx xqt gen-postman  # Uses tests.json + xray-mapping.json directly
-
-# 4. Run in CI
-newman run collection.postman.json
-```
-
-**All AI features gracefully degrade** — without AI, commands provide helpful guidance for manual workflows.
-
----
-
-## Quick Start
-
-### With AI (Future — Requires Setup)
-
-```bash
-# 1. Initialize project with knowledge/ folder and starter files
-npx xqt init
-
-# 2. Configure credentials
-cp .env.example .env
-# Edit .env with your Xray + JIRA credentials
-
-# 3. Add your API specs and requirements to knowledge/ folder
-# See knowledge/README.md for supported file types
-
-# 4. Set up AI provider (see "AI Setup" section above)
-# ... implement AI connection in MCP server or VS Code extension ...
-
-# 5. Generate test cases from knowledge sources (AI-assisted)
-npx xqt gen-tests --ai
-
-# 6. QE review gate — review and refine generated tests
-npx xqt edit-json
-
-# 7. Push approved tests to Xray Cloud
-npx xqt push-tests
-
-# 8. Generate Postman collection (AI-enhanced assertions)
-npx xqt gen-postman --ai
-
-# 9. Generate CI pipeline
-npx xqt gen-pipeline
-
-# 10. Run tests in CI
-newman run collection.postman.json --reporters cli,junit
-npx xqt import-results --file results.xml --testExecKey QE-123
-```
-
-### Without AI (Works Today)
-
-```bash
-# 1. Initialize project
-npx xqt init
-
-# 2. Configure credentials
-cp .env.example .env
-# Edit .env with your Xray + JIRA credentials
-
-# 3. Create tests manually using UI editor
-npx xqt edit-json
-# - Click "Add Test" to create new tests
-# - Use knowledge/ docs as reference (manual review)
-# - Save when ready
-
-# 4. Push to Xray Cloud
-npx xqt push-tests
-
-# 5. Generate Postman collection (from tests.json)
-npx xqt gen-postman
-
-# 6. Generate CI pipeline
-npx xqt gen-pipeline
-
-# 7. Run tests in CI
-newman run collection.postman.json --reporters cli,junit
-npx xqt import-results --file results.xml --testExecKey QE-123
-```
-
----
-
-## CLI Commands
-
-All commands support these global options:
-
-| Option        | Description                        |
-|---------------|------------------------------------|
-| `--verbose`   | Enable debug output                |
-| `--env <path>`| Custom path to .env file           |
-| `--version`   | Show version number                |
-| `--help`      | Show help for any command          |
-
----
-
-### `xqt init`
-
-Scaffold a new project with starter templates.
-
-```bash
-npx xqt init
-```
-
-**Creates:**
-- `knowledge/` folder with subdirectories (`api-specs/`, `requirements/`, `tickets/`)
-- `knowledge/README.md` — guide for organizing documentation
-- `XQT-GUIDE.md` — getting started guide for this toolkit (never named `README.md` to avoid overwriting yours)
-- `tests.json` — starter test definitions (marked as scaffolds)
-- `xray-mapping.json` — empty mapping file
-- `.env.example` — environment variable template
-- `.xrayrc` — project-level config
-
-Existing files are **never overwritten** — the command skips them with a warning.
-
----
-
-### `xqt gen-tests`
-
-Generate test cases from `knowledge/` folder documentation (AI-assisted or manual guidance).
-
-```bash
-# AI-assisted generation (requires AI provider setup — see "AI Setup" section)
-npx xqt gen-tests --ai
-
-# Focus on a specific OpenAPI spec
-npx xqt gen-tests --ai --spec knowledge/api-specs/users-api.yaml
-
-# Use a custom knowledge folder
-npx xqt gen-tests --ai --knowledge ./docs
-
-# Fetch and analyze a JIRA ticket
-npx xqt gen-tests --ai --ticket APIEE-123
-
-# Generate from a prompt
-npx xqt gen-tests --ai --prompt "Generate tests for user authentication flows"
-```
-
-| Option              | Description                                | Required |
-|---------------------|--------------------------------------------|----------|
-| `--ai`              | Enable AI-assisted generation              | Yes      |
-| `--spec <path>`     | OpenAPI/Swagger spec file                  | No       |
-| `--knowledge <path>`| Custom knowledge folder path               | No       |
-| `--ticket <key>`    | JIRA ticket key to fetch and analyze       | No       |
-| `--prompt <text>`   | Natural language prompt                    | No       |
-
-**Output:** Appends generated tests to `tests.json` (or creates it if it doesn't exist)
-
-**🚧 AI Provider Required:** The `--ai` flag currently shows a scaffold message. To enable actual AI generation, implement an AI provider connection (see [AI Setup](#ai-setup-optional)).
-
-**Without AI:** Run `gen-tests` without `--ai` for manual creation guidance, or use `edit-json` to create tests directly in the UI editor.
-
-Existing files are **never overwritten** — the command skips them with a warning.
-
----
-
-### `xqt edit-json`
-
-Launch the browser-based QE review gate editor.
-
-```bash
-npx xqt edit-json
-npx xqt edit-json --port 3000
-```
-
-| Option          | Description                              | Default |
-|-----------------|------------------------------------------|---------|
-| `--port <n>`    | Port for local editor server             | Random  |
-
-**Features:**
-- Add, edit, delete tests in a visual editor
-- Tag tests: `regression`, `smoke`, `edge`, `critical`, `integration`, `e2e`, `security`, `performance`
-- Toggle skip/push per test
-- View Xray mapping status (which tests are already pushed)
-- Real-time validation
-- "Save & Exit" writes `tests.json` and shuts down the server
-
-**Important:** This is the QE governance gate. Nothing is pushed to Xray until the QE saves and explicitly runs `push-tests`.
-
----
-
-### `xqt push-tests`
-
-Push or update tests in Xray Cloud from `tests.json`.
-
-```bash
-# Create new Test Execution and link all tests
-npx xqt push-tests
-
-# Link tests to an existing Test Execution
-npx xqt push-tests --testExecKey QE-123
-
-# Push tests without creating/linking any execution
-npx xqt push-tests --skip-exec
-```
-
-| Option              | Description                                        |
-|---------------------|----------------------------------------------------|
-| `--testExecKey <key>` | Link to an existing Test Execution instead of creating new |
-| `--skip-exec`       | Don't create or link any Test Execution              |
-
-**Behavior:**
-- Tests with `"skip": true` are excluded
-- Tests already in `xray-mapping.json` are **updated** (summary, description, labels, priority, steps)
-- New tests are **created** with type set to "Automated"
-- Mapping is saved incrementally (crash-safe)
-- 300ms rate-limit delay between API calls
-
----
-
-### `xqt gen-postman`
-
-Generate a Postman Collection v2.1 JSON from `tests.json` (works with or without AI).
-
-```bash
-# Generate collection with JIRA keys embedded (run after push-tests)
-npx xqt gen-postman
-
-# Use a custom base URL
-npx xqt gen-postman --base-url https://api.example.com
-
-# AI-enhanced generation with better assertions
-npx xqt gen-postman --ai
-
-# Schema-driven generation from OpenAPI spec (no AI needed)
-npx xqt gen-postman --spec knowledge/api-specs/api.yaml
-
-# Use custom knowledge folder
-npx xqt gen-postman --knowledge ./docs
-```
-
-| Option              | Description                     | Default         |
-|---------------------|---------------------------------|-----------------|
-| `--base-url <url>`  | Base URL for API requests       | `{{baseUrl}}`   |
-| `--ai`              | Enable AI-enhanced assertions   | No              |
-| `--spec <path>`     | OpenAPI spec for schema-driven generation | No    |
-| `--knowledge <path>`| Custom knowledge folder path    | `knowledge/`    |
-
-**Output:** `collection.postman.json` in project root
-
-**Behavior:**
-- Only generates for tests with `type: "api"` (or unset, for backward compatibility)
-- Embeds JIRA keys from `xray-mapping.json` when available (e.g., `[APIEE-6933] Test Summary`)
-- Falls back to `test_id` if not yet pushed to Xray
-- Each test becomes a folder, each step becomes a request with:
-  - Inferred HTTP method and endpoint from step data
-  - Pre-request scripts with step context
-  - Test scripts with assertions inferred from expected results
-  - SCAFFOLD markers for manual enhancement
-
-**Important:** Generated collections are **starting points** — review and enhance assertions, environment variables, and edge cases before use.
-
----
-
-### `xqt create-execution`
-
-Create a standalone Test Execution issue in JIRA.
-
-```bash
-npx xqt create-execution --summary "Sprint 24 Regression" --description "Full API regression"
-npx xqt create-execution --summary "Feature XYZ" --issue QE-123
-```
-
-| Option              | Description                                | Required |
-|---------------------|--------------------------------------------|----------|
-| `--summary <text>`  | Test Execution summary/title               | Yes      |
-| `--description <text>` | Description                             | No       |
-| `--issue <key>`     | Parent issue key to link the execution to  | No       |
-
----
-
-### `xqt import-results`
-
-Import test results into Xray Cloud. Supports JUnit XML and Playwright JSON formats. Designed for CI — no human interaction.
-
-#### Format Comparison
-
-| Feature | JUnit XML | Playwright JSON |
-|---------|-----------|----------------|
-| **Update existing tests** | ❌ No - always creates new tests | ✅ Yes - via annotations |
-| **Test key mapping** | ❌ Not supported | ✅ `test.info().annotations` |
-| **Attachments/Evidence** | ❌ Not supported | ✅ Supported |
-| **Best for** | Newman, generic test runners | Playwright tests |
-| **Recommendation** | ⚠️ Use only for tools without test keys | ✅ **Recommended for Playwright** |
-
-#### JUnit XML (Newman, generic test runners)
-
-⚠️ **Important:** JUnit XML **cannot update existing Xray tests** - it will always create new test cases. Only use this for Newman or test runners that don't support test keys.
-
-```bash
-npx xqt import-results --file results.xml --testExecKey QE-123
-```
-
-#### Playwright JSON (Recommended)
-
-✅ **Updates existing tests** via annotations. Use this format to link results to your existing Xray test cases.
-
-```bash
-# Generate JSON report in Playwright
-npx playwright test --reporter=json > playwright-results.json
-
-# Import to Xray (updates existing tests via annotations)
-npx xqt import-results --file playwright-results.json --testExecKey QE-123
-
-# Create new Test Execution automatically
-npx xqt import-results --file playwright-results.json --summary "Regression Suite"
-```
-
-**Required test code:**
-```typescript
-import { test, expect } from '@playwright/test';
-
-test('Verify API endpoint', async ({ request }) => {
-  // THIS LINE links to existing Xray test
-  test.info().annotations.push({ type: 'xray', description: 'PROJ-123' });
-  
-  // Your test code...
-});
-```
-
-| Option                      | Description                                       | Required |
-|-----------------------------|---------------------------------------------------|----------|
-| `--file <path>`             | Path to results file (.xml or .json)             | Yes      |
-| `--testExecKey <key>`       | Test Execution to link results to                | No*      |
-| `--summary <text>`          | Summary for new Test Execution (if no testExecKey) | No    |
-| `--description <text>`      | Description for new Test Execution               | No       |
-
-\* If `--testExecKey` is omitted, a new Test Execution will be created automatically.
-
-**Mapping Playwright Tests to Xray:**
-
-To link Playwright test results to existing Xray test cases, **you must use annotations**:
-
-```typescript
-// ✅ CORRECT - Updates existing test PROJ-123
-test('User login flow', async ({ page }) => {
-  test.info().annotations.push({ type: 'xray', description: 'PROJ-123' });
-  // ... test code
-});
-
-// ✅ Alternative - Include test key in title
-test('[PROJ-456] User registration validates email', async ({ page }) => {
-  // ... test code
-});
-
-// ❌ WRONG - Creates new test every time
-test('User login flow', async ({ page }) => {
-  // Missing annotation - will create duplicate test!
-  // ... test code
-});
-```
-
-**Without annotations:** A new test will be created in Xray with the test title as the summary (not recommended for existing tests).
-
----
-
-### `xqt gen-pipeline`
-
-Generate an Azure Pipelines YAML template.
-
-```bash
-npx xqt gen-pipeline
-npx xqt gen-pipeline --output ci/azure-pipelines.yml
-```
-
-| Option              | Description          | Default                |
-|---------------------|----------------------|------------------------|
-| `--output <path>`   | Output file path     | `azure-pipelines.yml`  |
-
-The generated pipeline:
-- Installs Node.js and dependencies
-- Runs Newman against `collection.postman.json`
-- Calls `import-results` with environment variables
-- Publishes JUnit test results
-
-**Note:** `edit-json` and QE review logic are NOT in the CI pipeline. Those happen pre-commit.
-
----
-
-### `xqt mcp-server`
-
-Start a Model Context Protocol server for GitHub Copilot agent-mode integration.
-
-```bash
-# Start MCP server in stdio mode (for agent integration)
-npx xqt mcp-server
-
-# Start in HTTP mode for testing (optional)
-npx xqt mcp-server --port 3100
-```
-
-| Option              | Description          | Default                |
-|---------------------|----------------------|------------------------|
-| `--port <n>`        | HTTP port (testing)  | stdio mode             |
-
-**MCP Tools Exposed:**
-- `generate_test_cases` — Generate tests from knowledge/ sources
-- `generate_postman` — Generate Postman collection with AI assertions
-- `analyze_knowledge` — List and summarize knowledge sources
-- `push_tests` — Push test cases to Xray Cloud
-- `analyze_spec` — Parse OpenAPI spec and extract endpoints
-
-**Status:** 🚧 Scaffold ready — AI provider connection not yet implemented. See [AI Setup](#ai-setup-optional) for implementation guidance.
-
-**Learn more:** [Model Context Protocol](https://modelcontextprotocol.io/)
-
-**Alternative:** `.vscode/xray-qe-participant/` contains a VS Code chat participant scaffold for GitHub Copilot integration.
-
----
-
-### `xqt compare-openapi`
-
-Compare an OpenAPI spec against an approved QA snapshot and fail the pipeline if breaking changes are detected.
-
-```bash
-# Basic comparison — exits 1 on breaking changes
-npx xqt compare-openapi \
-  --current ../api-repo/openapi.yaml \
-  --snapshot ./openapi.snapshot.yaml
-
-# Save a JSON diff report as a pipeline artifact
-npx xqt compare-openapi \
-  --current ../api-repo/openapi.yaml \
-  --snapshot ./openapi.snapshot.yaml \
-  --report openapi-diff-report.json
-```
-
-| Option               | Description                                                      | Required |
-|----------------------|------------------------------------------------------------------|----------|
-| `--current <path>`   | Path to the current (live) OpenAPI spec                          | Yes      |
-| `--snapshot <path>`  | Path to the approved QA baseline snapshot                        | Yes      |
-| `--report <path>`    | Write full diff results to a JSON file (useful as CI artifact)   | No       |
-
-**Behaviour:**
-- Snapshot = approved QA contract baseline
-- Current = proposed/live spec
-- Exits `0` if no breaking changes; logs a count of non-breaking differences
-- Exits `1` on any breaking change and prints the full diff
-- If `--report` is specified and breaking changes are found, a JSON report is written
-
-**Example Azure Pipelines step (from your test repo pipeline):**
-
-```yaml
-steps:
-  - checkout: self
-
-  - checkout: git://Project/portfolio-api
-    path: api-repo
-
-  - script: |
-      npx xqt compare-openapi \
-        --current api-repo/openapi.yaml \
-        --snapshot openapi.snapshot.yaml \
-        --report openapi-diff-report.json
-    displayName: Compare OpenAPI Contracts
-
-  - publish: openapi-diff-report.json
-    artifact: openapi-diff
-    condition: failed()
-```
-
-**Governance model:**
-- Dev repo is never modified by QE
-- QE test repo pipeline checks out the API repo and enforces the contract
-- Breaking change → pipeline fails → dev must fix spec or raise a contract change review
-- QE then runs `update-snapshot` to promote the new baseline
-
----
-
-### `xqt update-snapshot`
-
-Overwrite the QA snapshot baseline with the current spec. **Always a deliberate, manual action — never called automatically.**
-
-```bash
-npx xqt update-snapshot \
-  --current ../api-repo/openapi.yaml \
-  --snapshot ./openapi.snapshot.yaml
-```
-
-| Option               | Description                                         | Required |
-|----------------------|-----------------------------------------------------|----------|
-| `--current <path>`   | Path to the current (live) OpenAPI spec to promote  | Yes      |
-| `--snapshot <path>`  | Path to the snapshot file to overwrite              | Yes      |
-
-**Workflow:**
-1. Dev raises a contract change review
-2. QE approves the new contract
-3. QE runs `update-snapshot` locally
-4. QE raises a PR in the test repo with the updated snapshot
-5. PR is reviewed and merged — new baseline is established
-
-```bash
-# After merging the approved contract change:
-npx xqt update-snapshot \
-  --current ../api-repo/openapi.yaml \
-  --snapshot ./openapi.snapshot.yaml
-
-git add openapi.snapshot.yaml
-git commit -m "chore: promote OpenAPI snapshot to v2.5.0"
-git push
-```
-
----
-
-## Configuration
-
-### Environment Variables (.env)
-
-Create a `.env` file in your project root (or copy `.env.example`):
-
-| Variable          | Required | Description                                    |
-|-------------------|----------|------------------------------------------------|
-| `XRAY_ID`         | Yes      | Xray Cloud API Client ID                       |
-| `XRAY_SECRET`     | Yes      | Xray Cloud API Client Secret                   |
-| `JIRA_PROJECT_KEY` | Yes     | JIRA project key (e.g., `APIEE`, `QE`)         |
-| `JIRA_URL`        | Yes      | JIRA instance URL (e.g., `https://your-domain.atlassian.net`) |
-| `JIRA_API_TOKEN`  | Yes      | JIRA API token                                  |
-| `JIRA_EMAIL`      | Yes      | JIRA user email (must match Xray API Key owner) |
-| `XRAY_GRAPHQL_URL` | No      | Region-specific GraphQL endpoint (default: US)  |
-
-**Region-specific GraphQL endpoints:**
-
-| Region | URL |
-|--------|-----|
-| US (default) | `https://us.xray.cloud.getxray.app/api/v2/graphql` |
-| EU           | `https://eu.xray.cloud.getxray.app/api/v2/graphql` |
-| AU           | `https://au.xray.cloud.getxray.app/api/v2/graphql` |
-
-### Project Config (.xrayrc)
-
-Optional JSON file for non-sensitive project settings:
-
-```json
-{
-  "testsPath": "tests.json",
-  "mappingPath": "xray-mapping.json",
-  "collectionPath": "collection.postman.json"
-}
-```
-
----
-
-## File Reference
-
-### tests.json
-
-Source-of-truth for test definitions. Created by `init`, edited by `edit-json`, consumed by `push-tests` and `gen-postman`.
-
-```json
-{
-  "testExecution": {
-    "summary": "Sprint 24 - Automated Regression Suite",
-    "description": "API regression tests for Sprint 24 release"
-  },
-  "tests": [
-    {
-      "test_id": "TC-API-GET-001",
-      "skip": false,
-      "tags": ["regression", "smoke"],
-      "xray": {
-        "summary": "Verify GET /api/resource returns 200",
-        "description": "Test that the API returns expected data.",
-        "priority": "High",
-        "labels": ["API", "GET", "Regression"],
-        "steps": [
-          {
-            "action": "Send GET request to /api/resource/123",
-            "data": "Method: GET, Headers: Authorization: Bearer {token}",
-            "expected_result": "200 OK with resource object"
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-**Fields:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `test_id` | string | Yes | Unique identifier (alphanumeric, hyphens, underscores) |
-| `skip` | boolean | No | If `true`, excluded from `push-tests` |
-| `tags` | string[] | No | QE tags: `regression`, `smoke`, `edge`, `critical`, etc. |
-| `xray.summary` | string | Yes | JIRA issue title |
-| `xray.description` | string | No | JIRA issue description |
-| `xray.priority` | string | No | `Highest`, `High`, `Medium`, `Low`, `Lowest` |
-| `xray.labels` | string[] | No | JIRA labels |
-| `xray.steps[].action` | string | Yes | What action to perform |
-| `xray.steps[].data` | string | No | Input data / parameters |
-| `xray.steps[].expected_result` | string | Yes | Expected outcome |
-
-### xray-mapping.json
-
-Maps `test_id` → JIRA issue `{ key, id }`. Generated by `push-tests`, used for idempotent updates.
-
-```json
-{
-  "TC-API-GET-001": { "key": "APIEE-6933", "id": "1865623" },
-  "TC-API-POST-001": { "key": "APIEE-6934", "id": "1865627" },
-  "_testexecution": { "key": "APIEE-6941", "id": "1865637" }
-}
-```
-
----
-
-## Multi-Company Test Format
-
-This toolkit pushes tests into **one JIRA project per run** (via `JIRA_PROJECT_KEY`). For multiple companies, use consistent naming and keep per-company configs and files.
-
-**Recommended conventions:**
-- `test_id`: Prefix with company + domain + sequence, e.g. `ACME-BILLING-PAYMENTS-001`
-- `xray.summary`: Start with company or product tag, e.g. `[ACME] Payments - create invoice`
-- `xray.labels`: Add `company:<slug>`, `system:<slug>`, `team:<slug>` for filtering
-- `testExecution.summary`: Include company + release/sprint, e.g. `ACME - Sprint 12 Regression`
-
-**Example snippet:**
-
-```json
-{
-  "testExecution": {
-    "summary": "ACME - Sprint 12 Regression"
-  },
-  "tests": [
-    {
-      "test_id": "ACME-BILLING-PAYMENTS-001",
-      "tags": ["regression", "smoke"],
-      "xray": {
-        "summary": "[ACME] Payments - create invoice",
-        "labels": ["company:acme", "system:billing", "team:payments"],
-        "steps": [
-          {
-            "action": "Send POST /payments/invoices",
-            "expected_result": "201 Created"
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-**Per-company setup options:**
-- **Separate folders (recommended):** run `xray-qe init` once per company and keep `tests.json`, `xray-mapping.json`, `.env`, and `.xrayrc` isolated.
-- **Shared repo:** use a company-specific `.env` and `.xrayrc` (swap before running). Example `.xrayrc`:
-
-```json
-{
-  "testsPath": "tests.acme.json",
-  "mappingPath": "xray-mapping.acme.json",
-  "collectionPath": "collection.acme.postman.json"
-}
-```
-
----
-
-## Jira/Xray Project Setup
-
-Use this checklist to align a new team's board and Xray configuration with the toolkit:
-
-1. **Create a JIRA project** per company or business unit (Software or Service project).
-2. **Enable Xray** for the project and confirm issue types: **Test** and **Test Execution** (optional: Test Plan).
-3. **Configure screens/fields** to include Summary, Description, Priority, Labels, and Test Steps.
-4. **Set permissions** so the API user can create/edit Test and Test Execution issues.
-5. **Define components/labels** that match your naming conventions (company, system, team).
-6. **Create a board** with a filter like `project = KEY AND issuetype in (Test, "Test Execution")` and use components/labels for swimlanes.
-
----
-
-## QE Workflow
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         QE WORKFLOW (LOCAL)                             │
-│                                                                         │
-│  1. npx xqt init          ← scaffold project + knowledge/ folder  │
-│  2. Configure .env             ← credentials                           │
-│  3. Populate knowledge/        ← add API specs, requirements, tickets  │
-│     • knowledge/api-specs/     (OpenAPI, Swagger)                      │
-│     • knowledge/requirements/  (BRDs, logic docs)                      │
-│     • knowledge/tickets/       (JIRA exports, Confluence)              │
-│  4. npx xqt gen-tests --ai ← AI generates test cases from knowledge│
-│  5. npx xqt edit-json     ← QE REVIEW GATE (browser UI)           │
-│     • Review AI-generated tests                                        │
-│     • Add/edit/delete tests                                            │
-│     • Tag tests (regression, critical, etc.)                           │
-│     • Mark skip/push per test                                          │
-│     • Save & Exit                                                      │
-│  6. npx xqt push-tests    ← push to Xray Cloud                   │
-│  7. npx xqt gen-postman --ai ← generate Postman collection        │
-│  8. git commit & push          ← CI picks up from here                │
-│                                                                         │
-├─────────────────────────────────────────────────────────────────────────┤
-│                         CI PIPELINE (AUTOMATED)                         │
-│                                                                         │
-│  9. npm ci                     ← install deps                          │
-│  10. newman run collection.postman.json --reporters junit              │
-│  11. npx xqt import-results --file results.xml --testExecKey QE-123│
-│                                                                         │
-├─────────────────────────────────────────────────────────────────────────┤
-│                   CONTRACT ENFORCEMENT (TEST REPO PIPELINE)             │
-│                                                                         │
-│  12. Checkout API repo                                                  │
-│  13. npx xqt compare-openapi                                       │
-│        --current api-repo/openapi.yaml                                  │
-│        --snapshot openapi.snapshot.yaml                                 │
-│      → Fails pipeline on breaking changes                               │
-│                                                                         │
-│  (When QE approves a contract change)                                   │
-│  14. npx xqt update-snapshot                                       │
-│        --current api-repo/openapi.yaml                                  │
-│        --snapshot openapi.snapshot.yaml                                 │
-│      → Commit updated snapshot + raise PR                               │
-│                                                                         │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-## Playwright Quick Start
-
-### Complete Setup for Updating Existing Xray Tests
-
-This is the **recommended workflow** for teams using Playwright with existing Xray test cases.
-
-#### Step 1: Install Playwright (in your test repo)
-
-```bash
-npm install --save-dev @playwright/test
-```
-
-#### Step 2: Configure Playwright
-
-Create `playwright.config.ts` in your test repo:
-
-```typescript
-import { defineConfig } from '@playwright/test';
-
-export default defineConfig({
-  reporter: [
-    ['html'],  // For local viewing
-    ['json', { outputFile: 'playwright-results.json' }],  // For Xray import
-  ],
-  
-  use: {
-    baseURL: process.env.API_BASE_URL || 'https://your-api.com',
-    extraHTTPHeaders: {
-      'Authorization': `Bearer ${process.env.API_TOKEN}`,
-      'X-API-Key': process.env.API_KEY || '',
-    },
-  },
-});
-```
-
-#### Step 3: Write Tests with Xray Annotations
-
-⚠️ **Critical:** Every test MUST have an annotation to update existing Xray tests.
-
-```typescript
-import { test, expect } from '@playwright/test';
-
-test.describe('Regression Tests', () => {
-  
-  test('Verify API returns 200 for valid request', async ({ request }) => {
-    // THIS LINE links to your existing Xray test
-    test.info().annotations.push({ type: 'xray', description: 'APIEE-7131' });
-    
-    const response = await request.post('/api/verify', {
-      data: { userId: '123', action: 'validate' }
-    });
-    
-    // Attach response as evidence for Xray
-    test.info().attach('response-evidence', {
-      body: JSON.stringify({
-        status: response.status(),
-        headers: response.headers(),
-        body: await response.json()
-      }, null, 2),
-      contentType: 'application/json'
-    });
-    
-    expect(response.status()).toBe(200);
-  });
-  
-  test('Verify API returns 400 for invalid data', async ({ request }) => {
-    test.info().annotations.push({ type: 'xray', description: 'APIEE-7132' });
-    // ... test implementation
-  });
-  
-});
-```
-
-#### Step 4: Map All Your Tests
-
-Based on your `xray-mapping.json`, add annotations to each test:
-
-```typescript
-// If your xray-mapping.json shows:
-// "TC-001": { "key": "APIEE-7131", "id": "1879092" }
-// "TC-002": { "key": "APIEE-7132", "id": "1879095" }
-
-test('Test Case 1', async ({ request }) => {
-  test.info().annotations.push({ type: 'xray', description: 'APIEE-7131' });
-  // ...
-});
-
-test('Test Case 2', async ({ request }) => {
-  test.info().annotations.push({ type: 'xray', description: 'APIEE-7132' });
-  // ...
-});
-```
-
-#### Step 5: Run Locally
-
-```bash
-# Run tests
-npx playwright test
-
-# View HTML report
-npx playwright show-report
-
-# Upload to Xray (updates existing tests)
-npx xqt import-results --file playwright-results.json --testExecKey APIEE-6811
-```
-
-**What happens:**
-- ✅ Tests WITH annotations (`test.info().annotations.push(...)`) → Updates existing Xray tests
-- ⏭️ Tests WITHOUT annotations → **Automatically skipped** (won't create duplicates)
-- 📊 Summary shows: Passed, Failed, Skipped counts
-- 🔗 Direct link to view results in Xray
-
-**Verbose mode** (see exactly what's being uploaded):
-```bash
-npx xqt import-results \
-  --file playwright-results.json \
-  --testExecKey APIEE-6811 \
-  --verbose
-```
-
-This saves `playwright-results-xray-debug.json` for inspection.
-
-#### Step 6: Configure CI/CD
-
-**Azure Pipelines:**
-
-```yaml
-steps:
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '18.x'
-
-  - script: npm ci
-    displayName: 'Install dependencies'
-
-  - script: npx playwright test
-    displayName: 'Run Playwright tests'
-    continueOnError: true
-
-  - script: |
-      npx xqt import-results \
-        --file playwright-results.json \
-        --testExecKey APIEE-6811
-    displayName: 'Upload results to Xray'
-    env:
-      XRAY_ID: $(XRAY_ID)
-      XRAY_SECRET: $(XRAY_SECRET)
-      JIRA_PROJECT_KEY: $(JIRA_PROJECT_KEY)
-      JIRA_URL: $(JIRA_URL)
-      JIRA_API_TOKEN: $(JIRA_API_TOKEN)
-      JIRA_EMAIL: $(JIRA_EMAIL)
-```
-
-**GitHub Actions:**
-
-```yaml
-steps:
-  - uses: actions/setup-node@v3
-    with:
-      node-version: '18'
-
-  - run: npm ci
-
-  - run: npx playwright test
-
-  - run: |
-      npx xqt import-results \
-        --file playwright-results.json \
-        --testExecKey APIEE-6811
-    env:
-      XRAY_ID: ${{ secrets.XRAY_ID }}
-      XRAY_SECRET: ${{ secrets.XRAY_SECRET }}
-      JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT_KEY }}
-      JIRA_URL: ${{ secrets.JIRA_URL }}
-      JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
-      JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
-```
-
-### Benefits
-
-✅ **Updates existing tests** - No duplicate test creation  
-✅ **Automatic mapping** - Via annotations in test code  
-✅ **Evidence attachments** - Screenshots, responses, traces  
-✅ **Detailed reporting** - Retries, worker info, error details  
-✅ **CI/CD ready** - Standard workflow for automation  
-✅ **Single source of truth** - Test code + Xray together
-
----
-
-## Building Regression Packs
-
-Regression packs are curated test suites that verify your system still works after changes. The toolkit makes it easy to build and maintain regression packs using tags, AI-generated tests, and idempotent push.
-
-### 1. Organize Knowledge Sources by Domain
-
-```
-knowledge/
-├── api-specs/
-│   ├── auth-api.yaml        ← Authentication domain
-│   ├── users-api.yaml       ← User management
-│   └── payments-api.yaml    ← Payment processing
-├── requirements/
-│   ├── auth-flows.md
-│   ├── user-roles.md
-│   └── payment-validation.md
-└── tickets/
-    ├── APIEE-123.json       ← Login epic
-    ├── APIEE-456.json       ← Payment refactor epic
-    └── confluence-sso.html
-```
-
-### 2. Generate Tests by Domain
-
-```bash
-# Generate auth tests from auth spec
-npx xqt gen-tests --ai --spec knowledge/api-specs/auth-api.yaml
-
-# Generate payment tests
-npx xqt gen-tests --ai --spec knowledge/api-specs/payments-api.yaml
-
-# Generate from a specific ticket
-npx xqt gen-tests --ai --ticket APIEE-123
-```
-
-### 3. Tag Tests for Pack Categorization
-
-Use `edit-json` to assign tags:
-
-| Tag | Purpose |
-|-----|---------|
-| `regression` | Full regression pack — all core functionality |
-| `smoke` | Smoke test pack — critical paths only |
-| `critical` | Critical business flows (subset of regression) |
-| `edge` | Edge case and error handling tests |
-| `integration` | Multi-system integration tests |
-| `security` | Security and auth tests |
-| `performance` | Performance/load tests |
-
-**Example workflow:**
-1. Generate tests: `npx xqt gen-tests --ai`
-2. Open editor: `npx xqt edit-json`
-3. Add `regression` tag to all tests
-4. Add `smoke` tag to critical path tests
-5. Add `critical` tag to business-critical tests
-6. Save and push to Xray
-
-### 4. Filter and Run Specific Packs
-
-**In tests.json:**
-```json
-{
-  "tests": [
-    {
-      "test_id": "001",
-      "type": "api",
-      "tags": ["regression", "smoke", "critical"]
-    },
-    {
-      "test_id": "002",
-      "type": "api",
-      "tags": ["regression", "edge"]
-    },
-    {
-      "test_id": "003",
-      "type": "api",
-      "tags": ["regression"],
-      "skip": true
-    }
-  ]
-}
-```
-
-**Filtering in edit-json:**
-- Use the dropdown to filter by tag (e.g., show only `smoke` tests)
-- Mark tests as `skip: true` to exclude from push/generation
-
-**CI pipeline filtering:**
-- Generate smoke pack: filter `tests.json` to `tags.includes("smoke")` before `gen-postman`
-- Generate regression pack: filter to `tags.includes("regression")` and `skip !== true`
-- Schedule different packs on different cadences (smoke nightly, regression weekly)
-
-### 5. Maintain Packs Over Sprints
-
-**Idempotent push** keeps Xray in sync as your pack evolves:
-
-| Sprint Change | Action | Result |
-|---------------|--------|--------|
-| API endpoint added | `gen-tests --ai --spec new-api.yaml` → `edit-json` → `push-tests` | New tests created in Xray |
-| Test assertion updated | Edit in `edit-json` → `push-tests` | Existing test updated in Xray |
-| Test deprecated | Mark `skip: true` in `edit-json` → `push-tests` | Test excluded from future runs |
-| Requirements changed | Update `knowledge/requirements/` → `gen-tests --ai` | Regenerate affected tests |
-
-**Best practices:**
-- ✅ Regenerate tests when specs change (toolkit updates existing tests)
-- ✅ Use meaningful `test_id` values (`AUTH-LOGIN-001` instead of `001`)
-- ✅ Commit `tests.json` and `xray-mapping.json` to source control
-- ✅ Review AI-generated tests before pushing — they're scaffolds, not production-ready
-- ✅ Keep `knowledge/` up to date with your latest specs and docs
-
-### 6. Example: Sprint Regression Pack Workflow
-
-```bash
-# Sprint start: Generate tests from updated specs
-npx xqt gen-tests --ai
-
-# QE reviews and tags tests
-npx xqt edit-json
-# → Tag new tests with "regression"
-# → Mark experimental tests as "skip"
-# → Verify all critical paths have "smoke" tag
-
-# Push to Xray (creates new, updates existing)
-npx xqt push-tests
-
-# Generate Postman collection for CI
-npx xqt gen-postman --ai
-
-# Commit regression pack to repo
-git add tests.json xray-mapping.json collection.postman.json
-git commit -m "Sprint 24 regression pack"
-
-# CI runs nightly
-newman run collection.postman.json --folder "[smoke]"
-newman run collection.postman.json  # Full regression weekly
-```
-
----
-
-## Working with Existing Xray Tests
-
-If your team already has test cases in Xray Cloud that were created manually or by another tool, you can set up this toolkit to manage and update those existing tests.
-
-### Step 1: Query Existing Tests from Xray
-
-Use the Xray GraphQL API to fetch your existing tests. Here's a script to generate the mapping file:
-
-**fetch-existing-tests.js:**
-```javascript
-import { authenticate, loadConfig } from "@msalaam/xray-qe-toolkit";
-import fs from "fs";
-
-const cfg = loadConfig();
-const token = await authenticate(cfg);
-
-// GraphQL query to fetch all tests in your project
-const query = `
-  query {
-    getTests(jql: "project = ${cfg.jiraProjectKey} AND issuetype = Test", limit: 1000) {
-      total
-      results {
-        issueId
-        jira(fields: ["key", "summary", "description", "priority", "labels"])
-      }
-    }
-  }
-`;
-
-const response = await fetch(cfg.xrayGraphQLUrl || "https://us.xray.cloud.getxray.app/api/v2/graphql", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${token}`,
-  },
-  body: JSON.stringify({ query }),
-});
-
-const data = await response.json();
-const tests = data.data.getTests.results;
-
-// Generate xray-mapping.json
-const mapping = {};
-tests.forEach((test) => {
-  const testId = test.jira.key; // Use JIRA key as test_id initially
-  mapping[testId] = {
-    key: test.jira.key,
-    id: test.issueId,
-  };
-});
-
-fs.writeFileSync("xray-mapping.json", JSON.stringify(mapping, null, 2));
-console.log(`✓ Created xray-mapping.json with ${tests.length} tests`);
-
-// Generate tests.json scaffold
-const testsJson = {
-  testExecution: {
-    summary: "Existing Tests - Managed by Toolkit",
-    description: "Imported from existing Xray tests",
-  },
-  tests: tests.map((test) => ({
-    test_id: test.jira.key,
-    skip: false,
-    tags: [],
-    xray: {
-      summary: test.jira.summary,
-      description: test.jira.description || "",
-      priority: test.jira.priority?.name || "Medium",
-      labels: test.jira.labels || [],
-      steps: [
-        // You'll need to fetch test steps separately via another API call
-        {
-          action: "PLACEHOLDER - Edit this in npx xqt edit-json",
-          data: "",
-          expected_result: "PLACEHOLDER",
-        },
-      ],
-    },
-  })),
-};
-
-fs.writeFileSync("tests.json", JSON.stringify(testsJson, null, 2));
-console.log(`✓ Created tests.json with ${tests.length} test scaffolds`);
-console.log("\nNext steps:");
-console.log("1. Run 'npx xqt edit-json' to review and complete test steps");
-console.log("2. Run 'npx xqt push-tests' to update tests in Xray");
-```
-
-### Step 2: Run the Script
-
-```bash
-# Save the script above as fetch-existing-tests.js
-node fetch-existing-tests.js
-```
-
-This generates:
-- `xray-mapping.json` — maps your existing JIRA test keys to their IDs
-- `tests.json` — scaffold with summaries, descriptions, priorities, labels
-
-### Step 3: Complete Test Steps
-
-The script can't fetch test steps automatically (requires additional API calls). Complete them in the editor:
-
-```bash
-npx xqt edit-json
-# Edit each test to add proper steps
-# Save when done
-```
-
-### Step 4: Update Existing Tests
-
-Now you can update your existing Xray tests:
-
-```bash
-npx xqt push-tests
-```
-
-Because the tests are in `xray-mapping.json`, they'll be **updated** (not duplicated).
-
-### Alternative: Manual Mapping Creation
-
-If you have a small number of tests, create the mapping manually:
-
-**xray-mapping.json:**
-```json
-{
-  "APIEE-6933": { "key": "APIEE-6933", "id": "1865623" },
-  "APIEE-6934": { "key": "APIEE-6934", "id": "1865627" },
-  "APIEE-6935": { "key": "APIEE-6935", "id": "1865628" }
-}
-```
-
-**tests.json:**
-```json
-{
-  "tests": [
-    {
-      "test_id": "APIEE-6933",
-      "xray": {
-        "summary": "Test User Login",
-        "steps": [
-          { "action": "...", "expected_result": "..." }
-        ]
-      }
-    }
-  ]
-}
-```
-
-Then run `npx xqt push-tests` to update.
-
-### Future Enhancement: Pull Command
-
-A `pull-tests` command to automatically fetch and sync existing tests is planned:
-
-```bash
-# Future feature (not yet implemented)
-npx xqt pull-tests --project APIEE
-npx xqt pull-tests --jql "project = APIEE AND labels = regression"
-```
-
-This would automatically generate both `tests.json` and `xray-mapping.json` from Xray.
-
-**Want this feature?** [Open an issue on GitHub](https://github.com/Muhammad-Salaam_omit/xray-qe-toolkit/issues) or contribute via PR.
-
----
-
-## Idempotent Push
-
-`push-tests` checks `xray-mapping.json` before each operation:
-
-| Scenario | Action |
-|----------|--------|
-| `test_id` not in mapping | **Create** new JIRA Test issue + steps |
-| `test_id` in mapping | **Update** existing issue fields + replace steps |
-| `skip: true` | **Skip** entirely |
-
-This means you can safely run `push-tests` multiple times without creating duplicates.
-
----
-
-## Programmatic API
-
-All library functions are importable for custom scripts:
-
-```javascript
-import {
-  loadConfig,
-  validateConfig,
-  authenticate,
-  createIssue,
-  buildAndPush,
-  generatePostmanCollection,
-  logger,
-} from "@msalaam/xray-qe-toolkit";
-
-const cfg = loadConfig();
-validateConfig(cfg);
-
-const token = await authenticate(cfg);
-// ... use any exported function
-```
-
----
-
-## Troubleshooting
-
-### "disallowed to impersonate" / "no valid active user exists"
-
-Your `JIRA_EMAIL` doesn't match the Xray API Key owner.
-
-**Fix:**
-1. Ensure `JIRA_EMAIL` matches the email of the user who created the Xray API Key
-2. Verify the user has an active Xray license
-3. Regenerate the Xray API Key with the same user as `JIRA_API_TOKEN`
-
-### "issueId provided is not valid" (transient)
-
-Xray's GraphQL API needs time to index newly created JIRA issues. The toolkit automatically retries with exponential backoff (2s → 4s → 8s → 16s → 32s).
-
-If it still fails after 5 retries, wait a minute and try again.
-
-### Rate limiting / 429 errors
-
-The toolkit includes a 300ms delay between API calls. If you still hit rate limits, wait and retry. For very large test suites (100+), consider splitting across multiple runs.
-
-### Browser doesn't open for `edit-json`
-
-In headless environments, copy the URL printed in the terminal and open it manually.
-
----
-
-## License
-
-See LICENSE.
+# @msalaam/xray-qe-toolkit
+
+> QE toolkit for Xray Cloud — manage test definitions, sync to Jira/Xray, import Playwright results.
+
+[![npm version](https://badge.fury.io/js/%40msalaam%2Fxray-qe-toolkit.svg)](https://www.npmjs.com/package/@msalaam/xray-qe-toolkit)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [How It Works](#how-it-works)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Commands](#cli-commands)
+- [Configuration](#configuration)
+- [tests.json Reference](#testsjson-reference)
+- [Test Sets, Plans & Executions](#test-sets-plans--executions)
+- [Playwright Integration](#playwright-integration)
+- [xray-mapping.json](#xray-mappingjson)
+- [CI/CD Integration](#cicd-integration)
+- [Programmatic API](#programmatic-api)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+`@msalaam/xray-qe-toolkit` (CLI: `xqt`) manages the boundary between your local test definitions (`tests.json`) and Xray Cloud. It does not generate Playwright tests — those are created by a separate Copilot skill after Xray issue keys are known.
+
+**What it does:**
+
+- **`tests.json`** — single source of truth for test metadata (synced to Xray)
+- **Idempotent push** — creates new tests and Test Sets, updates existing ones, never duplicates
+- **Test Set management** — groups tests by feature, persistent across sprints
+- **Test Plan management** — create per-sprint plans, link Test Sets
+- **Test Executions** — auto-created per CI run, tagged by environment, linked to plan
+- **Playwright result import** — JSON reporter output → Xray with step-level results
+- **Xray folder sync** — organise the Test Repository from `folder` fields in tests.json
+- **Schema validation** — validate tests.json as a CI gate before pushing
+- **Visual editor** — browser-based editor for reviewing/editing tests.json
+
+> For the full spec-driven QE process — how `openapi.yaml` + `business-rules.yaml` become `tests.json`,
+> how Playwright tests are created, and how sprints are managed — see
+> **[SPEC-DRIVEN-APPROACH.md](SPEC-DRIVEN-APPROACH.md)** (scaffolded into every project by `xqt init`).
+
+---
+
+## How It Works
+
+```
+openapi.yaml + business-rules.yaml
+      ↓ (AI agent generates tests.json)
+tests.json — structured test definitions
+      ↓
+xqt validate   ← schema check
+      ↓
+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 plan → link Test Sets to Test Plan
+      ↓
+CI runs tests  ← xqt import → Test Execution in Xray
+```
+
+**Key design decisions:**
+- **Test Sets are persistent** — tests live in Test Sets grouped by feature
+- **Test Plans are per-sprint** — create one per sprint, link relevant Test Sets
+- **Test Executions are ephemeral** — every CI run creates a fresh execution
+- **Environments are labels** — `IOP-DEV`, `IOP-QA`, `IOP-PROD` tag each execution
+- **tests.json is the source of truth** — never edit test metadata directly in JIRA
+- **xray-mapping.json is auto-generated** — maps local `testId` → JIRA key; never edit manually
+- **Playwright tests come after push** — created only once `xray-mapping.json` has real Jira keys
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Xray Cloud** API credentials (Client ID + Client Secret) — from **Apps → Xray → API Keys**
+- **JIRA Cloud** API Token — from [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+
+---
+
+## Installation
+
+```bash
+# As a dev dependency (recommended)
+npm install --save-dev @msalaam/xray-qe-toolkit
+
+# Globally
+npm install -g @msalaam/xray-qe-toolkit
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Scaffold a new QA project
+npx xqt init
+
+# 2. Fill in credentials
+cp .env.example .env
+# Edit .env with XRAY_ID, XRAY_SECRET, JIRA_* values
+
+# 3. Place your API spec and business rules in resources/
+#    resources/api-specs/openapi.yaml
+#    resources/business-rules.yaml
+
+# 4. Generate tests.json from openapi.yaml + business-rules.yaml
+#    (done by AI agent / Copilot skill — reads both files, produces tests.json)
+
+# 5. Validate and push to Xray
+npx xqt validate
+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 plan --summary "Sprint 12 — My Service Regression"
+
+# 8. Run tests and import results
+npx playwright test
+npx xqt import --file test-results/results.json --env IOP-QA
+```
+
+---
+
+## CLI Commands
+
+All commands accept `--verbose` for debug output and `--env <path>` for a custom .env file path.
+
+---
+
+### `xqt init`
+
+Scaffold a QA project in the current directory. Idempotent — never overwrites existing files.
+
+Creates: `resources/` (API spec + business rules), `tests/` (models/services/resources/specs), `playwright.config.ts`, `tests.json`, `xray-mapping.json`, `.xrayrc`, `.env.example`, `XQT-GUIDE.md` (xqt command reference), `SPEC-DRIVEN-APPROACH.md` (QE process guide).
+
+```bash
+npx xqt init
+```
+
+---
+
+### `xqt edit`
+
+Launch a browser-based visual editor for `tests.json`. Use this to review, add, or update test definitions.
+
+```bash
+npx xqt edit
+npx xqt edit --port 3000
+```
+
+| Flag | Description | Default |
+|---|---|---|
+| `--port <n>` | Port for local editor server | Random |
+
+---
+
+### `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 plan --summary "My Service v2 Regression"
+npx xqt plan --summary "Sprint 12 Smoke Tests" --version "2024.12"
+```
+
+| Flag | Description |
+|---|---|
+| `--summary <text>` | Test Plan title **(required)** |
+| `--version <ver>` | Fix version to associate |
+| `--label <labels>` | Comma-separated JIRA labels |
+
+---
+
+### `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
+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
+- **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`
+
+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 --plan APIEE-1234
+npx xqt pull --project APIEE --limit 200
+```
+
+| Flag | Description |
+|---|---|
+| `--plan <key>` | Fetch tests from a specific Test Plan |
+| `--project <key>` | Fetch all tests in a JIRA project |
+| `--limit <n>` | Max tests to fetch (default: 100) |
+
+---
+
+### `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 --exec`.
+`create-execution` is accepted as a legacy alias.
+
+```bash
+# Standard output
+npx xqt exec --env IOP-QA
+
+# CI mode — prints ONLY the key
+EXEC_KEY=$(npx xqt exec --env IOP-QA --quiet)
+
+# Specific test selection
+npx xqt exec --env IOP-QA --plan APIEE-1234 --tests TC-001,TC-002
+```
+
+| Flag | Description |
+|---|---|
+| `--env <label>` | Environment label (e.g. `IOP-QA`) |
+| `--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 |
+| `--quiet` | Print only the execution key |
+
+> `xqt import` creates an execution automatically — this command is only needed when pre-selecting a specific subset of tests.
+
+---
+
+### `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
+
+Supported: Playwright JSON (`.json`) and JUnit XML (`.xml`).
+
+```bash
+# Auto-create execution (standard CI)
+npx xqt import --file test-results/results.json --env IOP-QA
+
+# Import into a pre-created execution
+npx xqt import --file test-results/results.json --exec APIEE-9876
+
+# JUnit XML
+npx xqt import --file test-results/results.xml --env IOP-PROD
+
+# Full options
+npx xqt import \
+  --file test-results/results.json \
+  --env IOP-QA \
+  --plan APIEE-1234 \
+  --version "2024.12" \
+  --revision "a1b2c3d4"
+```
+
+| Flag | Description |
+|---|---|
+| `--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 `xqt exec`) |
+| `--version <ver>` | Fix version / release label |
+| `--revision <rev>` | Build number or git SHA |
+| `--summary <text>` | Custom execution summary |
+
+---
+
+### `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
+```
+
+---
+
+### `xqt status`
+
+Show local and remote project status: tests.json counts, mapping coverage, Test Plan info.
+
+```bash
+npx xqt status
+npx xqt status --plan APIEE-1234
+```
+
+---
+
+### `xqt validate`
+
+Validate `tests.json` against its schema. Exits with code 1 on errors — use as a CI gate before `push-tests`.
+
+```bash
+npx xqt validate
+npx xqt validate --file path/to/tests.json
+```
+
+| Flag | Description |
+|---|---|
+| `--file <path>` | Override path to tests.json |
+
+---
+
+### `xqt pipeline`
+
+Generate an Azure Pipelines YAML template for the current project.
+`gen-pipeline` is accepted as a legacy alias.
+
+```bash
+npx xqt pipeline
+npx xqt pipeline --output .azure/ci.yml
+```
+
+---
+
+## Configuration
+
+### Environment Variables (.env)
+
+Copy `.env.example` to `.env` and fill in credentials. **Never commit `.env`.**
+
+```env
+# ── Xray Cloud ─────────────────────────────────────────────────
+XRAY_ID=your_xray_cloud_client_id
+XRAY_SECRET=your_xray_cloud_client_secret
+
+# ── JIRA ───────────────────────────────────────────────────────
+JIRA_PROJECT_KEY=APIEE
+JIRA_URL=https://your-org.atlassian.net
+JIRA_API_TOKEN=your_jira_api_token
+JIRA_EMAIL=your.email@company.com
+
+# ── Optional ───────────────────────────────────────────────────
+# XRAY_REGION=us                    # "us" (default) or "eu"
+# XQT_TEST_PLAN_KEY=APIEE-1234      # default Test Plan
+# XQT_DEFAULT_ENV=IOP-DEV           # default environment label
+```
+
+| Variable | Required | Description |
+|---|---|---|
+| `XRAY_ID` | Yes | Xray Cloud Client ID |
+| `XRAY_SECRET` | Yes | Xray Cloud Client Secret |
+| `JIRA_PROJECT_KEY` | Yes | JIRA project key |
+| `JIRA_URL` | Yes | JIRA instance URL |
+| `JIRA_API_TOKEN` | Yes | JIRA API token |
+| `JIRA_EMAIL` | Yes | JIRA user email |
+| `XRAY_REGION` | No | `us` (default) or `eu` |
+| `XQT_TEST_PLAN_KEY` | No | Default Test Plan key |
+| `XQT_DEFAULT_ENV` | No | Default environment label |
+
+---
+
+### Project Config (.xrayrc)
+
+`.xrayrc` (JSON) at the project root. Created by `xqt init`, updated by `xqt create-plan`.
+
+```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"
+}
+```
+
+| Field | Description |
+|---|---|
+| `testPlanKey` | Default Test Plan key for push-tests and import-results |
+| `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` |
+
+---
+
+## tests.json Reference
+
+`tests.json` is the canonical list of test cases. It is generated from `openapi.yaml` + `business-rules.yaml` by an AI agent, then consumed by `xqt push-tests` to sync with Xray Cloud.
+
+```json
+{
+  "testPlan": {
+    "key": "APIEE-1234",
+    "summary": "Sprint 12 — My Service API Regression"
+  },
+  "tests": [
+    {
+      "test_id": "TC-MYSVC-BR-001",
+      "type": "api",
+      "skip": false,
+      "tags": ["smoke", "regression"],
+      "folder": "/MyService/HealthCheck/Validation",
+      "testSet": "Health Check",
+      "requirementKeys": [],
+      "xray": {
+        "summary": "Service returns 200 OK when healthy",
+        "description": "Given Service is running, when GET /health is called, then Response is 200",
+        "testType": "Generic",
+        "definition": "Automated Playwright API test: GET /health — Service returns 200 OK when healthy",
+        "priority": "High",
+        "labels": ["smoke", "regression"]
+      }
+    }
+  ]
+}
+```
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `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. 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 |
+| `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 |
+| `xray.testType` | string | — | `Generic` (default for automated) / `Manual` / `Cucumber` |
+| `xray.definition` | string | — | Generic test definition field in Xray |
+| `xray.priority` | string | — | `Highest` / `High` / `Medium` / `Low` / `Lowest` |
+| `xray.labels` | string[] | — | JIRA labels on the test issue |
+
+---
+
+## Test Sets, Plans & Executions
+
+### Test Sets (persistent groupings)
+
+Tests live in **Test Sets** in Jira. Each Test Set groups related tests by feature or area — they persist across every sprint.
+
+Set the `testSet` field on each test in `tests.json`:
+
+```json
+{ "test_id": "TC-001", "testSet": "Client Lookup", ... }
+{ "test_id": "TC-002", "testSet": "Client Lookup", ... }
+{ "test_id": "TC-003", "testSet": "Health Check",  ... }
+```
+
+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
+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 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`)
+- `xqt import` links executions to the active plan
+
+### Test Executions (ephemeral per run)
+
+A Test Execution represents a single CI run.
+
+- **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
+
+### Summary
+
+| Concept | Lifecycle | Purpose |
+|---------|-----------|---------|
+| **Test Set** | Permanent | Groups tests by feature — where tests live |
+| **Test Plan** | Per-sprint | Scopes testing for a sprint — links Test Sets |
+| **Test Execution** | Per-CI-run | Records pass/fail for one run |
+
+### Three execution modes
+
+**Mode A — Auto (standard CI):**
+```bash
+npx xqt import --file results.json --env IOP-QA
+```
+
+**Mode B — Pre-create (controlled test selection):**
+```bash
+EXEC_KEY=$(npx xqt exec --env IOP-QA --plan APIEE-1234 --quiet)
+npx playwright test
+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
+```
+
+---
+
+## Playwright Integration
+
+### Annotate tests with Xray keys
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('GET /users returns 200', async ({ request }) => {
+  test.info().annotations.push({ type: 'xray', description: 'APIEE-1234' });
+
+  const response = await request.get('/users');
+  expect(response.status()).toBe(200);
+});
+```
+
+Or include the key in the test title:
+
+```typescript
+test('[APIEE-1234] GET /users returns 200', async ({ request }) => { ... });
+```
+
+### playwright.config.ts reporters
+
+```typescript
+reporter: [
+  ['json',  { outputFile: 'test-results/results.json' }],  // ← xqt import-results
+  ['junit', { outputFile: 'test-results/results.xml'  }],
+  ['html',  { open: 'never' }],
+],
+```
+
+### Test steps → Xray step results
+
+Steps created with `test.step()` are mapped to Xray step results automatically:
+
+```typescript
+test('Create and retrieve user', async ({ request }) => {
+  test.info().annotations.push({ type: 'xray', description: 'APIEE-2001' });
+
+  await test.step('POST /users — expect 201', async () => {
+    const r = await request.post('/users', { data: { name: 'Alice' } });
+    expect(r.status()).toBe(201);
+  });
+
+  await test.step('GET /users/:id — expect 200', async () => {
+    const r = await request.get('/users/1');
+    expect(r.status()).toBe(200);
+  });
+});
+```
+
+---
+
+## Folder Structure in Xray
+
+Tests are organised in the Xray Test Repository using the `folder` field in `tests.json`:
+
+```json
+{
+  "test_id": "TC-MYSVC-BR-001",
+  "folder": "/MyService/HealthCheck/Validation"
+}
+```
+
+- Paths must start with `/`
+- `folderRoot` in `.xrayrc` sets the base path
+- Folders are created automatically by `xqt push` and `xqt sync`
+
+---
+
+## CI/CD Integration
+
+### Azure DevOps pipeline
+
+Generate a template: `npx xqt pipeline`
+
+```yaml
+- script: npx xqt validate
+  displayName: Validate tests.json
+
+- script: npx playwright test
+  displayName: Run tests
+  continueOnError: true
+
+- script: |
+    npx xqt import \
+      --file test-results/results.json \
+      --env $(XQT_ENV)
+  displayName: Import results to Xray
+  env:
+    XRAY_ID:          $(XRAY_ID)
+    XRAY_SECRET:      $(XRAY_SECRET)
+    JIRA_PROJECT_KEY: $(JIRA_PROJECT_KEY)
+    JIRA_URL:         $(JIRA_URL)
+    JIRA_API_TOKEN:   $(JIRA_API_TOKEN)
+    JIRA_EMAIL:       $(JIRA_EMAIL)
+```
+
+### Required pipeline variables
+
+| Variable | Description |
+|---|---|
+| `XRAY_ID` | Xray Cloud Client ID |
+| `XRAY_SECRET` | Xray Cloud Client Secret |
+| `JIRA_PROJECT_KEY` | JIRA project key |
+| `JIRA_URL` | JIRA instance URL |
+| `JIRA_API_TOKEN` | JIRA API token |
+| `JIRA_EMAIL` | JIRA user email |
+| `XQT_ENV` | Environment label (`IOP-DEV` / `IOP-QA` / `IOP-PROD`) |
+
+### Pre-create execution in pipeline (Mode B)
+
+```yaml
+- script: |
+    EXEC_KEY=$(npx xqt exec --env $(XQT_ENV) --quiet)
+    echo "##vso[task.setvariable variable=EXEC_KEY]$EXEC_KEY"
+  displayName: Pre-create Test Execution
+
+- script: npx playwright test
+  continueOnError: true
+
+- script: |
+    npx xqt import --file test-results/results.json --exec $(EXEC_KEY)
+  displayName: Import results into pre-created execution
+```
+
+---
+
+## Programmatic API
+
+Every function is exported for custom scripts:
+
+```javascript
+import {
+  loadConfig,
+  authenticate,
+  createTestExecution,
+  importResultsMultipart,
+  getTestPlan,
+  syncTestPlan,
+} from '@msalaam/xray-qe-toolkit';
+
+const cfg = loadConfig();
+const token = await authenticate(cfg);
+
+const { key } = await createTestExecution(cfg, token, {
+  summary: 'My custom execution',
+  environments: ['IOP-QA'],
+  testPlanKey: 'APIEE-1234',
+});
+```
+
+Key exports: `authenticate`, `createIssue`, `updateIssue`, `getIssue`, `getTest`, `getTests`, `getTestPlan`, `createTestPlan`, `addTestsToTestPlan`, `addTestsToTestExecution`, `createTestExecution`, `importResultsMultipart`, `importTestsBulk`, `syncTestPlan`, `syncFolders`, `buildAndPush`, `loadMapping`, `saveMapping`, `loadConfig`, `validateConfig`.
+
+---
+
+## xray-mapping.json
+
+Auto-managed by `xqt push`. Maps local `test_id` → JIRA issue key and numeric Xray ID.
+
+```json
+{
+  "TC-MYSVC-BR-001": {
+    "key": "APIEE-1234",
+    "id":  "8765432"
+  },
+  "TC-MYSVC-BR-002": {
+    "key": "APIEE-1235",
+    "id":  "8765433"
+  }
+}
+```
+
+- **Commit this file** — the whole team must share the same mapping
+- Used by Copilot skill to generate Playwright tests with real Jira keys
+- Do not edit manually
+- Re-push to regenerate a missing entry
+
+---
+
+## Troubleshooting
+
+**Missing credentials**
+```
+Error: Missing required config: xrayId, xraySecret
+```
+Ensure `.env` exists and is populated.
+
+**Test not found in mapping after push**
+```bash
+npx xqt status
+npx xqt push --verbose
+```
+
+**Import results — 0 tests matched**
+Ensure Playwright tests have `xray` annotations or the key in the title:
+```typescript
+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`.
+
+**"disallowed to impersonate" error**
+`JIRA_EMAIL` must match the email of the user who created the Xray API Key.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)