pw-automation-framework 2.0.1

package/src/utils/elementHighlight.ts

@@ -0,0 +1,174 @@
+import { Page } from "playwright";
+
+/**
+ * elementHighlight.ts
+ * ===================
+ * Injects a visual highlight into the browser window BEFORE the framework
+ * interacts with an element. This lets the user watching the automation
+ * clearly see which field is being targeted.
+ *
+ * Visual effects:
+ *   • Glowing border (blue for input/click, orange for verify/assertion)
+ *   • Ripple pulse animation
+ *   • Small floating label showing the step action + value
+ *   • Auto-removes after the interaction completes (or on timeout)
+ *
+ * Usage (in handlers):
+ *   await highlightElement(this.page, locatorString, 'input', 'Ravi');
+ *   // ... do the actual interaction ...
+ *   await removeHighlight(this.page);
+ */
+
+type HighlightType = "input" | "click" | "verify" | "select" | "checkbox";
+
+const COLORS: Record<HighlightType, { border: string; bg: string; label: string }> = {
+  input:    { border: "#3b82f6", bg: "rgba(59,130,246,0.08)",  label: "#3b82f6" },
+  click:    { border: "#22c55e", bg: "rgba(34,197,94,0.08)",   label: "#22c55e" },
+  verify:   { border: "#a855f7", bg: "rgba(168,85,247,0.08)",  label: "#a855f7" },
+  select:   { border: "#f59e0b", bg: "rgba(245,158,11,0.08)",  label: "#f59e0b" },
+  checkbox: { border: "#ec4899", bg: "rgba(236,72,153,0.08)",  label: "#ec4899" },
+};
+
+/**
+ * Highlights an element in the browser before interacting with it.
+ *
+ * @param page         Playwright Page
+ * @param locator      CSS/XPath locator string (already built)
+ * @param type         Visual type: input | click | verify | select | checkbox
+ * @param labelText    Short text shown in the floating label (e.g. the value being entered)
+ */
+export async function highlightElement(
+  page:      Page,
+  locator:   string,
+  type:      HighlightType = "input",
+  labelText: string        = "",
+): Promise<void> {
+  const c = COLORS[type];
+
+  try {
+    await page.evaluate(
+      ({ locator, border, bg, labelColor, labelText }) => {
+        // ── Find element ──────────────────────────────────────────────────────
+        let el: Element | null = null;
+
+        if (locator.startsWith("//") || locator.startsWith("(//") || locator.startsWith("./")) {
+          // XPath
+          const result = document.evaluate(locator, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+          el = result.singleNodeValue as Element | null;
+        } else {
+          // CSS
+          try { el = document.querySelector(locator); } catch { /* bad selector */ }
+        }
+
+        if (!el || !(el instanceof HTMLElement)) return;
+
+        // ── Remove any previous highlight ─────────────────────────────────────
+        document.querySelectorAll("[data-pw-highlight]").forEach(n => {
+          const orig = (n as HTMLElement).dataset.pwOrigStyle ?? "";
+          (n as HTMLElement).style.cssText = orig;
+          delete (n as HTMLElement).dataset.pwHighlight;
+          delete (n as HTMLElement).dataset.pwOrigStyle;
+        });
+        document.querySelectorAll("#pw-overlay,#pw-label,#pw-ripple-style").forEach(n => n.remove());
+
+        // ── Store original style ───────────────────────────────────────────────
+        el.dataset.pwHighlight  = "1";
+        el.dataset.pwOrigStyle  = el.style.cssText;
+
+        // ── Apply highlight styles ─────────────────────────────────────────────
+        el.style.outline        = `2px solid ${border}`;
+        el.style.outlineOffset  = "2px";
+        el.style.boxShadow      = `0 0 0 4px ${bg}, 0 0 16px ${border}55`;
+        el.style.transition     = "outline .15s, box-shadow .15s";
+        el.style.zIndex         = "9999";
+
+        // ── Scroll element into view (smooth) ─────────────────────────────────
+        el.scrollIntoView({ behavior: "smooth", block: "center", inline: "nearest" });
+
+        // ── Ripple pulse animation ─────────────────────────────────────────────
+        const style = document.createElement("style");
+        style.id = "pw-ripple-style";
+        style.textContent = `
+          @keyframes pwRipple {
+            0%   { box-shadow: 0 0 0 0 ${border}66, 0 0 0 0 ${border}33; }
+            50%  { box-shadow: 0 0 0 6px ${border}33, 0 0 0 12px ${border}11; }
+            100% { box-shadow: 0 0 0 0 ${border}00, 0 0 0 0 ${border}00; }
+          }
+        `;
+        document.head.appendChild(style);
+        el.style.animation = "pwRipple .7s ease-out";
+
+        // ── Floating label ─────────────────────────────────────────────────────
+        if (labelText) {
+          const rect  = el.getBoundingClientRect();
+          const label = document.createElement("div");
+          label.id    = "pw-label";
+
+          const scrollX = window.scrollX || document.documentElement.scrollLeft;
+          const scrollY = window.scrollY || document.documentElement.scrollTop;
+
+          // Position above the element; clamp to viewport
+          const top  = Math.max(scrollY + rect.top - 36, scrollY + 4);
+          const left = Math.min(
+            Math.max(scrollX + rect.left, scrollX + 4),
+            scrollX + document.documentElement.clientWidth - 240,
+          );
+
+          Object.assign(label.style, {
+            position:     "absolute",
+            top:          `${top}px`,
+            left:         `${left}px`,
+            zIndex:       "2147483647",
+            background:   "#0a0d14",
+            color:        labelColor,
+            border:       `1px solid ${border}`,
+            borderRadius: "6px",
+            padding:      "3px 10px",
+            fontSize:     "12px",
+            fontFamily:   "-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif",
+            fontWeight:   "600",
+            pointerEvents:"none",
+            whiteSpace:   "nowrap",
+            maxWidth:     "260px",
+            overflow:     "hidden",
+            textOverflow: "ellipsis",
+            boxShadow:    "0 4px 14px rgba(0,0,0,.5)",
+            animation:    "pwFadeIn .15s ease",
+          });
+
+          const styleTag = document.createElement("style");
+          styleTag.textContent = "@keyframes pwFadeIn{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:none}}";
+          document.head.appendChild(styleTag);
+
+          label.textContent = `⚡ ${labelText.length > 40 ? labelText.slice(0, 37) + "…" : labelText}`;
+          document.body.appendChild(label);
+        }
+      },
+      { locator, border: c.border, bg: c.bg, labelColor: c.label, labelText },
+    );
+  } catch {
+    // Highlight is purely cosmetic — never throw
+  }
+}
+
+/**
+ * Removes the visual highlight from the page.
+ * Called after the interaction completes (or on failure).
+ */
+export async function removeHighlight(page: Page): Promise<void> {
+  try {
+    await page.evaluate(() => {
+      document.querySelectorAll("[data-pw-highlight]").forEach(n => {
+        const el = n as HTMLElement;
+        el.style.cssText   = el.dataset.pwOrigStyle ?? "";
+        el.style.animation = "";
+        delete el.dataset.pwHighlight;
+        delete el.dataset.pwOrigStyle;
+      });
+      document.querySelectorAll("#pw-overlay,#pw-label,#pw-ripple-style").forEach(n => n.remove());
+      document.querySelectorAll("style[textContent*='pwFadeIn'],style[textContent*='pwRipple']").forEach(n => n.remove());
+    });
+  } catch {
+    // Cosmetic — never throw
+  }
+}

package/src/utils/locatorHelper.ts

@@ -0,0 +1,49 @@
+/**
+ * buildLocatorString
+ * ==================
+ * Converts strategy + value → Playwright selector string.
+ * Supports all standard and Playwright-native strategies.
+ */
+export function buildLocatorString(strategy: string, value: string): string {
+  switch (strategy.toLowerCase().replace(/[_\s-]/g, "")) {
+    case "xpath":
+      return `xpath=${value}`;
+    case "css":
+    case "cssselector":
+      return value;
+    case "id":
+      return `#${value}`;
+    case "name":
+      return `[name="${value}"]`;
+    case "placeholder":
+      return `[placeholder="${value}"]`;
+    case "text":
+    case "linktext":
+      return `text=${value}`;
+    case "partiallinktext":
+    case "partialtext":
+      return `text=${value}`;
+    case "classname":
+    case "class":
+      return `.${value}`;
+    case "tagname":
+    case "tag":
+      return value;
+    case "testid":
+    case "datatestid":
+      return `[data-testid="${value}"]`;
+    case "label":
+      return `label=${value}`;
+    case "arialabel":
+      return `[aria-label="${value}"]`;
+    case "role":
+      return `[role="${value}"]`;
+    case "title":
+      return `[title="${value}"]`;
+    case "value":
+      return `[value="${value}"]`;
+    default:
+      console.warn(`[WARN] Unknown strategy "${strategy}", treating as CSS`);
+      return value;
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,40 @@
+import { LogLevel, LogEntry } from "../types/types";
+
+const COLORS: Record<LogLevel, string> = {
+  DEBUG: "\x1b[36m",  // cyan
+  INFO:  "\x1b[32m",  // green
+  WARN:  "\x1b[33m",  // yellow
+  ERROR: "\x1b[31m",  // red
+};
+const RESET = "\x1b[0m";
+
+export class Logger {
+  private executionId: string;
+  private context: string;
+
+  constructor(context: string, executionId: string = "global") {
+    this.context     = context;
+    this.executionId = executionId;
+  }
+
+  private log(level: LogLevel, message: string, extra?: Record<string, any>): void {
+    const ts    = new Date().toISOString();
+    const color = COLORS[level];
+    const tag   = `[${level}][${this.context}]`;
+    const extra_str = extra ? ` ${JSON.stringify(extra)}` : "";
+    console.log(`${color}${ts} ${tag}${RESET} ${message}${extra_str}`);
+  }
+
+  debug(msg: string, ctx?: Record<string, any>) { this.log("DEBUG", msg, ctx); }
+  info (msg: string, ctx?: Record<string, any>) { this.log("INFO",  msg, ctx); }
+  warn (msg: string, ctx?: Record<string, any>) { this.log("WARN",  msg, ctx); }
+  error(msg: string, ctx?: Record<string, any>) { this.log("ERROR", msg, ctx); }
+
+  child(context: string): Logger {
+    return new Logger(`${this.context}:${context}`, this.executionId);
+  }
+
+  static create(context: string, executionId?: string): Logger {
+    return new Logger(context, executionId);
+  }
+}

package/src/utils/response.ts

@@ -0,0 +1,27 @@
+import { ActionResponse } from "../types/types";
+
+export function pass(comments: string, screenshot?: string, data?: any): ActionResponse {
+  return { status: "Pass", comments, screenshot, data };
+}
+
+export function fail(comments: string, errorDetail?: string, screenshot?: string, data?: any): ActionResponse {
+  const message = errorDetail ? `${comments} — ${errorDetail}` : comments;
+  return { status: "Fail", comments: message, screenshot, data };
+}
+export function failElementNotFound(
+  displayLabel: string,
+  screenshot?: string,
+  extraData?: Record<string, any>,
+): ActionResponse {
+  return {
+    status: "Fail",
+    comments: `"${displayLabel}" not found`,
+    screenshot,
+    data: {
+      expected_result: `"${displayLabel}" found and interacted with`,
+      failure_type: "ELEMENT_NOT_FOUND",
+      ...extraData,
+    },
+  };
+}
+

package/src/utils/responseFormatter.ts

@@ -0,0 +1,167 @@
+/**
+ * responseFormatter.ts
+ * ====================
+ * Converts internal framework types → the standard API response format
+ * that matches what the main application expects.
+ *
+ * Standard format example:
+ * {
+ *   "status": "fail",
+ *   "results": [
+ *     {
+ *       "test_script_uid": "...",
+ *       "app_id": "...",
+ *       "status": "fail",
+ *       "results": [
+ *         {
+ *           "uid": null,
+ *           "obj_uid": "...",
+ *           "step_name": "...",
+ *           "page_uid": null,
+ *           "comments": "...",
+ *           "screenshot": "base64...",
+ *           "duration": "8 seconds",
+ *           "start_time": "2026-04-04 20:25:34",
+ *           "expected_result": "...",
+ *           "status": "pass"
+ *         }
+ *       ],
+ *       "duration": "42 seconds",
+ *       "script_start_time": "2026-04-04 20:25:34"
+ *     }
+ *   ]
+ * }
+ */
+
+import { ExecutionResult, ScriptResult, StepResult } from "../types/types";
+// import { ActionResponse } from "../types/types";
+
+// ─── Formatted types (what the main app expects) ──────────────────────────────
+
+export interface FormattedStepResult {
+  uid:             string | null;
+  obj_uid:         string | null;
+  step_name:       string;
+  step_script?:    string;
+  page_uid:        string | null;
+  comments:        string;
+  screenshot?:     string;
+  duration:        string;         // e.g. "8 seconds"
+  start_time:      string;         // e.g. "2026-04-04 20:25:34"
+  expected_result: string;
+  status:          "pass" | "fail" | "skip";
+  comparison_code?: any;
+}
+
+export interface FormattedScriptResult {
+  test_script_uid:   string;
+  app_id:            string | undefined;
+  status:            "pass" | "fail";
+  results:           FormattedStepResult[];
+  duration:          string;   // e.g. "42 seconds"
+  script_start_time: string;   // e.g. "2026-04-04 20:25:34"
+  comparison_code?:  any;
+}
+
+export interface FormattedExecutionResponse {
+  status:           "pass" | "fail";
+  executionId:      string;
+  results:          FormattedScriptResult[];
+  // Extra metadata (can be ignored by main app)
+  total_scripts:    number;
+  passed_scripts:   number;
+  failed_scripts:   number;
+  total_duration:   string;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Format milliseconds → "X seconds" or "less than 1 second"
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return "less than 1 second";
+  const secs = Math.round(ms / 1000);
+  return `${secs} second${secs !== 1 ? "s" : ""}`;
+}
+
+/**
+ * Format ISO timestamp → "YYYY-MM-DD HH:MM:SS"
+ */
+export function formatDateTime(isoString: string): string {
+  try {
+    const d = new Date(isoString);
+    const pad = (n: number) => String(n).padStart(2, "0");
+    return (
+      `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+      `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+    );
+  } catch {
+    return isoString;
+  }
+}
+
+
+/**
+ * Map internal StepStatus to lowercase API status
+ */
+function mapStepStatus(status: string): "pass" | "fail" | "skip" {
+  switch (status?.toUpperCase()) {
+    case "PASS":    return "pass";
+    case "FAIL":    return "fail";
+    case "SKIP":
+    case "RUNNING":
+    case "PENDING": return "skip";
+    default:        return "skip";
+  }
+}
+
+// ─── Formatters ──────────────────────────────────────────────────────────────
+
+export function formatStepResult(step: StepResult): FormattedStepResult {
+  return {
+    uid:             step.uid      ?? null,
+    obj_uid:         step.obj_uid  ?? null,
+    step_name:       step.step_name,
+    step_script:     step.step_script,
+    page_uid:        step.page_uid ?? null,
+    comments:        step.skip_reason
+                       ? `Skipped — ${step.skip_reason}`
+                       : (step.comments || ""),
+    screenshot:      step.screenshot,
+    duration:        formatDuration(step.duration_ms),
+    start_time:      formatDateTime(step.start_time),
+    expected_result: step.expected_result || "",
+    status:          mapStepStatus(step.status),
+    //  comparison_code: step.comparison_code,
+  };
+}
+
+export function formatScriptResult(script: ScriptResult): FormattedScriptResult {
+  const failedStep = script.step_results.find(s => s.comparison_code);  // ← this line
+  return {
+    test_script_uid:   script.test_script_uid,
+    app_id:            script.app_id,
+    status:            script.overall_status === "PASS" ? "pass" : "fail",
+    results:           script.step_results.map(formatStepResult),
+    duration:          formatDuration(script.duration_ms),
+    script_start_time: formatDateTime(script.start_time),
+     comparison_code:   failedStep?.comparison_code,
+    
+  };
+}
+
+export function formatExecutionResult(result: ExecutionResult): FormattedExecutionResponse {
+  const formattedResults = result.results.map(formatScriptResult);
+  const overallPass = formattedResults.every(r => r.status === "pass");
+
+  return {
+    status:          overallPass ? "pass" : "fail",
+    executionId:     result.executionId,
+    results:         formattedResults,
+    total_scripts:   result.total_scripts,
+    passed_scripts:  result.passed,
+    failed_scripts:  result.failed,
+    total_duration:  formatDuration(result.duration_ms),
+  };
+}

package/src/utils/sseManager.ts

@@ -0,0 +1,127 @@
+import { Response } from "express";
+import { SSEEvent, SSEEventType } from "../types/types";
+import { Logger } from "./logger";
+
+const log = Logger.create("SSEManager");
+
+/**
+ * SSEManager — v2 with Event Replay Buffer
+ * =========================================
+ * ROOT CAUSE FIX:
+ * The dashboard opens AFTER POST /api/run-test returns. Since execution is
+ * now non-blocking, it often completes before the browser even renders the
+ * dashboard page and the SSE connection is established. This means the
+ * dashboard misses all events and shows "Waiting for execution to begin..."
+ * even though the run is already done.
+ *
+ * FIX: Store every emitted event in a per-execution replay buffer.
+ * When a new SSE client connects, immediately replay all past events.
+ * This way late-connecting dashboards see the full execution history.
+ */
+export class SSEManager {
+  private clients: Map<string, Set<Response>> = new Map();
+  // ✅ Replay buffer — stores all events per execution
+  private eventBuffer: Map<string, SSEEvent[]> = new Map();
+  // Max events to buffer per execution (prevents memory leak)
+  private readonly MAX_BUFFER  = 500;
+  // How long to keep buffer after execution completes (ms)
+  private readonly BUFFER_TTL  = 2 * 60 * 60 * 1000; // 2 hours
+
+  addClient(executionId: string, res: Response): void {
+    res.setHeader("Content-Type",      "text/event-stream");
+    res.setHeader("Cache-Control",     "no-cache");
+    res.setHeader("Connection",        "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.flushHeaders();
+
+    if (!this.clients.has(executionId)) this.clients.set(executionId, new Set());
+    this.clients.get(executionId)!.add(res);
+
+    log.info(`SSE client connected: ${executionId}`);
+
+    // ✅ REPLAY: Send all past events immediately to this late-joining client
+    const pastEvents = this.eventBuffer.get(executionId) ?? [];
+    if (pastEvents.length > 0) {
+      log.info(`Replaying ${pastEvents.length} past events to late client: ${executionId}`);
+      pastEvents.forEach((ev) => this.sendToOne(res, ev));
+    } else {
+      // Only send connect message if no replay (otherwise connect msg mid-replay is confusing)
+      this.sendToOne(res, {
+        type: "log", executionId,
+        timestamp: new Date().toISOString(),
+        data: { message: "Connected to execution stream" },
+      });
+    }
+
+    // Heartbeat
+    const hb = setInterval(() => {
+      if (!res.writableEnded) res.write(": heartbeat\n\n");
+      else clearInterval(hb);
+    }, 20000);
+
+    res.on("close", () => {
+      clearInterval(hb);
+      this.removeClient(executionId, res);
+    });
+  }
+
+  emit(executionId: string, type: SSEEventType, data: any): void {
+    const event: SSEEvent = {
+      type, executionId,
+      timestamp: new Date().toISOString(),
+      data,
+    };
+
+    // ✅ Buffer event for replay
+    if (!this.eventBuffer.has(executionId)) {
+      this.eventBuffer.set(executionId, []);
+    }
+    const buf = this.eventBuffer.get(executionId)!;
+    if (buf.length < this.MAX_BUFFER) buf.push(event);
+
+    // Broadcast to all currently connected clients
+    const clients = this.clients.get(executionId);
+    if (clients && clients.size > 0) {
+      clients.forEach((res) => this.sendToOne(res, event));
+    }
+
+    if (type === "execution_complete") {
+      // Clean up connections, keep buffer for replay
+      setTimeout(() => this.clients.delete(executionId), 5000);
+      // Clean up buffer after TTL
+      setTimeout(() => this.eventBuffer.delete(executionId), this.BUFFER_TTL);
+    }
+  }
+
+  /** Broadcast to ALL connections (e.g. queue updates, global health) */
+  broadcast(type: SSEEventType, data: any): void {
+    const event: SSEEvent = {
+      type, executionId: "global",
+      timestamp: new Date().toISOString(),
+      data,
+    };
+    this.clients.forEach((clients) => clients.forEach((res) => this.sendToOne(res, event)));
+  }
+
+  /** Replay buffer for a given executionId (used by status endpoint) */
+  getBuffer(executionId: string): SSEEvent[] {
+    return this.eventBuffer.get(executionId) ?? [];
+  }
+
+  hasClients(executionId: string): boolean {
+    return (this.clients.get(executionId)?.size ?? 0) > 0;
+  }
+
+  private sendToOne(res: Response, event: SSEEvent): void {
+    try {
+      if (!res.writableEnded) res.write(`data: ${JSON.stringify(event)}\n\n`);
+    } catch { /* client gone */ }
+  }
+
+  private removeClient(executionId: string, res: Response): void {
+    this.clients.get(executionId)?.delete(res);
+    if (this.clients.get(executionId)?.size === 0) this.clients.delete(executionId);
+  }
+}
+
+export const sseManager = new SSEManager();

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2021", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}