@msalaam/xray-qe-toolkit 1.4.0 → 1.4.1

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;
-}

package/templates/knowledge-README.md

@@ -1,121 +0,0 @@
-# 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.