@msalaam/xray-qe-toolkit 1.3.4 → 1.4.1

package/templates/resources-README.md

@@ -0,0 +1,112 @@
+# Resources — AI Test Generation Sources
+
+This folder contains documentation and specifications used by the AI agent to generate test cases for Xray.
+
+---
+
+## Folder Structure
+
+```
+resources/
+├── 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`
+- **GraphQL schemas** — `.graphql`, `.gql`
+
+Files in this folder drive model, service, assertion, and spec generation via the spec-driven workflow.
+
+### `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** (AI agent reads these files and populates `tests.json`)
+   - Reads `openapi.yaml` (API shape) and `business-rules.yaml` (domain rules)
+   - Produces `tests.json` entries with stable `test_id` values for Xray traceability
+   - Each `business-rules.yaml` rule maps 1:1 to a `tests.json` entry
+   - See **[SPEC-DRIVEN-APPROACH.md](../SPEC-DRIVEN-APPROACH.md)** for the full workflow
+
+2. **Xray Sync** (after `tests.json` is generated)
+   - `npx xqt validate` then `npx xqt push-tests`
+   - Creates Xray Test issues + Test Sets in Jira
+   - Populates `xray-mapping.json` with issue keys
+
+3. **Playwright Test Creation** (after Xray sync)
+   - Copilot skill reads `tests.json` + `xray-mapping.json`
+   - Creates one Playwright `test()` call per `tests.json` entry
+   - Real Jira keys in test titles from day one
+
+4. **Continuous Refinement**
+   - As you add/update specs and business rules, re-run the generation workflow
+   - The toolkit is **idempotent** — existing tests are updated, retired rules get `skip: true`
+   - Always validate before pushing: `npx xqt validate` then `npx xqt push-tests`
+
+---
+
+## 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 your OpenAPI spec
+cp ~/Downloads/my-api.yaml resources/openapi.yaml
+
+# 2. Populate business rules (or generate a draft from the spec)
+# Use Copilot + SPEC-DRIVEN-APPROACH.md to generate resources/business-rules.yaml
+
+# 3. Validate knowledge artifacts
+npx xqt validate --schema business-rules
+
+# 4. Use Copilot (spec-driven workflow) to generate models, services, assertions, and specs
+# See SPEC-DRIVEN-APPROACH.md for the full step-by-step
+
+# 5. Validate tests.json
+npx xqt validate
+
+# 6. Push tests to Xray
+npx xqt push-tests
+
+# 7. Run tests and import results
+npx playwright test
+npx xqt import-results --file test-results/results.json
+```
+
+---
+
+**Note:** This folder is the knowledge input for the spec-driven workflow. See **[SPEC-DRIVEN-APPROACH.md](../SPEC-DRIVEN-APPROACH.md)** for the complete greenfield/brownfield generation process.

package/templates/tests.json

@@ -1,74 +1,92 @@
 {
-  "testExecution": {
-    "summary": "My Project - Regression Suite",
-    "description": "Automated regression tests for My Project API"
+  "testPlan": {
+    "key": "",
+    "summary": "My Service — Test Plan"
   },
   "tests": [
     {
-      "test_id": "TC-API-001",
+      "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 with all dependencies reachable, when GET /health is called, then Response is 200 with body { \"status\": \"ok\" }",
+        "testType": "Generic",
+        "definition": "Automated Playwright API test: GET /health — Service returns 200 OK when healthy",
+        "priority": "High",
+        "labels": ["smoke", "regression"]
+      }
+    },
+    {
+      "test_id": "TC-MYSVC-BR-002",
+      "type": "api",
+      "skip": false,
+      "tags": ["regression", "security"],
+      "folder": "/MyService/ExampleFeature/Authorization",
+      "testSet": "Example Feature",
+      "requirementKeys": [],
+      "xray": {
+        "summary": "Unauthenticated requests are rejected",
+        "description": "Given No Authorization header is provided, when Any protected endpoint is called, then Response is 401 Unauthorized",
+        "testType": "Generic",
+        "definition": "Automated Playwright API test: GET /api/v1/resource — Unauthenticated requests are rejected",
+        "priority": "Highest",
+        "labels": ["regression", "security"]
+      }
+    },
+    {
+      "test_id": "TC-MYSVC-BR-003",
       "type": "api",
       "skip": false,
       "tags": ["regression", "smoke"],
+      "folder": "/MyService/ExampleFeature/BusinessLogic",
+      "testSet": "Example Feature",
+      "requirementKeys": [],
       "xray": {
-        "summary": "Verify successful response for valid request",
-        "description": "Test that the API returns the expected data and status code for a valid, well-formed request.",
+        "summary": "Valid resource creation returns 201 with resource id",
+        "description": "Given Authenticated user with create permission, when POST /api/v1/resource with valid body, then Response is 201 with { \"id\": \"<uuid>\" } and Location header",
+        "testType": "Generic",
+        "definition": "Automated Playwright API test: POST /api/v1/resource — Valid resource creation returns 201 with resource id",
         "priority": "High",
-        "labels": ["API", "Positive", "Regression"],
-        "steps": [
-          {
-            "action": "Send GET request to /api/resource with valid parameters",
-            "data": "Method: GET, Headers: Authorization: Bearer {token}, Params: id=1",
-            "expected_result": "API returns HTTP 200 with resource object"
-          },
-          {
-            "action": "Validate response body structure",
-            "data": "Response body JSON",
-            "expected_result": "Response contains expected fields: id, name, status"
-          }
-        ]
+        "labels": ["regression", "smoke"]
       }
     },
     {
-      "test_id": "TC-API-002",
+      "test_id": "TC-MYSVC-BR-004",
       "type": "api",
       "skip": false,
-      "tags": ["regression", "negative"],
+      "tags": ["regression", "edge"],
+      "folder": "/MyService/ExampleFeature/Validation",
+      "testSet": "Example Feature",
+      "requirementKeys": [],
       "xray": {
-        "summary": "Verify error response for invalid request",
-        "description": "Test that the API returns a descriptive error when invalid or missing input is provided.",
-        "priority": "Medium",
-        "labels": ["API", "Negative", "Validation"],
-        "steps": [
-          {
-            "action": "Send POST request to /api/resource with missing required fields",
-            "data": "Method: POST, Headers: Authorization: Bearer {token}, Body: {}",
-            "expected_result": "API returns HTTP 400 Bad Request"
-          },
-          {
-            "action": "Validate error response body",
-            "data": "Response body JSON",
-            "expected_result": "Response contains 'error' field with a descriptive message string"
-          }
-        ]
+        "summary": "Missing required fields return 400 with field-level errors",
+        "description": "Given Authenticated user, when POST /api/v1/resource with missing required fields, then Response is 400 with errors array listing each missing field",
+        "testType": "Generic",
+        "definition": "Automated Playwright API test: POST /api/v1/resource — Missing required fields return 400 with field-level errors",
+        "priority": "High",
+        "labels": ["regression", "edge"]
       }
     },
     {
-      "test_id": "TC-API-003",
+      "test_id": "TC-MYSVC-BR-005",
       "type": "api",
-      "skip": true,
-      "tags": ["edge", "performance"],
+      "skip": false,
+      "tags": ["regression", "edge"],
+      "folder": "/MyService/ExampleFeature/Edge",
+      "testSet": "Example Feature",
+      "requirementKeys": [],
       "xray": {
-        "summary": "Verify API handles large payload within acceptable time",
-        "description": "Test that the API processes a large request payload without timeout or degraded response.",
-        "priority": "Low",
-        "labels": ["API", "Performance", "Edge"],
-        "steps": [
-          {
-            "action": "Send POST request to /api/resource with large payload",
-            "data": "Method: POST, Headers: Authorization: Bearer {token}, Body: large JSON array with 1000 items",
-            "expected_result": "API returns HTTP 200 within 3000ms"
-          }
-        ]
+        "summary": "Resource id not found returns 404",
+        "description": "Given Authenticated user, when GET /api/v1/resource/{id} with non-existent id, then Response is 404 with standard error body",
+        "testType": "Generic",
+        "definition": "Automated Playwright API test: GET /api/v1/resource/{id} — Resource id not found returns 404",
+        "priority": "Medium",
+        "labels": ["regression", "edge"]
       }
     }
   ]

package/commands/genPostman.js

@@ -1,70 +0,0 @@
-/**
- * Command: xray-qe gen-postman [--base-url <url>] [--ai] [--spec <path>] [--knowledge <path>]
- *
- * Generates a Postman Collection v2.1 JSON file from tests.json.
- * Optionally uses xray-mapping.json to embed JIRA keys for better traceability.
- * With --ai flag, enables AI-assisted generation (requires connected provider).
- */
-
-import fs from "node:fs";
-import logger, { setVerbose } from "../lib/logger.js";
-import { loadConfig } from "../lib/config.js";
-import { generate } from "../lib/postmanGenerator.js";
-import { loadMapping } from "../lib/testCaseBuilder.js";
-
-export default async function genPostman(opts = {}) {
-  if (opts.verbose) setVerbose(true);
-
-  logger.rocket("@msalaam/xray-qe-toolkit — Generate Postman Collection\n");
-
-  const cfg = loadConfig({ envPath: opts.env });
-
-  if (!fs.existsSync(cfg.testsPath)) {
-    logger.error(`tests.json not found at ${cfg.testsPath}`);
-    logger.info("Run 'npx xray-qe init' to create a starter tests.json");
-    process.exit(1);
-  }
-
-  const testsConfig = JSON.parse(fs.readFileSync(cfg.testsPath, "utf8"));
-
-  // Load mapping to embed JIRA keys when available
-  const mapping = loadMapping(cfg.mappingPath);
-
-  // Filter out skipped tests
-  const filteredConfig = {
-    ...testsConfig,
-    tests: (testsConfig.tests || []).filter((t) => !t.skip),
-  };
-
-  // AI flag handling
-  if (opts.ai) {
-    logger.info("🤖 AI-assisted generation enabled");
-    logger.warn("AI provider not yet connected — using schema-driven generation as fallback");
-    logger.blank();
-  }
-
-  // Knowledge path override
-  const knowledgePath = opts.knowledge || cfg.knowledgePath;
-  if (opts.knowledge) {
-    logger.info(`Using custom knowledge path: ${knowledgePath}`);
-  }
-
-  // Spec file handling (schema-driven generation without AI)
-  if (opts.spec && fs.existsSync(opts.spec)) {
-    logger.info(`Using OpenAPI spec: ${opts.spec}`);
-    logger.info("📝 Schema-driven endpoint inference enabled");
-    // TODO: Parse OpenAPI spec and enhance endpoint/method/body inference
-    logger.blank();
-  }
-
-  generate(filteredConfig, cfg.collectionPath, {
-    baseUrl: opts.baseUrl || "{{baseUrl}}",
-    mapping: mapping,
-  });
-
-  logger.blank();
-  logger.success(`Collection saved to ${cfg.collectionPath}`);
-  logger.info("Import into Postman or run with Newman:");
-  console.log(`   npx newman run ${cfg.collectionPath}`);
-  logger.blank();
-}

package/lib/postmanGenerator.js

@@ -1,304 +0,0 @@
-/**
- * @msalaam/xray-qe-toolkit — Postman Collection Generator
- *
- * Generates a Postman Collection v2.1 JSON from tests.json.
- * Each test becomes a request folder; steps map to request items with
- * pre-request scripts and test assertions.
- *
- * The output is a working starting point — QEs or agents can further
- * refine the generated collection.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import logger from "./logger.js";
-
-/**
- * Generate a Postman v2.1 collection from tests.json config.
- *
- * @param {object}   testsConfig   Parsed tests.json content
- * @param {string}   outputPath    Where to write collection.postman.json
- * @param {object}   [opts]        Options
- * @param {string}   [opts.baseUrl]  Base URL placeholder (default: "{{baseUrl}}")
- * @param {object}   [opts.mapping]  xray-mapping.json content (for embedding JIRA keys)
- * @returns {object} The generated collection object
- */
-export function generate(testsConfig, outputPath, opts = {}) {
-  const baseUrl = opts.baseUrl || "{{baseUrl}}";
-  const mapping = opts.mapping || {};
-  const tests = testsConfig.tests || [];
-
-  // Filter for API tests only (type: "api" or unset for backward compatibility)
-  const apiTests = tests.filter((t) => !t.type || t.type === "api");
-
-  const collection = {
-    info: {
-      name: testsConfig.testExecution?.summary || "Generated Test Collection",
-      description:
-        (testsConfig.testExecution?.description || "Auto-generated by @msalaam/xray-qe-toolkit") +
-        "\n\n⚠️ SCAFFOLD: This is a generated starting point. Review and enhance each request with proper assertions, environment variables, and edge cases before use.",
-      schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
-      _postman_id: generateUUID(),
-    },
-    variable: [
-      {
-        key: "baseUrl",
-        value: "https://api.example.com",
-        type: "string",
-      },
-      {
-        key: "authToken",
-        value: "",
-        type: "string",
-      },
-    ],
-    auth: {
-      type: "bearer",
-      bearer: [
-        {
-          key: "token",
-          value: "{{authToken}}",
-          type: "string",
-        },
-      ],
-    },
-    item: apiTests.map((test) => buildTestFolder(test, baseUrl, mapping)),
-  };
-
-  fs.writeFileSync(outputPath, JSON.stringify(collection, null, 2));
-  logger.save(`Collection written to ${path.basename(outputPath)}`);
-  logger.info(`${apiTests.length} API test(s) → ${countRequests(collection)} request(s)`);
-  if (tests.length > apiTests.length) {
-    logger.info(`${tests.length - apiTests.length} non-API tests skipped (use type: "api" to include)`);
-  }
-
-  return collection;
-}
-
-// ─── Internal builders ────────────────────────────────────────────────────────
-
-/**
- * Convert a single test definition into a Postman folder with request items.
- */
-function buildTestFolder(test, baseUrl, mapping = {}) {
-  // Use JIRA key if available in mapping, otherwise use test_id
-  const testKey = mapping[test.test_id]?.key || test.test_id;
-  
-  const folder = {
-    name: `[${testKey}] ${test.xray.summary}`,
-    description: test.xray.description || "",
-    item: [],
-  };
-
-  if (!test.xray.steps || test.xray.steps.length === 0) {
-    // No steps — create a single placeholder request
-    folder.item.push(buildPlaceholderRequest(test, baseUrl));
-    return folder;
-  }
-
-  test.xray.steps.forEach((step, idx) => {
-    folder.item.push(buildStepRequest(test, step, idx + 1, baseUrl));
-  });
-
-  return folder;
-}
-
-/**
- * Build a request item from a test step.
- */
-function buildStepRequest(test, step, stepNum, baseUrl) {
-  // Try to infer HTTP method and path from the step action/data
-  const { method, endpoint } = inferEndpoint(step);
-
-  const item = {
-    name: `Step ${stepNum}: ${truncate(step.action, 80)}`,
-    request: {
-      method,
-      header: [
-        {
-          key: "Content-Type",
-          value: "application/json",
-        },
-      ],
-      url: {
-        raw: `${baseUrl}${endpoint}`,
-        host: [baseUrl],
-        path: endpoint.split("/").filter(Boolean),
-      },
-    },
-    event: [],
-  };
-
-  // Add pre-request script with step data context
-  if (step.data) {
-    item.event.push({
-      listen: "prerequest",
-      script: {
-        type: "text/javascript",
-        exec: [
-          `// Step Data: ${step.data}`,
-          `// Action: ${step.action}`,
-          `console.log("Executing: ${escapeJs(step.action)}");`,
-        ],
-      },
-    });
-
-    // Try to extract request body from step data
-    const body = extractBody(step.data);
-    if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
-      item.request.body = {
-        mode: "raw",
-        raw: body,
-        options: { raw: { language: "json" } },
-      };
-    }
-  }
-
-  // Add test script with expected result assertion
-  if (step.expected_result) {
-    item.event.push({
-      listen: "test",
-      script: {
-        type: "text/javascript",
-        exec: buildTestScript(step),
-      },
-    });
-  }
-
-  return item;
-}
-
-/**
- * Build a placeholder request when a test has no steps.
- */
-function buildPlaceholderRequest(test, baseUrl) {
-  return {
-    name: test.xray.summary,
-    request: {
-      method: "GET",
-      header: [],
-      url: {
-        raw: `${baseUrl}/TODO`,
-        host: [baseUrl],
-        path: ["TODO"],
-      },
-      description: `TODO: Configure this request for test ${test.test_id}`,
-    },
-  };
-}
-
-/**
- * Infer HTTP method and endpoint from step action/data text.
- */
-function inferEndpoint(step) {
-  const combined = `${step.action} ${step.data || ""}`;
-  const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
-
-  let method = "GET";
-  let endpoint = "/api/TODO";
-
-  // Look for explicit HTTP method
-  for (const m of methods) {
-    if (combined.toUpperCase().includes(m)) {
-      method = m;
-      break;
-    }
-  }
-
-  // Look for a path pattern like /api/something or /endpoint
-  const pathMatch = combined.match(/(?:\/[\w{}\-]+){1,10}/);
-  if (pathMatch) {
-    endpoint = pathMatch[0];
-  }
-
-  return { method, endpoint };
-}
-
-/**
- * Build Postman test script lines from an expected result.
- */
-function buildTestScript(step) {
-  const lines = [
-    `// Expected: ${step.expected_result}`,
-    "",
-  ];
-
-  const expected = step.expected_result.toLowerCase();
-
-  // Infer status code assertions
-  const statusMatch = expected.match(/(\d{3})\s/);
-  if (statusMatch) {
-    lines.push(`pm.test("Status code is ${statusMatch[1]}", function () {`);
-    lines.push(`    pm.response.to.have.status(${statusMatch[1]});`);
-    lines.push(`});`);
-    lines.push("");
-  }
-
-  // Check for schema vSCAFFOLDation mentions
-  if (expected.includes("schema") || expected.includes("required fields")) {
-    lines.push(`pm.test("Response has expected schema", function () {`);
-    lines.push(`    const json = pm.response.json();`);
-    lines.push(`    // TODO: Add schema assertions based on expected fields`);
-    lines.push(`    pm.expect(json).to.be.an("object");`);
-    lines.push(`});`);
-    lines.push("");
-  }
-
-  // Check for error message mentions
-  if (expected.includes("error") || expected.includes("400") || expected.includes("401")) {
-    lines.push(`pm.test("Error response format", function () {`);
-    lines.push(`    const json = pm.response.json();`);
-    lines.push(`    pm.expect(json).to.have.property("error");`);
-    lines.push(`});`);
-    lines.push("");
-  }
-
-  // Always add a general assertion
-  lines.push(`pm.test("${escapeJs(truncate(step.expected_result, 100))}", function () {`);
-  lines.push(`    pm.response.to.be.ok;`);
-  lines.push(`});`);
-
-  return lines;
-}
-
-/**
- * Try to extract a JSON body from step data text.
- */
-function extractBody(data) {
-  // Look for JSON object in the data field
-  const jsonMatch = data.match(/\{[\s\S]*\}/);
-  if (jsonMatch) {
-    try {
-      JSON.parse(jsonMatch[0]);
-      return jsonMatch[0];
-    } catch {
-      return jsonMatch[0]; // Return raw even if not valid JSON
-    }
-  }
-  return null;
-}
-
-// ─── Utilities ────────────────────────────────────────────────────────────────
-
-function truncate(str, max) {
-  return str.length > max ? str.slice(0, max - 3) + "..." : str;
-}
-
-function escapeJs(str) {
-  return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
-}
-
-function generateUUID() {
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = (Math.random() * 16) | 0;
-    return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
-  });
-}
-
-function countRequests(collection) {
-  let count = 0;
-  for (const folder of collection.item) {
-    count += folder.item ? folder.item.length : 1;
-  }
-  return count;
-}