@qa-gentic/stlc-agents 1.0.25 → 1.0.27

package/src/stlc_agents/agent_playwright_generator/server.py

@@ -24,7 +24,7 @@ CI/CD Telemetry:
   before they are permanently committed to the repository.
 """
 from __future__ import annotations
-import asyncio, json, re, sys, os, uuid, socket, subprocess, time, threading, queue
+import asyncio, json, logging, re, sys, os, uuid, socket, subprocess, time, threading, queue
 from pathlib import Path
 from dotenv import load_dotenv
 from mcp.server import Server
@@ -1081,7 +1081,9 @@ def _merge_locators_ts(new_locators_section: str, existing_content: str, page_cl
     
     for match in re.finditer(new_pattern, new_locators_section):
         key_name, selector, intent = match.groups()
-        new_locators_dict[key_name] = {"selector": selector, "intent": intent}
+        stab_m = re.search(r'stability:\s*(\d+)', match.group(0))
+        stability = int(stab_m.group(1)) if stab_m else 0
+        new_locators_dict[key_name] = {"selector": selector, "intent": intent, "stability": stability}
     
     # Filter out existing keys
     unique_locators = {}
@@ -1113,7 +1115,8 @@ def _merge_locators_ts(new_locators_section: str, existing_content: str, page_cl
     for key_name, entry in {**unique_locators, **locator_conflicts}.items():
         selector = entry["selector"]
         intent = entry["intent"]
-        new_entries.append(f'  {key_name}: {{ selector: "{selector}", intent: \'{intent}\', stability: 0 }},')
+        stability = entry.get("stability", 0)
+        new_entries.append(f'  {key_name}: {{ selector: "{selector}", intent: \'{intent}\', stability: {stability} }},')
     
     if new_entries:
         merged = (
@@ -1326,8 +1329,12 @@ class _PlaywrightMcp:
         self._init_session()
 
     def call(self, tool: str, arguments: dict) -> dict:
+        _log = logging.getLogger("stlc.playwright_mcp")
         msg = self._build_rpc("tools/call", {"name": tool, "arguments": arguments})
         resp = self._post(msg)
+        if "error" in resp:
+            _log.error("Playwright MCP tool '%s' error: %s", tool, resp["error"])
+            raise RuntimeError(f"Playwright MCP tool '{tool}' error: {resp['error']}")
         content = resp.get("result", {}).get("content", [])
         if not content:
             return {}
@@ -1503,6 +1510,11 @@ def _find_ref(snapshot: dict, *, role: str | None = None, name_patterns: list[st
     return None
 
 
+def _find_refs_by_role(snapshot: dict, role: str) -> list[str]:
+    """Return all refs with the given role, in document order."""
+    return [el["ref"] for el in _parse_ax_elements(snapshot) if el.get("role") == role and el.get("ref")]
+
+
 def _to_camel(s: str) -> str:
     words = re.split(r"[\s\-_]+", s.strip())
     if not words:
@@ -1640,77 +1652,181 @@ def _needs_login(app_url: str, username: str, password: str) -> bool:
 
 def _do_login(pmcp: _PlaywrightMcp, app_url: str, username: str, password: str) -> dict:
     """Navigate to app_url, fill login form, click submit, return post-login snapshot."""
+    _log = logging.getLogger("stlc.playwright_mcp")
     pmcp.call("browser_navigate", {"url": app_url.rstrip("/")})
+
+    # Snapshot AFTER navigate to get fresh refs — Playwright MCP requires ref= to target
+    # a specific element; the element= field is only a human-readable permission label.
     login_snap = pmcp.call("browser_snapshot", {})
+    _log.info("Pre-login snapshot (first 600):\n%s", _snapshot_to_text(login_snap)[:600])
 
-    user_ref = _find_ref(login_snap, role="textbox", name_patterns=[r"user(?:name)?|email|login"])
+    user_ref = _find_ref(login_snap, role="textbox", name_patterns=[r"user(?:name)?"])
     pass_ref = _find_ref(login_snap, role="textbox", name_patterns=[r"pass(?:word)?"])
+    btn_ref  = _find_ref(login_snap, role="button",  name_patterns=[r"login|sign.?in|submit"])
+    _log.info("Login refs: user=%s pass=%s btn=%s", user_ref, pass_ref, btn_ref)
 
     if not user_ref or not pass_ref:
-        # no login form detected — return the snapshot as-is
-        return login_snap
+        raise RuntimeError(
+            f"Login form not found on page (user_ref={user_ref!r}, pass_ref={pass_ref!r}). "
+            "Check APP_BASE_URL and that Playwright MCP can reach the app."
+        )
 
-    # Try role=button first, then role=input (e.g. SauceDemo uses input[type=submit])
-    btn_ref = (
-        _find_ref(login_snap, role="button", name_patterns=[r"log.?in|sign.?in|submit"])
-        or _find_ref(login_snap, role="input",  name_patterns=[r"log.?in|sign.?in|submit"])
-    )
+    pmcp.call("browser_fill_form", {"fields": [
+        {"name": "Username", "type": "textbox", "ref": user_ref, "value": username},
+        {"name": "Password", "type": "textbox", "ref": pass_ref, "value": password},
+    ]})
 
-    pmcp.call("browser_fill", {"ref": user_ref, "value": username})
-    pmcp.call("browser_fill", {"ref": pass_ref, "value": password})
     if btn_ref:
-        pmcp.call("browser_click", {"ref": btn_ref})
+        pmcp.call("browser_click", {"element": "Login button", "ref": btn_ref})
     else:
-        # Last resort: submit via Enter key on the password field
-        pmcp.call("browser_press", {"ref": pass_ref, "key": "Enter"})
+        pmcp.call("browser_click", {"element": "Login button"})
 
-    return pmcp.call("browser_snapshot", {})
+    post_snap = pmcp.call("browser_snapshot", {})
+    _log.info("Post-login snapshot (first 400):\n%s", _snapshot_to_text(post_snap)[:400])
+
+    # Login failed if the username input is still present on the page
+    if _find_ref(post_snap, role="textbox", name_patterns=[r"user(?:name)?|email"]):
+        raise RuntimeError(
+            "Login failed — still on login page after submit. "
+            "Check APP_USERNAME, APP_PASSWORD, and that Playwright MCP can reach the app."
+        )
+    return post_snap
 
 
-# ── Multi-step flows driven by gherkin hints ──────────────────────────────────
+# ── Gherkin-driven multi-step capture ────────────────────────────────────────
 
-def _capture_checkout_flow(pmcp: _PlaywrightMcp, app_url: str, username: str, password: str) -> dict:
+# Interaction verbs we look for in When/And Gherkin steps
+_INTERACTION_VERBS = re.compile(
+    r"^(?:click|tap|press|open|select|expand|toggle|choose|navigate\s+to|go\s+to)\b",
+    re.IGNORECASE,
+)
+
+# Strip leading "I " or keyword prefix before matching verb
+_STEP_PREFIX = re.compile(
+    r"^(?:Given|When|Then|And|But)\s+(?:I\s+)?",
+    re.IGNORECASE,
+)
+
+# Trailing noise words that follow the real target name
+_TRAILING_NOISE = re.compile(
+    r"\s+(?:button|link|tab|icon|item|option|element|toggle|"
+    r"in\s+the\s+.+|from\s+the\s+.+|on\s+the\s+.+)\s*$",
+    re.IGNORECASE,
+)
+
+# Filler words between the verb and the target
+_VERB_FILLER = re.compile(
+    r"^(?:click|tap|press|open|select|expand|toggle|choose|navigate\s+to|go\s+to)\s+"
+    r"(?:on\s+)?(?:the\s+|a\s+|an\s+)?",
+    re.IGNORECASE,
+)
+
+
+def _extract_interaction_target(step_body: str) -> str | None:
+    """
+    Return the interaction target from a Gherkin step body, or None if the step
+    does not describe an interaction.
+
+    Examples:
+      "click the hamburger menu"          → "hamburger menu"
+      "open the About link in the sidebar"→ "About"
+      "tap the Submit button"             → "Submit"
+      "I am logged in as a user"          → None  (no interaction verb)
+    """
+    body = _STEP_PREFIX.sub("", step_body).strip()
+    if not _INTERACTION_VERBS.match(body):
+        return None
+    target = _VERB_FILLER.sub("", body).strip()
+    target = _TRAILING_NOISE.sub("", target).strip().strip("\"'")
+    return target if len(target) >= 2 else None
+
+
+def _find_element_ref(snapshot: dict, target: str) -> str | None:
     """
-    Checkout-specific multi-step capture:
-    login → add item to cart → open cart → proceed to checkout → snapshot checkout form.
-    Cart navigation uses the cart icon (browser_click) rather than a direct URL
-    to keep browser session state intact.
+    Find a clickable element ref whose accessible name fuzzy-matches target.
+
+    Strategy: build a regex from the meaningful words in target and search
+    through interactive roles in priority order, falling back to any role.
     """
-    base = app_url.rstrip("/")
+    words = [w for w in re.split(r"\s+", target.lower()) if len(w) >= 3]
+    if not words:
+        return None
+    pattern = "|".join(re.escape(w) for w in words)
+    for role in ("button", "link", "menuitem", "tab", "option", None):
+        ref = _find_ref(snapshot, role=role, name_patterns=[pattern])
+        if ref:
+            return ref
+    return None
 
-    post_login = _do_login(pmcp, base, username, password) if _needs_login(base, username, password) else pmcp.call("browser_snapshot", {})
 
-    inventory_snap = pmcp.call("browser_snapshot", {})
-    add_ref = _find_ref(inventory_snap, role="button", name_patterns=[r"add to cart"])
-    if add_ref:
-        pmcp.call("browser_click", {"ref": add_ref})
+def _capture_gherkin_driven(
+    pmcp: _PlaywrightMcp,
+    app_url: str,
+    username: str,
+    password: str,
+    gherkin: str,
+) -> dict:
+    """
+    Gherkin-driven capture that works for any application.
+
+    Algorithm:
+      1. Login (if credentials) or navigate to app_url → snapshot landing page.
+      2. Parse each When/And/Given/Then step for interaction verbs (click, open,
+         select, expand, toggle, …).
+      3. For each interaction: find the target element in the current snapshot,
+         click it, wait for the DOM to settle, snapshot the new page state.
+      4. Return the merged context_map from all captured states.
+
+    Steps where the target element cannot be found in the current snapshot are
+    skipped with a warning — this handles cases where an element is only revealed
+    after a prior interaction.
+    """
+    _log = logging.getLogger("stlc.playwright_mcp")
+    all_maps: list[dict] = []
 
-    # use cart icon link rather than hard-coded /cart.html
-    after_add_snap = pmcp.call("browser_snapshot", {})
-    cart_icon_ref = _find_ref(after_add_snap, role="link", name_patterns=[r"shopping cart|cart"])
-    if cart_icon_ref:
-        pmcp.call("browser_click", {"ref": cart_icon_ref})
+    # Phase 1 — reach the starting page
+    if _needs_login(app_url, username, password):
+        current_snap = _do_login(pmcp, app_url, username, password)
     else:
-        pmcp.call("browser_navigate", {"url": f"{base}/cart.html"})
+        pmcp.call("browser_navigate", {"url": app_url})
+        current_snap = pmcp.call("browser_snapshot", {})
 
-    cart_snap = pmcp.call("browser_snapshot", {})
-    checkout_ref = _find_ref(cart_snap, role="button", name_patterns=[r"checkout"])
-    if checkout_ref:
-        pmcp.call("browser_click", {"ref": checkout_ref})
+    landing_map = _build_context_map_from_snapshot(current_snap)
+    all_maps.append(landing_map)
+    _log.info("gherkin capture: landing page elements=%s", list(landing_map.keys())[:10])
 
-    checkout_snap = pmcp.call("browser_snapshot", {})
+    if not gherkin:
+        return _merge_maps(*all_maps)
 
-    return _merge_maps(
-        _build_context_map_from_snapshot(post_login),
-        _build_context_map_from_snapshot(inventory_snap),
-        _build_context_map_from_snapshot(cart_snap),
-        _build_context_map_from_snapshot(checkout_snap),
-    )
+    # Phase 2 — replay interaction steps
+    steps = _parse_gherkin_steps(gherkin)
+    for step_text in steps.get("all_steps", []):
+        target = _extract_interaction_target(step_text)
+        if not target:
+            continue
+
+        _log.info("gherkin capture: looking for '%s'", target)
+        ref = _find_element_ref(current_snap, target)
+        if not ref:
+            _log.info("gherkin capture: '%s' not found in snapshot — skipping", target)
+            continue
 
+        try:
+            pmcp.call("browser_click", {"element": target, "ref": ref})
+            time.sleep(0.4)  # let DOM/animation settle
+            new_snap = pmcp.call("browser_snapshot", {})
+            new_map = _build_context_map_from_snapshot(new_snap)
+            if new_map:
+                all_maps.append(new_map)
+                current_snap = new_snap
+                _log.info(
+                    "gherkin capture: after '%s' → %d elements (total states=%d)",
+                    target, len(new_map), len(all_maps),
+                )
+        except Exception as exc:
+            _log.warning("gherkin capture: interaction '%s' failed: %s", target, exc)
 
-def _is_checkout_flow(app_url: str, gherkin: str) -> bool:
-    haystack = (app_url + " " + gherkin).lower()
-    return all(kw in haystack for kw in ("checkout", "first name", "last name"))
+    return _merge_maps(*all_maps)
 
 
 # ── Public implementation ─────────────────────────────────────────────────────
@@ -1725,9 +1841,18 @@ def _capture_app_context(
     """
     Navigate the live application and return a verified context_map.
 
-    Owns the full browser lifecycle: start Playwright MCP if needed,
-    navigate / login / snapshot, build context_map, shut down.
+    Uses Gherkin-driven capture: replays the interaction steps described in the
+    Gherkin to visit every relevant page state.  Works for any application —
+    no app-specific flow knowledge required.
+
+    Owns the full browser lifecycle: start Playwright MCP if needed, run the
+    capture, shut down.
     """
+    _log = logging.getLogger("stlc.playwright_mcp")
+    _log.info(
+        "capture_app_context: url=%s username=%s password=%s mcp=%s",
+        app_url, bool(app_username), bool(app_password), playwright_mcp_url,
+    )
     if not app_url:
         return {
             "context_map": {},
@@ -1738,20 +1863,9 @@ def _capture_app_context(
     pmcp = _PlaywrightMcp(playwright_mcp_url)
     try:
         pmcp.ensure_running()
-
-        if _is_checkout_flow(app_url, gherkin_content):
-            # Multi-step flow: login → add to cart → checkout form
-            context_map = _capture_checkout_flow(pmcp, app_url, app_username, app_password)
-        else:
-            # Standard flow: navigate (with login if credentials supplied) → snapshot
-            if _needs_login(app_url, app_username, app_password):
-                # _do_login navigates to app_url, fills credentials, returns post-login snap
-                landing_snap = _do_login(pmcp, app_url, app_username, app_password)
-            else:
-                pmcp.call("browser_navigate", {"url": app_url})
-                landing_snap = pmcp.call("browser_snapshot", {})
-            context_map = _build_context_map_from_snapshot(landing_snap)
-
+        context_map = _capture_gherkin_driven(
+            pmcp, app_url, app_username, app_password, gherkin_content,
+        )
         locator_source = "playwright-mcp-verified" if context_map else "gherkin-inferred"
         return {
             "context_map":    context_map,
@@ -1760,11 +1874,13 @@ def _capture_app_context(
         }
 
     except Exception as exc:
+        _log.error("capture_app_context failed: %s", exc, exc_info=True)
         return {
             "context_map":    {},
             "locator_source": "gherkin-inferred",
             "error":          str(exc),
-            "note":           "Browser capture failed — caller may proceed with gherkin-inferred locators",
+            "abort":          True,
+            "note":           "Browser capture failed. STOP — do NOT call generate_playwright_code. Fix the error above, ensure the Playwright MCP server is reachable, then retry capture_app_context.",
         }
     finally:
         pmcp.close()
@@ -1803,11 +1919,14 @@ def _generate_playwright_code(
             f"//   browser_navigate('{app_url}') → browser_snapshot() → pass result as context_map\n"
         )
         new_locators = snapshot_hint + new_locators
+    new_step_defs, derived_methods = _gen_step_defs(
+        page_class, kebab, camel, all_steps, auth_hook)
     new_page_object = _gen_page_object(
         page_class, kebab, camel, gherkin, healing_strategy,
-        enable_visual_regression, enable_timing_healing)
-    new_step_defs = _gen_step_defs(
-        page_class, kebab, camel, all_steps, auth_hook)
+        enable_visual_regression, enable_timing_healing,
+        derived_methods=derived_methods,
+        context_map=context_map,
+        app_url=app_url)
     new_feature = _gen_feature_file(gherkin, kebab, page_class)
 
     # Normalize feature file: auto-quote unquoted string parameters so they
@@ -1915,14 +2034,30 @@ def _gen_locators(page_class, kebab, gherkin, context_map=None):
             " * Run Playwright MCP (npx @playwright/mcp@latest --port 8931) and use\n"
             " * browser_navigate + browser_snapshot to replace them with real selectors."
         )
+        body = (
+            f"  pageContainer:     {{ selector: \"[data-testid='{kebab}-container']\",    intent: '{page_class} main page container',    stability: 0 }},\n"
+            f"  primaryActionBtn:  {{ selector: \"[data-testid='{kebab}-action-btn']\",   intent: 'primary action button',               stability: 0, visualIntent: true }},\n"
+            f"  submitBtn:         {{ selector: \"[data-testid='{kebab}-submit']\",        intent: 'submit form button',                  stability: 0, visualIntent: true }},\n"
+            f"  confirmBtn:        {{ selector: \"[data-testid='{kebab}-confirm']\",       intent: 'confirm action button',               stability: 0, visualIntent: true }},\n"
+            f"  cancelBtn:         {{ selector: \"[data-testid='{kebab}-cancel']\",        intent: 'cancel or close button',              stability: 0 }},\n"
+            f"  saveBtn:           {{ selector: \"[data-testid='{kebab}-save']\",          intent: 'save changes button',                 stability: 0, visualIntent: true }},\n"
+            f"  primaryInputField: {{ selector: \"[data-testid='{kebab}-primary-input']\", intent: 'primary text input',                  stability: 0 }},\n"
+            f"  fileInput:         {{ selector: \"input[type='file']\",                    intent: 'file upload input',                   stability: 70 }},\n"
+            f"  successToast:      {{ selector: \"[data-testid='toast-success']\",         intent: 'success notification toast',          stability: 0, visualIntent: true }},\n"
+            f"  errorToast:        {{ selector: \"[data-testid='toast-error']\",           intent: 'error notification toast',            stability: 0, visualIntent: true }},\n"
+            f"  validationError:   {{ selector: \"[data-testid='validation-error']\",      intent: 'form validation error message',       stability: 0, visualIntent: true }},\n"
+            f"  successIndicator:  {{ selector: \"[data-testid='{kebab}-success']\",       intent: 'success state indicator',             stability: 0, visualIntent: true }},\n"
+            f"  updatedIndicator:  {{ selector: \"[data-testid='{kebab}-updated']\",       intent: 'updated state indicator',             stability: 0 }},\n"
+            f"{extras}"
+        )
     else:
-        extras = cdp_entries
         source_note = (
             " *\n"
             " * SOURCE: Playwright MCP accessibility tree snapshot.\n"
             " * Stability rank: data-testid(100) > aria-role+name(90) > id(80) > aria-label(70) > placeholder(60).\n"
             " * All selectors derived from real AX nodes — zero hallucinated values."
         )
+        body = cdp_entries
 
     return f'''/**
  * Locators: {page_class}Page
@@ -1933,20 +2068,7 @@ def _gen_locators(page_class, kebab, gherkin, context_map=None):
  *   visualIntent: when true, VisualIntentChecker screenshots this element at assertions{source_note}
  */
 export const {page_class}Locators = {{
-  pageContainer:     {{ selector: "[data-testid='{kebab}-container']",    intent: '{page_class} main page container',    stability: 0 }},
-  primaryActionBtn:  {{ selector: "[data-testid='{kebab}-action-btn']",   intent: 'primary action button',               stability: 0, visualIntent: true }},
-  submitBtn:         {{ selector: "[data-testid='{kebab}-submit']",        intent: 'submit form button',                  stability: 0, visualIntent: true }},
-  confirmBtn:        {{ selector: "[data-testid='{kebab}-confirm']",       intent: 'confirm action button',               stability: 0, visualIntent: true }},
-  cancelBtn:         {{ selector: "[data-testid='{kebab}-cancel']",        intent: 'cancel or close button',              stability: 0 }},
-  saveBtn:           {{ selector: "[data-testid='{kebab}-save']",          intent: 'save changes button',                 stability: 0, visualIntent: true }},
-  primaryInputField: {{ selector: "[data-testid='{kebab}-primary-input']", intent: 'primary text input',                  stability: 0 }},
-  fileInput:         {{ selector: "input[type='file']",                    intent: 'file upload input',                   stability: 70 }},
-  successToast:      {{ selector: "[data-testid='toast-success']",         intent: 'success notification toast',          stability: 0, visualIntent: true }},
-  errorToast:        {{ selector: "[data-testid='toast-error']",           intent: 'error notification toast',            stability: 0, visualIntent: true }},
-  validationError:   {{ selector: "[data-testid='validation-error']",      intent: 'form validation error message',       stability: 0, visualIntent: true }},
-  successIndicator:  {{ selector: "[data-testid='{kebab}-success']",       intent: 'success state indicator',             stability: 0, visualIntent: true }},
-  updatedIndicator:  {{ selector: "[data-testid='{kebab}-updated']",       intent: 'updated state indicator',             stability: 0 }},
-{extras}}} as const;
+{body}}} as const;
 export type LocatorKey = keyof typeof {page_class}Locators;
 '''
 
@@ -1985,139 +2107,193 @@ def _gen_locators_from_flat_map(context_map: dict) -> str:
 
 
 def _gen_page_object(page_class, kebab, camel, gherkin, healing_strategy,
-                      enable_visual_regression, enable_timing_healing):
-    steps     = _parse_gherkin_steps(gherkin)["all_steps"]
-    stubs     = _build_method_stubs(camel, steps)
+                      enable_visual_regression, enable_timing_healing,
+                      derived_methods=None, context_map=None, app_url=None):
+    steps  = _parse_gherkin_steps(gherkin)["all_steps"]
+    stubs  = _build_method_stubs(camel, steps, derived_methods or [])
     vi_import = 'import { VisualIntentChecker } from "@utils/locators/VisualIntentChecker";' if enable_visual_regression else ""
     th_import = 'import { TimingHealer } from "@utils/locators/TimingHealer";' if enable_timing_healing else ""
-    # BasePage provides visual & timing fields and initialisation; avoid redeclaring them
-    vi_field  = ""
-    th_field  = ""
-    vi_init   = ""  # initialised by BasePage
-    th_init   = ""  # initialised by BasePage
-    tn        = '    await this.timing.waitForNetworkIdle("navigate");' if enable_timing_healing else ""
-    ts_       = '    await this.timing.waitForNetworkIdle("submitForm");' if enable_timing_healing else ""
-    vc        = '    await this.visual.check("successToast", this.loc.successToast.selector, this.loc.successToast.intent);' if enable_visual_regression else ""
-
-    return f'''import {{ Page, expect }} from "@playwright/test";
-import {{ fixture }} from "@hooks/pageFixture";
-import {{ {page_class}Locators }} from "../locators/{kebab}.locators";
-import {{ LocatorHealer }} from "@utils/locators/LocatorHealer";
-import {{ LocatorRepository }} from "@utils/locators/LocatorRepository";
-import {{ BasePage }} from "./BasePage";
-{vi_import}
-{th_import}
-
-/**
- * {page_class}Page — Three-Layer Self-Healing Page Object
- *
- * Layer 1 — Locator Healing ({healing_strategy}):
- *   primary selector → role-based → label-based → text-based → playwright-cli + Claude AI Vision
- *   → DevToolsHealer AX tree (CDPSession) → DevToolsHealer bounding box (CDPSession)
- *   Healed selectors persisted in LocatorRepository — zero overhead on repeat runs.
- *
-{" * Layer 2 — Timing Healing (TimingHealer): intercepts network traces, auto-heals timeout drift." if enable_timing_healing else ""}
-{" *" if enable_timing_healing else ""}
-{" * Layer 3 — Visual Intent (VisualIntentChecker): element screenshot diff at assertions." if enable_visual_regression else ""}
-{" *" if enable_visual_regression else ""}
-{" * HealingDashboard: http://localhost:7890 — approve/reject all AI suggestions." if (enable_timing_healing or enable_visual_regression) else ""}
- *
- * RULE: Never call page.click / page.fill / page.locator directly.
- */
-export default class {page_class}Page extends BasePage {{
-    private readonly loc = {page_class}Locators;
-
-    constructor(page?: Page) {{
-        super(page ?? fixture().page);
-        Object.entries(this.loc).forEach(([key, val]) =>
-            this.repo.register(key, val.selector, val.intent));
-    }}
-
-  async navigate(): Promise<void> {{
-    const url = `${{this.env.getBaseUrl()}}/${{this.env.getPath("{kebab}")}}`;
-    fixture().logger.info(`Navigating to ${{url}}`);
-    await this.page.goto(url, {{ waitUntil: "networkidle" }});
-{tn}
-    await this.healer.assertVisibleWithHealing(
-      "pageContainer", this.loc.pageContainer.selector, this.loc.pageContainer.intent);
-  }}
-
-  async waitForPageLoad(): Promise<void> {{
-    await this.healer.assertVisibleWithHealing(
-      "pageContainer", this.loc.pageContainer.selector, this.loc.pageContainer.intent);
-  }}
-
-  async submitForm(): Promise<void> {{
-    await this.healer.clickWithHealing(
-      "submitBtn", this.loc.submitBtn.selector, this.loc.submitBtn.intent);
-{ts_}
-  }}
-
-  async confirmAction(): Promise<void> {{
-    await this.healer.clickWithHealing(
-      "confirmBtn", this.loc.confirmBtn.selector, this.loc.confirmBtn.intent);
-  }}
-
-  async clickCancel(): Promise<void> {{
-    await this.healer.clickWithHealing(
-      "cancelBtn", this.loc.cancelBtn.selector, this.loc.cancelBtn.intent);
-  }}
-
-  async clickSave(): Promise<void> {{
-    await this.healer.clickWithHealing(
-      "saveBtn", this.loc.saveBtn.selector, this.loc.saveBtn.intent);
-  }}
-
-  async fillPrimaryInput(value: string): Promise<void> {{
-    await this.healer.fillWithHealing(
-      "primaryInputField", this.loc.primaryInputField.selector, value, this.loc.primaryInputField.intent);
-  }}
-
-  async uploadFile(buffer: Buffer, fileName: string, mimeType: string): Promise<void> {{
-    await this.page.locator(this.loc.fileInput.selector).setInputFiles({{ name: fileName, mimeType, buffer }});
-  }}
-
-  async verifySuccessToast(): Promise<void> {{
-    await this.healer.assertVisibleWithHealing(
-      "successToast", this.loc.successToast.selector, this.loc.successToast.intent);
-{vc}
-    fixture().logger.info("✓ Success toast verified (locator + visual)");
-  }}
-
-  async verifyErrorToast(): Promise<void> {{
-    await this.healer.assertVisibleWithHealing(
-      "errorToast", this.loc.errorToast.selector, this.loc.errorToast.intent);
-    fixture().logger.info("✓ Error toast verified");
-  }}
-
-  async verifyValidationErrors(): Promise<void> {{
-    await this.healer.assertVisibleWithHealing(
-      "validationError", this.loc.validationError.selector, this.loc.validationError.intent);
-    const count = await this.page.locator(this.loc.validationError.selector).count();
-    expect(count).toBeGreaterThan(0);
-  }}
+    tn = '    await this.timing.waitForNetworkIdle("navigate");' if enable_timing_healing else ""
+    ts_ = '    await this.timing.waitForNetworkIdle("submitForm");' if enable_timing_healing else ""
+    vc  = '    await this.visual.check("successToast", this.loc.successToast.selector, this.loc.successToast.intent);' if enable_visual_regression else ""
+
+    # Extract verified locator keys from context_map.
+    # When avail is non-empty (real capture), template methods are emitted only for
+    # locator keys that actually exist — prevents TypeScript errors and invented code.
+    avail: set = set()
+    if context_map and context_map.get("locators"):
+        avail = {loc["key"] for loc in context_map["locators"]}
+    elif context_map and isinstance(context_map, dict):
+        avail = {k for k, v in context_map.items() if isinstance(v, dict) and "selector" in v}
+
+    def _has(*keys: str) -> bool:
+        return not avail or all(k in avail for k in keys)
+
+    # ── navigate() ──────────────────────────────────────────────────────────
+    if app_url:
+        nav = (
+            "\n\n  async navigate(): Promise<void> {\n"
+            f'    this.logger.info("Navigating to {app_url}");\n'
+            f'    await this.page.goto("{app_url}", {{ waitUntil: "domcontentloaded" }});\n'
+            f"{tn}\n"
+            "  }"
+        )
+    elif not avail:
+        nav = (
+            "\n\n  async navigate(): Promise<void> {\n"
+            "    // TODO: replace with actual URL (e.g. this.env.baseUrl + '/inventory.html')\n"
+            "    const url = `${this.env.baseUrl}`;\n"
+            "    this.logger.info(`Navigating to ${url}`);\n"
+            "    await this.page.goto(url, { waitUntil: 'domcontentloaded' });\n"
+            f"{tn}\n"
+            "  }"
+        )
+    else:
+        nav = ""  # real context_map but no URL — omit rather than invent a path
 
-  async verifySuccessState(): Promise<void> {{
-    await this.healer.assertVisibleWithHealing(
-      "successIndicator", this.loc.successIndicator.selector, this.loc.successIndicator.intent);
-  }}
+    # ── conditional template methods ─────────────────────────────────────────
+    parts: list = []
 
-  async verifyStatePersisted(): Promise<void> {{
-    await this.healer.assertVisibleWithHealing(
-      "updatedIndicator", this.loc.updatedIndicator.selector, this.loc.updatedIndicator.intent);
-  }}
+    parts.append(
+        "  async waitForPageLoad(): Promise<void> {\n"
+        "    await this.waitHelper.waitForPageLoad();\n"
+        "  }"
+    )
+    if _has("submitBtn"):
+        parts.append(
+            "  async submitForm(): Promise<void> {\n"
+            "    await this.healer.clickWithHealing(\n"
+            '      "submitBtn", this.loc.submitBtn.selector, this.loc.submitBtn.intent);\n'
+            f"{ts_}\n"
+            "  }"
+        )
+    if _has("confirmBtn"):
+        parts.append(
+            "  async confirmAction(): Promise<void> {\n"
+            "    await this.healer.clickWithHealing(\n"
+            '      "confirmBtn", this.loc.confirmBtn.selector, this.loc.confirmBtn.intent);\n'
+            "  }"
+        )
+    if _has("cancelBtn"):
+        parts.append(
+            "  async clickCancel(): Promise<void> {\n"
+            "    await this.healer.clickWithHealing(\n"
+            '      "cancelBtn", this.loc.cancelBtn.selector, this.loc.cancelBtn.intent);\n'
+            "  }"
+        )
+    if _has("saveBtn"):
+        parts.append(
+            "  async clickSave(): Promise<void> {\n"
+            "    await this.healer.clickWithHealing(\n"
+            '      "saveBtn", this.loc.saveBtn.selector, this.loc.saveBtn.intent);\n'
+            "  }"
+        )
+    if _has("primaryInputField"):
+        parts.append(
+            "  async fillPrimaryInput(value: string): Promise<void> {\n"
+            "    await this.healer.fillWithHealing(\n"
+            '      "primaryInputField", this.loc.primaryInputField.selector, value, this.loc.primaryInputField.intent);\n'
+            "  }"
+        )
+    if _has("fileInput"):
+        parts.append(
+            "  async uploadFile(buffer: Buffer, fileName: string, mimeType: string): Promise<void> {\n"
+            "    await this.page.locator(this.loc.fileInput.selector).setInputFiles({ name: fileName, mimeType, buffer });\n"
+            "  }"
+        )
+    if _has("successToast"):
+        parts.append(
+            "  async verifySuccessToast(): Promise<void> {\n"
+            "    await this.healer.assertVisibleWithHealing(\n"
+            '      "successToast", this.loc.successToast.selector, this.loc.successToast.intent);\n'
+            f"{vc}\n"
+            '    fixture().logger.info("✓ Success toast verified (locator + visual)");\n'
+            "  }"
+        )
+    if _has("errorToast"):
+        parts.append(
+            "  async verifyErrorToast(): Promise<void> {\n"
+            "    await this.healer.assertVisibleWithHealing(\n"
+            '      "errorToast", this.loc.errorToast.selector, this.loc.errorToast.intent);\n'
+            '    fixture().logger.info("✓ Error toast verified");\n'
+            "  }"
+        )
+    if _has("validationError"):
+        parts.append(
+            "  async verifyValidationErrors(): Promise<void> {\n"
+            "    await this.healer.assertVisibleWithHealing(\n"
+            '      "validationError", this.loc.validationError.selector, this.loc.validationError.intent);\n'
+            "    const count = await this.page.locator(this.loc.validationError.selector).count();\n"
+            "    expect(count).toBeGreaterThan(0);\n"
+            "  }"
+        )
+    if _has("successIndicator"):
+        parts.append(
+            "  async verifySuccessState(): Promise<void> {\n"
+            "    await this.healer.assertVisibleWithHealing(\n"
+            '      "successIndicator", this.loc.successIndicator.selector, this.loc.successIndicator.intent);\n'
+            "  }"
+        )
+    if _has("updatedIndicator"):
+        parts.append(
+            "  async verifyStatePersisted(): Promise<void> {\n"
+            "    await this.healer.assertVisibleWithHealing(\n"
+            '      "updatedIndicator", this.loc.updatedIndicator.selector, this.loc.updatedIndicator.intent);\n'
+            "  }"
+        )
+        parts.append(
+            "  async reloadAndVerify(): Promise<void> {\n"
+            "    await this.page.reload({ waitUntil: 'networkidle' });\n"
+            "    await this.verifyStatePersisted();\n"
+            "  }"
+        )
 
-  async reloadAndVerify(): Promise<void> {{
-    await this.page.reload({{ waitUntil: "networkidle" }});
-    await this.verifyStatePersisted();
-  }}
+    methods_block = "\n\n".join(parts)
+    layer2    = " * Layer 2 — Timing Healing (TimingHealer): intercepts network traces, auto-heals timeout drift.\n *" if enable_timing_healing else ""
+    layer3    = " * Layer 3 — Visual Intent (VisualIntentChecker): element screenshot diff at assertions.\n *" if enable_visual_regression else ""
+    dashboard = " * HealingDashboard: http://localhost:7890 — approve/reject all AI suggestions." if (enable_timing_healing or enable_visual_regression) else ""
 
-{stubs}
-}}
-'''
+    return (
+        f'import {{ Page, expect }} from "@playwright/test";\n'
+        f'import {{ fixture }} from "@hooks/pageFixture";\n'
+        f'import {{ {page_class}Locators }} from "../locators/{kebab}.locators";\n'
+        f'import {{ LocatorHealer }} from "@utils/locators/LocatorHealer";\n'
+        f'import {{ LocatorRepository }} from "@utils/locators/LocatorRepository";\n'
+        f'import {{ BasePage }} from "./BasePage";\n'
+        f'{vi_import}\n'
+        f'{th_import}\n'
+        f'\n'
+        f'/**\n'
+        f' * {page_class}Page — Three-Layer Self-Healing Page Object\n'
+        f' *\n'
+        f' * Layer 1 — Locator Healing ({healing_strategy}):\n'
+        f' *   primary selector → role-based → label-based → text-based → playwright-cli + Claude AI Vision\n'
+        f' *   → DevToolsHealer AX tree (CDPSession) → DevToolsHealer bounding box (CDPSession)\n'
+        f' *   Healed selectors persisted in LocatorRepository — zero overhead on repeat runs.\n'
+        f' *\n'
+        + (f' * Layer 2 — Timing Healing (TimingHealer): intercepts network traces, auto-heals timeout drift.\n *\n' if enable_timing_healing else '')
+        + (f' * Layer 3 — Visual Intent (VisualIntentChecker): element screenshot diff at assertions.\n *\n' if enable_visual_regression else '')
+        + (f' * HealingDashboard: http://localhost:7890 — approve/reject all AI suggestions.\n' if (enable_timing_healing or enable_visual_regression) else '')
+        + f' *\n'
+        f' * RULE: Never call page.click / page.fill / page.locator directly.\n'
+        f' */\n'
+        f'export default class {page_class}Page extends BasePage {{\n'
+        f'    private readonly loc = {page_class}Locators;\n'
+        f'\n'
+        f'    constructor(page?: Page) {{\n'
+        f'        super(page ?? fixture().page);\n'
+        f'        Object.entries(this.loc).forEach(([key, val]) =>\n'
+        f'            this.repo.register(key, val.selector, val.intent));\n'
+        f'    }}'
+        + nav
+        + '\n\n'
+        + methods_block
+        + ('\n\n' + stubs if stubs.strip() else '')
+        + '\n}\n'
+    )
 
 
-def _build_method_stubs(camel, steps):
+def _build_method_stubs(camel, steps, derived_methods=None):
     stubs, seen = [], set()
     for step in steps:
         lower = step.lower()
@@ -2144,6 +2320,18 @@ def _build_method_stubs(camel, steps):
     await this.verifyStatePersisted();
     fixture().logger.info("✓ State persisted after refresh");
   }''')
+
+    # Emit stubs for every derived method called by the step definitions.
+    # These throw so tests fail loudly instead of silently passing with no-ops.
+    for method_name in (derived_methods or []):
+        if method_name not in seen:
+            seen.add(method_name)
+            stubs.append(
+                f'  async {method_name}(...args: unknown[]): Promise<void> {{\n'
+                f'    throw new Error("not yet implemented: {method_name}");\n'
+                f'  }}'
+            )
+
     return "\n\n".join(stubs)
 
 
@@ -2208,6 +2396,18 @@ def _step_text_to_cucumber_pattern(text: str) -> str:
 
 def _build_step_callback(kw, text, method_call, camel, page_class):
     """Build one Cucumber step definition block using Cucumber expressions."""
+    # @cucumber/cucumber does not export And/But as step-definition functions.
+    # Normalise them to When (action) or Then (assertion) based on the method name.
+    if kw in ("And", "But"):
+        _lower_m = method_call.lower()
+        _lower_t = text.lower()
+        _assertion_words = (
+            "verify", "assert", "should", "expect", "check",
+            "visible", "enabled", "disabled", "present", "contain",
+            "navigated", "remain", "not_", "available", "reachable",
+        )
+        kw = "Then" if any(w in _lower_m or w in _lower_t for w in _assertion_words) else "When"
+
     pattern    = _step_text_to_cucumber_pattern(text)
     param_types = re.findall(r'\{(string|int|float|word)\}', pattern)
     if param_types:
@@ -2266,9 +2466,12 @@ def _gen_step_defs(page_class, kebab, camel, all_steps, auth_hook):
         )
 
     mappings: list = [
-        # navigation
-        (["navigates to", "is on the", "navigate to", "visits the",
-          "goes to", "opens the", "on the page", "on the site"],
+        # navigation — only match unambiguously page-level navigation phrases;
+        # "opens the" and "is on the" are intentionally excluded: they are too broad
+        # and incorrectly match steps like "opens the sidebar menu" or "is on the cart page".
+        # Those steps fall through to _step_text_to_method_name and get correct derived names.
+        (["navigates to", "navigate to", "visits the", "goes to",
+          "is on the main page", "is on the home page", "on the site"],
          f"{camel}Page.navigate()"),
         # cart setup
         (["has items in", "has item in", "items in the cart",
@@ -2452,7 +2655,9 @@ def _gen_step_defs(page_class, kebab, camel, all_steps, auth_hook):
             " */\n"
         )
 
-    return (
+    derived_method_names = [mn for _kw, _text, mn in unmapped_steps]
+
+    content = (
         f'import {{ Given, When, Then }} from "@cucumber/cucumber";\n'
         f'import {{ expect }} from "@playwright/test";\n'
         f'import {{ fixture }} from "@hooks/pageFixture";\n'
@@ -2467,6 +2672,7 @@ def _gen_step_defs(page_class, kebab, camel, all_steps, auth_hook):
         f'{unmapped_comment}'
         + "".join(blocks)
     )
+    return content, derived_method_names
 
 
 def _gen_feature_file(gherkin: str, kebab: str, page_class: str) -> str: