@vijaypjavvadi/bdd2pw 3.8.0 → 3.9.0

package/templates/heal.ts.tmpl

@@ -1,452 +1,452 @@
-/**
- * Self-healing locator helper — v1.2.1 scaffold (bdd2pw 2.2.1+).
- *
- * 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.
- *
- * v1.2 → v1.2.1: action-time healing is now applied via INSTANCE
- * MUTATION instead of a Proxy wrapper. v1.2's Proxy broke Playwright
- * `expect(loc).toBeVisible()` because the matcher does a private-field
- * probe (`#frame`) that doesn't survive a generic Proxy — every spec
- * that called expect() on a POM field died synchronously with
- * `Error: toBeVisible can be only used with Locator object`. v1.2.1
- * preserves Locator identity so expect() works normally while keeping
- * the action-time heal-and-retry behaviour intact.
- *
- * What this provides today (v1.2.1)
- * ----------------------------------
- *   - `healOrThrow(page, { preferred, context })` — registers the locator
- *     to `artefacts/heal-events.jsonl` AND mutates it in place so 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. Best-effort
- *     POST — failures are silently swallowed.
- *
- * 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.
- *   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 { test, type Locator, type Page } from "@playwright/test";
-
-export interface HealContext {
-  /** PascalCase Page Object class name, e.g. "LoginPage". */
-  page: string;
-  /** camelCase field name, e.g. "usernameInput". */
-  name: string;
-}
-
-export interface HealOrThrowOptions {
-  /** The locator the emitter chose for this field. */
-  preferred: Locator;
-  /** Static metadata that uniquely identifies this locator across runs. */
-  context: HealContext;
-}
-
-interface HealEvent {
-  ts: string;
-  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;
-}
-
-const DISABLED = process.env.HEAL_DISABLE === "1" || process.env.HEAL_DISABLE === "true";
-const SERVICE_URL = process.env.SELF_HEALING_URL ?? "";
-const EVENTS_PATH = process.env.HEAL_EVENTS_PATH ?? "artefacts/heal-events.jsonl";
-
-let writerInitialised = false;
-
-function ensureArtefactsDir(): string {
-  const fullPath = path.resolve(process.cwd(), EVENTS_PATH);
-  const dir = path.dirname(fullPath);
-  if (!writerInitialised) {
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-      writerInitialised = true;
-    } catch {
-      /* best-effort */
-    }
-  }
-  return fullPath;
-}
-
-function appendEvent(event: HealEvent | HealAttemptEvent): void {
-  if (DISABLED) return;
-  const fullPath = ensureArtefactsDir();
-  try {
-    fs.appendFileSync(fullPath, JSON.stringify(event) + "\n", "utf8");
-  } catch {
-    /* best-effort — never break tests for logging */
-  }
-}
-
-/**
- * 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;
-  try {
-    url = new URL("/api/v1/register", SERVICE_URL);
-  } catch {
-    return;
-  }
-  const payload = JSON.stringify({
-    page: context.page,
-    name: context.name,
-    pid: process.pid,
-    ts: new Date().toISOString(),
-  });
-  const client = url.protocol === "https:" ? https : http;
-  try {
-    const req = client.request(
-      url,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Content-Length": Buffer.byteLength(payload),
-        },
-        timeout: 1000,
-      },
-      (res) => res.resume(),
-    );
-    req.on("error", () => {});
-    req.on("timeout", () => req.destroy());
-    req.write(payload);
-    req.end();
-  } catch {
-    /* best-effort */
-  }
-}
-
-/**
- * Register a locator with the self-healing pipeline and mutate it in
- * place so action methods perform action-time healing on failure
- * (v1.2.1). Returns the SAME Locator instance — identity is preserved,
- * so `expect(returned).toBeVisible()` works normally.
- */
-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 wrapLocatorForHealing(page, opts.preferred, opts.context);
-}
-
-/* ─── v1.2.1 action-time healing (instance mutation, no Proxy) ────── */
-
-/** 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);
-    }
-  });
-}
-
-/**
- * Add action-time healing to a Locator by MUTATING IT IN PLACE.
- *
- * v1.2 used a `new Proxy(...)` wrapper here, which broke any spec that
- * called `await expect(loc).toBeVisible()` — Playwright's matchers do
- * a private-field probe (`#frame` and friends) that doesn't survive a
- * generic Proxy. Result: 100% test fail rate on any spec that asserts
- * against a POM field, with the unhelpful error
- *   `Error: toBeVisible can be only used with Locator object`.
- *
- * v1.2.1 replaces the Proxy with direct method override:
- *   - For every healable method (click, fill, …), capture the original
- *     bound function via closure BEFORE mutation.
- *   - Replace the property on the Locator INSTANCE with a wrapper that
- *     try/catches and heals on failure.
- *   - Return the original Locator unchanged in identity. `instanceof
- *     Locator` still holds; private-field probes still work; `expect()`
- *     accepts it normally; non-healable methods (.locator(), .first(),
- *     etc.) keep their prototype's implementation untouched.
- *
- * After a successful heal, `healedLocator` is set in the closure and
- * subsequent calls (on any healable method on this same instance) go
- * through it transparently. Cross-method healing of one cached
- * candidate, exactly as v1.2 promised — but without sacrificing
- * matcher compatibility.
- */
-function wrapLocatorForHealing(page: Page, original: Locator, context: HealContext): Locator {
-  let healedLocator: Locator | null = null;
-
-  for (const method of HEALABLE_METHODS) {
-    // Capture the original method BEFORE mutation — otherwise we'd
-    // recurse infinitely when our wrapper tries to call the "original".
-    const origFn = (original as unknown as Record<string, unknown>)[method];
-    if (typeof origFn !== "function") continue;
-
-    (original as unknown as Record<string, unknown>)[method] = async function (
-      ...args: unknown[]
-    ) {
-      // Once healed, route every healable call through the candidate.
-      if (healedLocator) {
-        const fn = (healedLocator as unknown as Record<string, Function>)[method];
-        return await fn.apply(healedLocator, args);
-      }
-
-      try {
-        return await (origFn as (...a: unknown[]) => Promise<unknown>).apply(
-          original,
-          args,
-        );
-      } catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        const original_selector = locatorSelector(original);
-        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 original;
-}
+/**
+ * Self-healing locator helper — v1.2.1 scaffold (bdd2pw 2.2.1+).
+ *
+ * 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.
+ *
+ * v1.2 → v1.2.1: action-time healing is now applied via INSTANCE
+ * MUTATION instead of a Proxy wrapper. v1.2's Proxy broke Playwright
+ * `expect(loc).toBeVisible()` because the matcher does a private-field
+ * probe (`#frame`) that doesn't survive a generic Proxy — every spec
+ * that called expect() on a POM field died synchronously with
+ * `Error: toBeVisible can be only used with Locator object`. v1.2.1
+ * preserves Locator identity so expect() works normally while keeping
+ * the action-time heal-and-retry behaviour intact.
+ *
+ * What this provides today (v1.2.1)
+ * ----------------------------------
+ *   - `healOrThrow(page, { preferred, context })` — registers the locator
+ *     to `artefacts/heal-events.jsonl` AND mutates it in place so 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. Best-effort
+ *     POST — failures are silently swallowed.
+ *
+ * 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.
+ *   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 { test, type Locator, type Page } from "@playwright/test";
+
+export interface HealContext {
+  /** PascalCase Page Object class name, e.g. "LoginPage". */
+  page: string;
+  /** camelCase field name, e.g. "usernameInput". */
+  name: string;
+}
+
+export interface HealOrThrowOptions {
+  /** The locator the emitter chose for this field. */
+  preferred: Locator;
+  /** Static metadata that uniquely identifies this locator across runs. */
+  context: HealContext;
+}
+
+interface HealEvent {
+  ts: string;
+  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;
+}
+
+const DISABLED = process.env.HEAL_DISABLE === "1" || process.env.HEAL_DISABLE === "true";
+const SERVICE_URL = process.env.SELF_HEALING_URL ?? "";
+const EVENTS_PATH = process.env.HEAL_EVENTS_PATH ?? "artefacts/heal-events.jsonl";
+
+let writerInitialised = false;
+
+function ensureArtefactsDir(): string {
+  const fullPath = path.resolve(process.cwd(), EVENTS_PATH);
+  const dir = path.dirname(fullPath);
+  if (!writerInitialised) {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      writerInitialised = true;
+    } catch {
+      /* best-effort */
+    }
+  }
+  return fullPath;
+}
+
+function appendEvent(event: HealEvent | HealAttemptEvent): void {
+  if (DISABLED) return;
+  const fullPath = ensureArtefactsDir();
+  try {
+    fs.appendFileSync(fullPath, JSON.stringify(event) + "\n", "utf8");
+  } catch {
+    /* best-effort — never break tests for logging */
+  }
+}
+
+/**
+ * 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;
+  try {
+    url = new URL("/api/v1/register", SERVICE_URL);
+  } catch {
+    return;
+  }
+  const payload = JSON.stringify({
+    page: context.page,
+    name: context.name,
+    pid: process.pid,
+    ts: new Date().toISOString(),
+  });
+  const client = url.protocol === "https:" ? https : http;
+  try {
+    const req = client.request(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+        },
+        timeout: 1000,
+      },
+      (res) => res.resume(),
+    );
+    req.on("error", () => {});
+    req.on("timeout", () => req.destroy());
+    req.write(payload);
+    req.end();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Register a locator with the self-healing pipeline and mutate it in
+ * place so action methods perform action-time healing on failure
+ * (v1.2.1). Returns the SAME Locator instance — identity is preserved,
+ * so `expect(returned).toBeVisible()` works normally.
+ */
+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 wrapLocatorForHealing(page, opts.preferred, opts.context);
+}
+
+/* ─── v1.2.1 action-time healing (instance mutation, no Proxy) ────── */
+
+/** 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);
+    }
+  });
+}
+
+/**
+ * Add action-time healing to a Locator by MUTATING IT IN PLACE.
+ *
+ * v1.2 used a `new Proxy(...)` wrapper here, which broke any spec that
+ * called `await expect(loc).toBeVisible()` — Playwright's matchers do
+ * a private-field probe (`#frame` and friends) that doesn't survive a
+ * generic Proxy. Result: 100% test fail rate on any spec that asserts
+ * against a POM field, with the unhelpful error
+ *   `Error: toBeVisible can be only used with Locator object`.
+ *
+ * v1.2.1 replaces the Proxy with direct method override:
+ *   - For every healable method (click, fill, …), capture the original
+ *     bound function via closure BEFORE mutation.
+ *   - Replace the property on the Locator INSTANCE with a wrapper that
+ *     try/catches and heals on failure.
+ *   - Return the original Locator unchanged in identity. `instanceof
+ *     Locator` still holds; private-field probes still work; `expect()`
+ *     accepts it normally; non-healable methods (.locator(), .first(),
+ *     etc.) keep their prototype's implementation untouched.
+ *
+ * After a successful heal, `healedLocator` is set in the closure and
+ * subsequent calls (on any healable method on this same instance) go
+ * through it transparently. Cross-method healing of one cached
+ * candidate, exactly as v1.2 promised — but without sacrificing
+ * matcher compatibility.
+ */
+function wrapLocatorForHealing(page: Page, original: Locator, context: HealContext): Locator {
+  let healedLocator: Locator | null = null;
+
+  for (const method of HEALABLE_METHODS) {
+    // Capture the original method BEFORE mutation — otherwise we'd
+    // recurse infinitely when our wrapper tries to call the "original".
+    const origFn = (original as unknown as Record<string, unknown>)[method];
+    if (typeof origFn !== "function") continue;
+
+    (original as unknown as Record<string, unknown>)[method] = async function (
+      ...args: unknown[]
+    ) {
+      // Once healed, route every healable call through the candidate.
+      if (healedLocator) {
+        const fn = (healedLocator as unknown as Record<string, Function>)[method];
+        return await fn.apply(healedLocator, args);
+      }
+
+      try {
+        return await (origFn as (...a: unknown[]) => Promise<unknown>).apply(
+          original,
+          args,
+        );
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const original_selector = locatorSelector(original);
+        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 original;
+}