@vijaypjavvadi/bdd2pw 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -9,6 +9,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _Nothing yet._
 
+## [2.2.1] — 2026-05-09
+
+### Fixed — heal Proxy broke `expect(locator).toMatcher(...)` (HIGH, launch-blocker)
+
+bdd2pw 2.2.0's action-time healing wrapped every POM-field Locator in a
+`new Proxy(...)` for healable-method interception. Playwright's
+`expect(loc).toBeVisible()` (and every other `LocatorMatchers`) does a
+private-field probe (`#frame`, `Symbol.toStringTag`, etc.) that doesn't
+survive a generic Proxy — so every spec that asserted against a POM
+field died synchronously with:
+
+```
+Error: toBeVisible can be only used with Locator object
+```
+
+100 % test fail rate on any spec calling `expect()` on a POM field.
+
+**Fix:** replaced the Proxy with **direct instance mutation** in
+`templates/heal.ts.tmpl` (heal helper bumped to v1.2.1):
+
+```ts
+// Before (v1.2): wrap in Proxy → identity check fails
+const proxy = new Proxy(original, { get(target, prop) {...} });
+return proxy;
+
+// After (v1.2.1): mutate own properties → identity preserved
+for (const method of HEALABLE_METHODS) {
+  const origFn = (original as any)[method];
+  if (typeof origFn !== "function") continue;
+  (original as any)[method] = async function (...args) {
+    if (healedLocator) {
+      return await (healedLocator as any)[method].apply(healedLocator, args);
+    }
+    try { return await origFn.apply(original, args); }
+    catch (err) { /* heal-and-retry, identical to v1.2 */ }
+  };
+}
+return original;
+```
+
+The healing logic (POST `/api/v1/heal`, retry with candidate, log
+`heal_attempt` / `healed` / `heal_unavailable`) is byte-identical. Only
+the wrapping mechanism changed.
+
+#### What this preserves vs v1.2
+
+| Property | v1.2 (Proxy) | v1.2.1 (mutation) |
+|---|---|---|
+| Action-time healing on `.click`/`.fill`/etc. | ✓ | ✓ |
+| Once-cached candidate reused on subsequent calls | ✓ | ✓ |
+| `await loc.click()` works | ✓ | ✓ |
+| `await expect(loc).toBeVisible()` works | ❌ | ✓ |
+| `loc instanceof Locator` | partially | ✓ |
+| Private-field probes (`#frame`) | ❌ | ✓ |
+| Non-healable methods (`.locator()`, `.first()`) untouched | ✓ | ✓ (prototype delegation) |
+
+#### Files
+
+- Modified: `templates/heal.ts.tmpl` (the `wrapLocatorForHealing`
+  function + doc comments at top + version bump v1.2 → v1.2.1).
+
+#### Migration from 2.2.0
+
+Pure bug fix — no API change. Just bump the dep pin to `^2.2.1`.
+
+Cloud-jobs-template runs that were failing 100% on
+`expect.toBeVisible can be only used with Locator object` will now go
+green (or fail honestly on real test logic). Action-time healing
+continues to work the same way for failed `.click()` / `.fill()` /
+etc.
+
 ## [2.2.0] — 2026-05-08
 
 ### Fixed — LLM fallback hung 8+ minutes in cloud-job containers (HIGH, launch-blocker)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vijaypjavvadi/bdd2pw",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Scaffold runnable Playwright TypeScript tests from Gherkin .feature files. Detects existing Page Objects, scans live pages via Microsoft Playwright MCP, emits POMs + specs, ready for execution. CLI + HTTP service. Optional governed LLM fallback (Anthropic / OpenAI / Gemini).",
   "bin": {
     "bdd2pw": "dist/cli.js"

package/templates/heal.ts.tmpl

@@ -1,15 +1,24 @@
 /**
- * Self-healing locator helper — v1.2 scaffold.
+ * 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.
  *
- * What this provides today (v1.2)
- * --------------------------------
+ * 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 wraps it in a `Proxy` that
- *     intercepts every healable action method (.click, .fill, .check,
+ *     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
@@ -174,8 +183,10 @@ function heartbeat(context: HealContext): void {
 }
 
 /**
- * Register a locator with the self-healing pipeline and return a Proxy
- * that performs action-time healing on failure (v1.2).
+ * 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({
@@ -191,7 +202,7 @@ export function healOrThrow(page: Page, opts: HealOrThrowOptions): Locator {
   return wrapLocatorForHealing(page, opts.preferred, opts.context);
 }
 
-/* ─── v1.2 action-time healing ────────────────────────────────────── */
+/* ─── 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
@@ -291,40 +302,77 @@ async function fetchHealCandidate(
 }
 
 /**
- * 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.
+ * 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;
 
-  const proxy = new Proxy(original, {
-    get(target, prop, _receiver) {
-      const live: Locator = healedLocator ?? target;
+  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;
 
-      if (typeof prop !== "string") {
-        const v = Reflect.get(live, prop, live);
-        return typeof v === "function" ? (v as Function).bind(live) : v;
+    (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);
       }
 
-      const value = Reflect.get(live, prop, live);
-      if (typeof value !== "function") return value;
-      if (!HEALABLE_METHODS.has(prop)) return (value as Function).bind(live);
+      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(),
+        });
 
-      // 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);
+        const candidate = await fetchHealCandidate(context, original_selector, errMsg);
+        if (!candidate) {
           appendEvent({
             ts: new Date().toISOString(),
-            event: "heal_attempt",
+            event: "heal_unavailable",
             page: context.page,
             name: context.name,
             scenario_name: currentScenarioName(),
@@ -336,87 +384,69 @@ function wrapLocatorForHealing(page: Page, original: Locator, context: HealConte
             pid: process.pid,
             cwd: process.cwd(),
           });
+          throw err;
+        }
 
-          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;
-          }
+        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;
-          }
+        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;
+  return original;
 }