@vijaypjavvadi/bdd2pw 2.0.2 → 2.2.0

package/templates/heal.ts.tmpl

@@ -1,64 +1,52 @@
 /**
- * Self-healing locator helper — v1.1 scaffold.
+ * Self-healing locator helper — v1.2 scaffold.
  *
  * GENERATED FILE. Do not edit directly; this file is rewritten on every
  * `bdd2pw scaffold --self-healing` invocation. To customise, fork it under
  * a different filename and update the `tsconfig.json` `paths` mapping.
  *
- * What this provides today (v1.1)
+ * What this provides today (v1.2)
  * --------------------------------
- *   - `healOrThrow(page, { preferred, context })` — a passthrough that
- *     returns the `preferred` Playwright Locator unchanged, AND records
- *     the locator-creation event to `artefacts/heal-events.jsonl` for the
- *     offline self-heal pipeline to consume.
+ *   - `healOrThrow(page, { preferred, context })` — registers the locator
+ *     to `artefacts/heal-events.jsonl` AND wraps it in a `Proxy` that
+ *     intercepts every healable action method (.click, .fill, .check,
+ *     .selectOption, .hover, .focus, .textContent, .innerText,
+ *     .getAttribute, .isVisible, .waitFor, .press, .type, .setChecked,
+ *     .uncheck, .clear, .scrollIntoViewIfNeeded). On the FIRST action
+ *     failure for a given locator, the proxy:
+ *       1. Logs a `heal_attempt` event with the original error.
+ *       2. Asks the self-healing service (when SELF_HEALING_URL is set)
+ *          for a candidate replacement selector via POST /api/v1/heal.
+ *       3. Re-runs the original action against `page.locator(<candidate>)`.
+ *       4. On success, logs a `healed` event; subsequent actions on the
+ *          SAME locator instance use the candidate transparently.
+ *       5. On failure (no service, no candidate, or candidate also fails),
+ *          logs `heal_unavailable` and re-throws the original error so
+ *          the test still fails honestly.
  *   - Optional fire-and-forget heartbeat to `${SELF_HEALING_URL}/api/v1/register`
- *     so the service knows which locators a test references. The heartbeat is
- *     a best-effort POST — failures are silently swallowed so a missing
- *     service doesn't break tests.
+ *     so the service knows which locators a test references. Best-effort
+ *     POST — failures are silently swallowed.
  *
- * What this does NOT do yet (deferred to v1.2)
- * --------------------------------------------
- *   - **Action-time healing.** When `await locator.click()` fails because
- *     the locator changed, this helper will not catch the failure, call
- *     `/api/v1/heal`, and retry with a suggested locator. That requires a
- *     Locator-wrapping proxy that intercepts every action method (.click,
- *     .fill, .check, .selectOption, .hover, .focus, .textContent,
- *     .innerText, .getAttribute, .isVisible, .waitForSelector, ...). The
- *     existing self-healing SDK does this for *string-selector*-based test
- *     code (`page.fill('#username', ...)`); pw-emit's POMs use Locator
- *     objects (`this.usernameInput.fill(...)`), so the v1.2 wrapper has a
- *     different shape.
- *
- *   Until v1.2 ships, this file is a registration scaffold: the offline
- *   self-heal pipeline (`E:\EB1A_Research\self_healing_stage_services`)
- *   sees what locators each test references via the JSONL feed, but
- *   recovery still has to happen through that pipeline's batch processing
- *   rather than at action time.
+ * Action-time healing intentionally fires only on ACTION failures (click,
+ * fill, etc.), not on locator construction — `page.getByLabel("Username")`
+ * is just an object factory and never throws. The proxy adds zero overhead
+ * on the happy path: every method call passes through unmodified, the
+ * try/catch only kicks in when the underlying Playwright call rejects.
  *
  * Environment variables
  * ---------------------
- *   SELF_HEALING_URL    Base URL of the self-healing service (e.g.
- *                       http://localhost:8003). When set, every locator
- *                       creation triggers a fire-and-forget POST to
- *                       `${SELF_HEALING_URL}/api/v1/register`. When unset,
- *                       no network calls are made; events still land in
- *                       JSONL.
- *
- *   HEAL_EVENTS_PATH    Override the JSONL output path. Defaults to
- *                       `artefacts/heal-events.jsonl` relative to the
- *                       process cwd (typically the repo root when running
- *                       `npx playwright test`).
- *
- *   HEAL_DISABLE        Set to "1" or "true" to disable both JSONL writes
- *                       and heartbeats. Useful in CI when you don't want
- *                       the artefact noise.
+ *   SELF_HEALING_URL    Base URL of the self-healing service.
+ *   HEAL_EVENTS_PATH    Override the JSONL output path (default
+ *                       `artefacts/heal-events.jsonl`).
+ *   HEAL_DISABLE        "1"/"true" disables JSONL writes + heartbeats +
+ *                       heal-service calls. Useful in CI.
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import * as http from "http";
 import * as https from "https";
-import type { Locator, Page } from "@playwright/test";
+import { test, type Locator, type Page } from "@playwright/test";
 
 export interface HealContext {
   /** PascalCase Page Object class name, e.g. "LoginPage". */
@@ -79,6 +67,27 @@ interface HealEvent {
   event: "register";
   page: string;
   name: string;
+  /** Scenario / test title at the time the locator was registered. */
+  scenario_name: string | null;
+  pid: number;
+  cwd: string;
+}
+
+interface HealAttemptEvent {
+  ts: string;
+  event: "heal_attempt" | "healed" | "heal_unavailable";
+  page: string;
+  name: string;
+  scenario_name: string | null;
+  method: string;
+  /** Original locator selector (best-effort serialisation). */
+  original: string | null;
+  /** Replacement selector when known. */
+  healed: string | null;
+  /** Confidence in the replacement, 0–1, when the service provided one. */
+  confidence: number | null;
+  /** Truncated error message that triggered the heal attempt. */
+  error: string | null;
   pid: number;
   cwd: string;
 }
@@ -103,7 +112,7 @@ function ensureArtefactsDir(): string {
   return fullPath;
 }
 
-function appendEvent(event: HealEvent): void {
+function appendEvent(event: HealEvent | HealAttemptEvent): void {
   if (DISABLED) return;
   const fullPath = ensureArtefactsDir();
   try {
@@ -113,6 +122,20 @@ function appendEvent(event: HealEvent): void {
   }
 }
 
+/**
+ * Best-effort scenario-name capture. test.info() throws when called
+ * outside a running test (`Test info is not available outside the test
+ * lifecycle`), so we swallow and return null.
+ */
+function currentScenarioName(): string | null {
+  try {
+    const info = test.info();
+    return info?.title ?? null;
+  } catch {
+    return null;
+  }
+}
+
 function heartbeat(context: HealContext): void {
   if (DISABLED || !SERVICE_URL) return;
   let url: URL;
@@ -151,28 +174,249 @@ function heartbeat(context: HealContext): void {
 }
 
 /**
- * Register a locator with the self-healing pipeline and return it unchanged.
- *
- * The emitted POM constructor calls this for every field:
- *
- *   this.usernameInput = healOrThrow(page, {
- *     preferred: page.getByLabel("Username"),
- *     context: { page: "LoginPage", name: "usernameInput" },
- *   });
- *
- * v1.1 returns `preferred` as-is — no wrapping, no proxy, no action-time
- * healing. The locator is registered to JSONL + heartbeat so the offline
- * self-heal pipeline sees it. v1.2 will wrap action methods.
+ * Register a locator with the self-healing pipeline and return a Proxy
+ * that performs action-time healing on failure (v1.2).
  */
-export function healOrThrow(_page: Page, opts: HealOrThrowOptions): Locator {
+export function healOrThrow(page: Page, opts: HealOrThrowOptions): Locator {
   appendEvent({
     ts: new Date().toISOString(),
     event: "register",
     page: opts.context.page,
     name: opts.context.name,
+    scenario_name: currentScenarioName(),
     pid: process.pid,
     cwd: process.cwd(),
   });
   heartbeat(opts.context);
-  return opts.preferred;
+  return wrapLocatorForHealing(page, opts.preferred, opts.context);
+}
+
+/* ─── v1.2 action-time healing ────────────────────────────────────── */
+
+/** Healable Locator action methods — i.e. ones that throw on element-not-
+ *  found / timeout. Read methods like .count() / .all() return 0 / [] and
+ *  don't need wrapping. */
+const HEALABLE_METHODS = new Set<string>([
+  "click", "dblclick", "fill", "type", "press", "check", "uncheck",
+  "setChecked", "selectOption", "hover", "focus", "blur", "tap",
+  "clear", "scrollIntoViewIfNeeded", "waitFor",
+  "textContent", "innerText", "innerHTML", "getAttribute", "inputValue",
+  "isVisible", "isHidden", "isEnabled", "isDisabled", "isChecked",
+  "isEditable",
+]);
+
+/** Pull a human-readable selector string out of a Locator. Playwright
+ *  doesn't expose this officially; read its private `_selector` field
+ *  when present and fall back to `String(locator)`. */
+function locatorSelector(loc: Locator): string | null {
+  try {
+    const internal = (loc as unknown as { _selector?: string })._selector;
+    if (typeof internal === "string" && internal.length > 0) return internal;
+    const str = String(loc);
+    return str === "[object Object]" ? null : str;
+  } catch {
+    return null;
+  }
+}
+
+interface HealCandidate {
+  selector: string;
+  confidence: number | null;
+}
+
+/** POST /api/v1/heal — returns a candidate replacement selector or null. */
+async function fetchHealCandidate(
+  context: HealContext,
+  originalSelector: string | null,
+  errorMessage: string,
+): Promise<HealCandidate | null> {
+  if (DISABLED || !SERVICE_URL) return null;
+  let url: URL;
+  try {
+    url = new URL("/api/v1/heal", SERVICE_URL);
+  } catch {
+    return null;
+  }
+  const payload = JSON.stringify({
+    page: context.page,
+    name: context.name,
+    original: originalSelector,
+    error: errorMessage.slice(0, 500),
+    scenario_name: currentScenarioName(),
+  });
+  const client = url.protocol === "https:" ? https : http;
+  return new Promise<HealCandidate | null>((resolve) => {
+    let resolved = false;
+    const settle = (v: HealCandidate | null) => {
+      if (!resolved) { resolved = true; resolve(v); }
+    };
+    try {
+      const req = client.request(
+        url,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Content-Length": Buffer.byteLength(payload),
+          },
+          timeout: 5000,
+        },
+        (res) => {
+          const chunks: Buffer[] = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on("end", () => {
+            try {
+              const body = Buffer.concat(chunks).toString("utf8");
+              const parsed = JSON.parse(body) as { selector?: string; confidence?: number };
+              if (parsed && typeof parsed.selector === "string") {
+                settle({ selector: parsed.selector, confidence: typeof parsed.confidence === "number" ? parsed.confidence : null });
+              } else {
+                settle(null);
+              }
+            } catch {
+              settle(null);
+            }
+          });
+          res.on("error", () => settle(null));
+        },
+      );
+      req.on("error", () => settle(null));
+      req.on("timeout", () => { req.destroy(); settle(null); });
+      req.write(payload);
+      req.end();
+    } catch {
+      settle(null);
+    }
+  });
+}
+
+/**
+ * Wrap a Locator in a Proxy that retries failed actions against a
+ * service-suggested candidate selector. Once a candidate is verified to
+ * work for any method on this Locator, subsequent calls use the
+ * candidate transparently.
+ */
+function wrapLocatorForHealing(page: Page, original: Locator, context: HealContext): Locator {
+  let healedLocator: Locator | null = null;
+
+  const proxy = new Proxy(original, {
+    get(target, prop, _receiver) {
+      const live: Locator = healedLocator ?? target;
+
+      if (typeof prop !== "string") {
+        const v = Reflect.get(live, prop, live);
+        return typeof v === "function" ? (v as Function).bind(live) : v;
+      }
+
+      const value = Reflect.get(live, prop, live);
+      if (typeof value !== "function") return value;
+      if (!HEALABLE_METHODS.has(prop)) return (value as Function).bind(live);
+
+      // Healable action: wrap so we can intercept rejections.
+      const method = prop;
+      return async (...args: unknown[]) => {
+        try {
+          return await (value as (...a: unknown[]) => Promise<unknown>).apply(live, args);
+        } catch (err) {
+          // Already healed once and STILL failing → real defect; rethrow.
+          if (healedLocator) throw err;
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const original_selector = locatorSelector(target);
+          appendEvent({
+            ts: new Date().toISOString(),
+            event: "heal_attempt",
+            page: context.page,
+            name: context.name,
+            scenario_name: currentScenarioName(),
+            method,
+            original: original_selector,
+            healed: null,
+            confidence: null,
+            error: errMsg.slice(0, 500),
+            pid: process.pid,
+            cwd: process.cwd(),
+          });
+
+          const candidate = await fetchHealCandidate(context, original_selector, errMsg);
+          if (!candidate) {
+            appendEvent({
+              ts: new Date().toISOString(),
+              event: "heal_unavailable",
+              page: context.page,
+              name: context.name,
+              scenario_name: currentScenarioName(),
+              method,
+              original: original_selector,
+              healed: null,
+              confidence: null,
+              error: errMsg.slice(0, 500),
+              pid: process.pid,
+              cwd: process.cwd(),
+            });
+            throw err;
+          }
+
+          let candidateLocator: Locator;
+          try {
+            candidateLocator = page.locator(candidate.selector);
+          } catch {
+            appendEvent({
+              ts: new Date().toISOString(),
+              event: "heal_unavailable",
+              page: context.page,
+              name: context.name,
+              scenario_name: currentScenarioName(),
+              method,
+              original: original_selector,
+              healed: candidate.selector,
+              confidence: candidate.confidence,
+              error: "candidate selector failed to construct",
+              pid: process.pid,
+              cwd: process.cwd(),
+            });
+            throw err;
+          }
+
+          try {
+            const retryFn = (candidateLocator as unknown as Record<string, Function>)[method];
+            const retryResult = await retryFn.apply(candidateLocator, args);
+            healedLocator = candidateLocator;
+            appendEvent({
+              ts: new Date().toISOString(),
+              event: "healed",
+              page: context.page,
+              name: context.name,
+              scenario_name: currentScenarioName(),
+              method,
+              original: original_selector,
+              healed: candidate.selector,
+              confidence: candidate.confidence,
+              error: errMsg.slice(0, 500),
+              pid: process.pid,
+              cwd: process.cwd(),
+            });
+            return retryResult;
+          } catch (retryErr) {
+            appendEvent({
+              ts: new Date().toISOString(),
+              event: "heal_unavailable",
+              page: context.page,
+              name: context.name,
+              scenario_name: currentScenarioName(),
+              method,
+              original: original_selector,
+              healed: candidate.selector,
+              confidence: candidate.confidence,
+              error: retryErr instanceof Error ? retryErr.message.slice(0, 500) : String(retryErr).slice(0, 500),
+              pid: process.pid,
+              cwd: process.cwd(),
+            });
+            throw err;
+          }
+        }
+      };
+    },
+  });
+
+  return proxy;
 }