@msalaam/xray-qe-toolkit 1.1.0

package/templates/README.template.md

@@ -0,0 +1,161 @@
+# Xray QE Toolkit Project
+
+> Quality Engineering workflow automation for Xray Cloud integration
+
+## Quick Start
+
+### 1. Configure Credentials
+
+```bash
+# Copy the template and fill in your credentials
+cp .env.example .env
+```
+
+Edit `.env` with your Xray Cloud and JIRA credentials:
+
+```env
+XRAY_ID=your_xray_client_id
+XRAY_SECRET=your_xray_client_secret
+JIRA_PROJECT_KEY=YOUR_PROJECT
+JIRA_URL=https://your-domain.atlassian.net
+JIRA_API_TOKEN=your_jira_api_token
+JIRA_EMAIL=your.email@company.com
+```
+
+**Important:** Both Xray and JIRA credentials must belong to the same user.
+
+### 2. Add Your Documentation
+
+Populate the `knowledge/` folder with your API specs and requirements:
+
+```
+knowledge/
+├── api-specs/       ← OpenAPI/Swagger specs (.yaml, .json)
+├── requirements/    ← Business requirements (.md, .pdf, .docx)
+└── tickets/         ← JIRA exports, Confluence pages
+```
+
+See [knowledge/README.md](knowledge/README.md) for details.
+
+### 3. Create Test Cases
+
+**Option A: Manual (No AI required)**
+```bash
+# Open the visual editor
+npx xqt edit-json
+```
+
+**Option B: AI-Assisted (Requires setup)**
+```bash
+# Generate from knowledge sources
+npx xqt gen-tests --ai
+
+# Then review in the editor
+npx xqt edit-json
+```
+
+### 4. Push to Xray Cloud
+
+```bash
+npx xqt push-tests
+```
+
+### 5. Generate Postman Collection
+
+```bash
+npx xqt gen-postman
+```
+
+### 6. Set Up CI Pipeline
+
+```bash
+# Generate Azure Pipelines template
+npx xqt gen-pipeline
+```
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx xqt init` | Scaffold new project (already done) |
+| `npx xqt gen-tests` | Generate test cases from knowledge/ |
+| `npx xqt edit-json` | Review/edit tests in browser |
+| `npx xqt push-tests` | Push tests to Xray Cloud |
+| `npx xqt gen-postman` | Generate Postman collection |
+| `npx xqt gen-pipeline` | Generate CI pipeline template |
+| `npx xqt create-execution` | Create Test Execution issue |
+| `npx xqt import-results` | Import test results (CI) |
+
+Run any command with `--help` for details:
+```bash
+npx xqt gen-tests --help
+```
+
+## Workflow
+
+```
+1. Add docs to knowledge/
+2. Generate tests (AI or manual)
+3. Review in edit-json
+4. Push to Xray
+5. Generate Postman collection
+6. Run in CI (newman + import-results)
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `tests.json` | Test definitions (source of truth) |
+| `xray-mapping.json` | Maps test IDs to JIRA keys |
+| `collection.postman.json` | Generated Postman collection |
+| `.env` | Credentials (DO NOT COMMIT) |
+| `.xrayrc` | Project config |
+| `knowledge/` | API specs and requirements |
+
+## Multi-Company Test Format
+
+If you work across multiple companies or business units, keep a consistent naming pattern:
+
+- `test_id`: `COMPANY-AREA-FLOW-###` (e.g., `ACME-BILLING-PAYMENTS-001`)
+- `xray.summary`: prefix with `[COMPANY]` for easy filtering
+- `xray.labels`: add `company:<slug>`, `system:<slug>`, `team:<slug>`
+- `testExecution.summary`: include company + release/sprint
+
+For multiple companies, keep separate configs and files (recommended), or swap `.env` and `.xrayrc` before running.
+
+## Jira/Xray Board Alignment
+
+1. Create a JIRA project per company/team and enable Xray.
+2. Ensure issue types include **Test** and **Test Execution**.
+3. Add fields to screens: Summary, Description, Priority, Labels, Test Steps.
+4. Grant API user permissions to create/edit Test and Test Execution issues.
+5. Create a board with a filter for your project and those issue types.
+6. Use components/labels that match your naming conventions.
+
+## Tags
+
+Use tags in `edit-json` to organize test suites:
+
+- `regression` — Full regression pack
+- `smoke` — Critical path tests only
+- `critical` — Business-critical flows
+- `edge` — Edge cases and error handling
+- `integration` — Multi-system tests
+
+## Need Help?
+
+```bash
+# Show all commands
+npx xqt --help
+
+# Show command-specific help
+npx xqt push-tests --help
+
+# Enable debug output
+npx xqt push-tests --verbose
+```
+
+## Package Documentation
+
+Full documentation: https://www.npmjs.com/package/@msalaam/xray-qe-toolkit

package/templates/azure-pipelines.yml

@@ -0,0 +1,65 @@
+# ──────────────────────────────────────────────────────────────
+# Azure DevOps Pipeline — Xray QE Regression Runner
+# Generated by @msalaam/xray-qe-toolkit
+# ──────────────────────────────────────────────────────────────
+#
+# This pipeline runs Newman against the generated Postman collection
+# and imports results into Xray Cloud.
+#
+# IMPORTANT: edit-json and QE review gates are NOT part of CI.
+# Those steps must be run locally before committing.
+#
+# Required pipeline variables (set in Azure DevOps UI → Variables):
+#   XRAY_ID, XRAY_SECRET, JIRA_PROJECT_KEY, JIRA_URL,
+#   JIRA_API_TOKEN, JIRA_EMAIL, TEST_EXEC_KEY
+# ──────────────────────────────────────────────────────────────
+
+trigger:
+  branches:
+    include:
+      - main
+      - release/*
+
+pool:
+  vmImage: "ubuntu-latest"
+
+variables:
+  NODE_VERSION: "18.x"
+
+steps:
+  - task: NodeTool@0
+    displayName: "Install Node.js $(NODE_VERSION)"
+    inputs:
+      versionSpec: "$(NODE_VERSION)"
+
+  - script: |
+      npm ci
+    displayName: "Install dependencies"
+
+  - script: |
+      npx newman run collection.postman.json \
+        --reporters cli,junit \
+        --reporter-junit-export results.xml \
+        --suppress-exit-code
+    displayName: "Run Newman tests"
+
+  - script: |
+      npx xqt import-results \
+        --file results.xml \
+        --testExecKey $(TEST_EXEC_KEY)
+    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)
+
+  - task: PublishTestResults@2
+    displayName: "Publish JUnit results"
+    inputs:
+      testResultsFormat: "JUnit"
+      testResultsFiles: "results.xml"
+      mergeTestResults: true
+      failTaskOnFailedTests: true

package/templates/knowledge-README.md

@@ -0,0 +1,121 @@
+# Knowledge Base — AI Test Generation Resources
+
+This folder contains documentation and specifications used by the AI agent to generate test cases for Xray.
+
+---
+
+## Folder Structure
+
+```
+knowledge/
+├── api-specs/          OpenAPI/Swagger specifications (YAML/JSON)
+├── requirements/       Business requirements, acceptance criteria, logic docs
+└── tickets/            Exported JIRA tickets, Confluence pages, user stories
+```
+
+---
+
+## Supported File Types
+
+### `api-specs/`
+- **OpenAPI 3.x / Swagger 2.0** — `.yaml`, `.yml`, `.json`
+- **Postman collections** — `.postman_collection.json`
+- **GraphQL schemas** — `.graphql`, `.gql`
+
+Files in this folder are used to generate API test cases with accurate endpoints, methods, request/response schemas, and authentication patterns.
+
+### `requirements/`
+- **Markdown** — `.md`
+- **Plain text** — `.txt`
+- **Word documents** — `.docx`
+- **PDFs** — `.pdf`
+
+Business logic, acceptance criteria, workflow descriptions, and domain rules. Used to generate test scenarios, edge cases, and validation logic.
+
+### `tickets/`
+- **JIRA exports** — `.json`, `.xml`
+- **Confluence HTML exports** — `.html`
+- **User stories** — `.md`, `.txt`
+
+Ticket acceptance criteria and linked documentation. Used to ensure test coverage aligns with stories and epics.
+
+---
+
+## How the AI Agent Uses These Files
+
+1. **Test Case Generation** (`npx xqt gen-tests --ai`)
+   - Analyzes all files in `knowledge/`
+   - Generates structured test cases in `tests.json` format
+   - Infers test IDs, priorities, tags, and step-by-step actions
+   - Groups related tests by domain/feature
+
+2. **Postman Collection Generation** (`npx xqt gen-postman --ai`)
+   - Combines `tests.json` with `knowledge/api-specs/`
+   - Generates executable Postman requests with:
+     - Real endpoints from OpenAPI specs
+     - Request bodies matching schemas
+     - Assertions based on expected responses
+     - Environment variables for base URLs, tokens
+
+3. **Continuous Refinement**
+   - As you add/update specs and docs, re-run generation commands
+   - The toolkit is **idempotent** — existing tests are updated, not duplicated
+   - Always review generated tests via `npx xqt edit-json` before pushing to Xray
+
+---
+
+## Best Practices
+
+✅ **DO:**
+- Keep specs up to date with your API implementation
+- Organize files by feature/domain for easier tracking
+- Use descriptive filenames (e.g., `auth-api-v2.yaml`, `payment-flows.md`)
+- Commit this folder to source control (Git)
+
+⚠️ **DON'T:**
+- Store credentials or secrets in these files
+- Include massive binary files (>10MB) — extract relevant sections
+- Mix unrelated specs in the same file
+- Forget to update specs when the API changes
+
+---
+
+## Example Workflow
+
+```bash
+# 1. Add an OpenAPI spec
+cp ~/Downloads/api-spec.yaml knowledge/api-specs/users-api.yaml
+
+# 2. Add business requirements
+echo "Users must be able to reset passwords via email" > knowledge/requirements/password-reset.md
+
+# 3. Generate test cases from knowledge
+npx xqt gen-tests --ai
+
+# 4. Review and edit generated tests
+npx xqt edit-json
+
+# 5. Push approved tests to Xray
+npx xqt push-tests
+
+# 6. Generate Postman collection with AI-enhanced assertions
+npx xqt gen-postman --ai
+
+# 7. Run tests in CI
+newman run collection.postman.json
+```
+
+---
+
+## V2 Roadmap: UI Testing with Playwright
+
+In the next version, this folder will also support:
+- **Page object models** — `.ts` definitions
+- **User journey diagrams** — `.drawio`, `.svg`
+- **Accessibility standards** — WCAG checklists
+
+The toolkit will generate Playwright test scripts (`*.spec.ts`) for UI regression packs.
+
+---
+
+**Note:** The `--ai` flag requires a connected AI provider (e.g., GitHub Copilot, Azure OpenAI). Without it, commands fall back to schema-driven generation where applicable.

package/templates/tests.json

@@ -0,0 +1,72 @@
+{
+  "testExecution": {
+    "summary": "Sprint XX - Automated Regression Suite",
+    "description": "Automated test execution covering API regression tests. Generate test cases from knowledge/ folder using: npx xray-qe gen-tests --ai"
+  },
+  "tests": [
+    {
+      "test_id": "TC-API-GET-001",
+      "type": "api",
+      "tags": ["regression", "smoke"],
+      "xray": {
+        "summary": "Verify GET /api/resource returns 200 with valid data",
+        "description": "SCAFFOLD: This is an example test. Generate real tests from knowledge/ using 'npx xray-qe gen-tests --ai' or edit manually via 'npx xray-qe edit-json'.",
+        "priority": "High",
+        "labels": ["API", "GET", "Regression"],
+        "steps": [
+          {
+            "action": "Send GET request to /api/resource/123",
+            "data": "Method: GET, Endpoint: /api/resource/123, Headers: Authorization: Bearer {token}",
+            "expected_result": "API returns 200 OK with resource object containing id, name, and status fields"
+          },
+          {
+            "action": "Validate response schema",
+            "data": "Expected schema: { id: number, name: string, status: string }",
+            "expected_result": "Response matches expected schema and all required fields are present"
+          }
+        ]
+      }
+    },
+    {
+      "test_id": "TC-API-POST-001",
+      "type": "api",
+      "tags": ["regression"],
+      "xray": {
+        "summary": "VeriSCAFFOLD: Example test demonstrating POST operations. Replace with tests generated from your API specifications
+        "description": "Test that a new resource is created successfully via POST with valid payload.",
+        "priority": "Medium",
+        "labels": ["API", "POST", "CRUD"],
+        "steps": [
+          {
+            "action": "Send POST request with valid payload",
+            "data": "Method: POST, Endpoint: /api/resource, Body: {\"name\": \"New Resource\", \"type\": \"demo\"}",
+            "expected_result": "API returns 201 Created with resource ID and location header"
+          },
+          {
+            "action": "Verify resource was persisted",
+            "data": "Method: GET, Endpoint: /api/resource/{newId}",
+            "expected_result": "GET returns the newly created resource with matching name and type"
+          }
+        ]
+      }
+    },
+    {
+      "test_id": "TC-API-ERR-400",
+      "type": "api",
+      "tags": ["regression", "edge"],
+      "xray": {
+        "summary": "VeriSCAFFOLD: Example error handling test. Generate comprehensive validation tests from your API specs and requirements
+        "description": "Test that the API returns proper error response when invalid data is submitted.",
+        "priority": "Medium",
+        "labels": ["API", "ErrorHandling", "Validation"],
+        "steps": [
+          {
+            "action": "Send POST request with missing required field",
+            "data": "Method: POST, Endpoint: /api/resource, Body: {} (empty)",
+            "expected_result": "API returns 400 Bad Request with descriptive error message"
+          }
+        ]
+      }
+    }
+  ]
+}

package/templates/xray-mapping.json

@@ -0,0 +1 @@
+{}