@qa-gentic/stlc-agents 1.0.16 → 1.0.17

package/src/stlc_agents/agent_playwright_generator/server.py

@@ -1,29 +1,30 @@
 """
 Agent 3: QA Playwright Code Generator — MCP Server
 
-Browser interaction at generation time is handled by the external Playwright MCP
-server (github.com/microsoft/playwright-mcp). Start it before running workflows:
-    npx @playwright/mcp@latest --port 8931
-
-The coding agent uses Playwright MCP tools (browser_navigate, browser_snapshot,
-browser_fill, browser_click, browser_wait_for_url) to build a verified context_map
-of locators from the live accessibility tree, then passes that map to
-generate_playwright_code.
+This agent owns all browser interaction.  The pipeline is a pure orchestrator
+that passes credentials/URL; this server does the browser walk and returns a
+verified context_map.
+
+Tools exposed:
+  capture_app_context      — navigate app, snapshot AX tree, return context_map
+  generate_playwright_code — generate TS files from gherkin + context_map
+  scaffold_locator_repository — generate self-healing infrastructure once per project
+  get_generated_files      — retrieve cached TS file contents
+  attach_code_to_work_item — attach generated files to an ADO work item
+  validate_gherkin_steps   — parse and return unique steps by keyword
+  pre_validate_cucumber_steps — validate step-def syntax before write_helix_files
 
 Three layers of self-healing at TEST RUNTIME:
   1. Locator Healing    — selector chain + AI Vision
   2. Timing Healing     — network trace drift detection → auto-adjusted timeouts
   3. Visual Regression  — element screenshot diff against approved baseline
 
-DevToolsHealer (Layer 4) runs at test runtime via Playwright's built-in CDPSession —
-no external process or port required.
-
 CI/CD Telemetry:
   HealingDashboard — HTTP server on :7890, engineers review/approve AI suggestions
   before they are permanently committed to the repository.
 """
 from __future__ import annotations
-import asyncio, json, re, sys, os, uuid
+import asyncio, json, re, sys, os, uuid, socket, subprocess, time, threading, queue
 from pathlib import Path
 from dotenv import load_dotenv
 from mcp.server import Server
@@ -39,8 +40,29 @@ app = Server("qa-playwright-generator")
 # File content cache — keeps large TS blobs out of conversation history.
 # generate_playwright_code and scaffold_locator_repository store files here
 # keyed by a short cache_key; get_generated_files retrieves them on demand.
+#
+# Files are persisted to disk so the cache survives MCP server restarts.
+# Each entry is written as JSON under _CACHE_DIR/<cache_key>.json.
 # ---------------------------------------------------------------------------
-_file_cache: dict[str, dict] = {}
+import tempfile as _tempfile
+
+_CACHE_DIR = Path(_tempfile.gettempdir()) / "stlc_file_cache"
+_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _cache_write(cache_key: str, files: dict) -> None:
+    (_CACHE_DIR / f"{cache_key}.json").write_text(json.dumps(files))
+
+
+def _cache_read(cache_key: str) -> dict | None:
+    p = _CACHE_DIR / f"{cache_key}.json"
+    if not p.exists():
+        return None
+    return json.loads(p.read_text())
+
+
+def _cache_has(cache_key: str) -> bool:
+    return (_CACHE_DIR / f"{cache_key}.json").exists()
 
 
 # ---------------------------------------------------------------------------
@@ -136,6 +158,48 @@ def _validate_attach_inputs(files: list[dict]) -> dict:
 @app.list_tools()
 async def list_tools() -> list[types.Tool]:
     return [
+        types.Tool(
+            name="capture_app_context",
+            description=(
+                "Navigate the live application using the Playwright MCP server, capture the "
+                "AX accessibility tree via browser_snapshot, and return a verified context_map "
+                "of locators.  Handles login flows automatically when app_username and "
+                "app_password are supplied.  The returned context_map should be passed directly "
+                "to generate_playwright_code so selectors come from the real DOM rather than "
+                "Gherkin inference.\n\n"
+                "When APP_BASE_URL is not supplied this tool returns an empty context_map and "
+                "locator_source=\"gherkin-inferred\" — generation still proceeds."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "app_url": {
+                        "type": "string",
+                        "description": "Base URL of the application under test.",
+                    },
+                    "app_username": {
+                        "type": "string",
+                        "description": "Optional username for login flows.",
+                    },
+                    "app_password": {
+                        "type": "string",
+                        "description": "Optional password for login flows.",
+                    },
+                    "gherkin_content": {
+                        "type": "string",
+                        "description": (
+                            "Optional Gherkin feature text.  When supplied the agent uses it "
+                            "to decide which pages to navigate to (e.g. checkout flows)."
+                        ),
+                    },
+                    "playwright_mcp_url": {
+                        "type": "string",
+                        "description": "Override the Playwright MCP server URL (default: http://localhost:8931/mcp).",
+                    },
+                },
+                "required": [],
+            },
+        ),
         types.Tool(
             name="generate_playwright_code",
             description=(
@@ -178,13 +242,25 @@ async def list_tools() -> list[types.Tool]:
                             "> aria-label(70) > placeholder(60)."
                         ),
                     },
+                    "app_url": {
+                        "type": "string",
+                        "description": (
+                            "Optional base URL of the application under test "
+                            "(e.g. 'https://account.stg.myamplify.io'). "
+                            "When provided AND context_map is absent, Agent 3 will embed the URL "
+                            "as a comment in locators.ts so it is available for manual AX-tree "
+                            "snapshot runs. The URL is also echoed back in the result as app_url "
+                            "for reference. Agent 3 does not navigate to it directly — use "
+                            "browser_navigate + browser_snapshot via the Playwright MCP server "
+                            "to build a verified context_map, then pass context_map to this tool."
+                        ),
+                    },
                     "helix_project_root": {
                         "type": "string",
                         "description": (
                             "Optional path to Helix-QA project root. When provided, generated code "
                             "is merged with existing files (append-only, deduplication, conflict renaming). "
-                            "No overwrites ever occur. Locators with naming conflicts get unique names. "
-                            "Pass this to enable seamless integration with your automation framework."
+                            "No overwrites ever occur. Locators with naming conflicts get unique names."
                         ),
                     },
                 },
@@ -349,7 +425,17 @@ async def list_tools() -> list[types.Tool]:
 @app.call_tool()
 async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
     try:
-        if name == "generate_playwright_code":
+        if name == "capture_app_context":
+            result = await asyncio.to_thread(
+                _capture_app_context,
+                arguments.get("app_url", os.getenv("APP_BASE_URL", "")),
+                arguments.get("app_username", os.getenv("APP_USERNAME", "")),
+                arguments.get("app_password", os.getenv("APP_PASSWORD", "")),
+                arguments.get("gherkin_content", ""),
+                arguments.get("playwright_mcp_url",
+                              os.getenv("PLAYWRIGHT_MCP_URL", "http://localhost:8931/mcp")),
+            )
+        elif name == "generate_playwright_code":
             result = await asyncio.to_thread(
                 _generate_playwright_code,
                 arguments["gherkin_content"],
@@ -361,14 +447,19 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
                 arguments.get("enable_timing_healing", True),
                 arguments.get("context_map"),
                 arguments.get("helix_project_root"),
+                arguments.get("app_url"),
             )
             # Cache files; return manifest so TS content stays out of conversation
             cache_key = uuid.uuid4().hex[:8]
-            _file_cache[cache_key] = result.pop("files")
+            _files = result.pop("files")
+            _cache_write(cache_key, _files)
             result["cache_key"] = cache_key
-            result["files_manifest"] = list(_file_cache[cache_key].keys())
+            result["files_manifest"] = list(_files.keys())
             result.pop("healing_layers", None)
             result.pop("scaffold_note", None)
+            # Echo app_url so the caller knows which URL a live snapshot should target
+            if arguments.get("app_url"):
+                result["app_url"] = arguments["app_url"]
         elif name == "scaffold_locator_repository":
             result = await asyncio.to_thread(
                 _scaffold_locator_repository,
@@ -384,21 +475,22 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             result["_validation"] = _validate_scaffold_output(result)
             # Cache files; return manifest so TS content stays out of conversation
             cache_key = uuid.uuid4().hex[:8]
-            _file_cache[cache_key] = result.pop("files")
+            _files = result.pop("files")
+            _cache_write(cache_key, _files)
             result["cache_key"] = cache_key
-            result["files_manifest"] = list(_file_cache[cache_key].keys())
+            result["files_manifest"] = list(_files.keys())
             result.pop("healing_strategies", None)
             result.pop("healing_layers", None)
             result.pop("env_vars", None)
         elif name == "get_generated_files":
             cache_key = arguments["cache_key"]
-            if cache_key not in _file_cache:
+            if not _cache_has(cache_key):
                 result = {
                     "error": f"Cache key '{cache_key}' not found. "
                              "Re-run generate_playwright_code or scaffold_locator_repository.",
                 }
             else:
-                result = {"cache_key": cache_key, "files": _file_cache[cache_key]}
+                result = {"cache_key": cache_key, "files": _cache_read(cache_key)}
         elif name == "attach_code_to_work_item":
             # ── Pre-attach input validation ────────────────────────────────
             input_validation = _validate_attach_inputs(arguments.get("files", []))
@@ -1163,6 +1255,521 @@ def _merge_feature_file(new_feature_content: str, existing_content: str) -> str:
     return merged
 
 
+# ============================================================================
+# capture_app_context
+# ============================================================================
+
+# ── Playwright MCP helpers (owned by Agent 3, not by the pipeline) ────────────
+
+_PMCP_CALL_TIMEOUT    = 120
+_PMCP_STARTUP_WAIT    = 8
+_PMCP_CONNECT_TIMEOUT = 10
+
+
+def _port_is_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except (OSError, ConnectionRefusedError, socket.timeout):
+        return False
+
+
+def _parse_mcp_url_port(url: str):
+    m = re.match(r"https?://([^/:]+):(\d+)", url)
+    if m:
+        return m.group(1), int(m.group(2))
+    return "localhost", 8931
+
+
+def _find_free_port(start: int = 8932, end: int = 8999) -> int:
+    for port in range(start, end + 1):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    raise RuntimeError(f"No free TCP port found in {start}–{end}")
+
+
+class _PlaywrightMcp:
+    """Minimal synchronous Playwright MCP HTTP/SSE client used only by this agent."""
+
+    def __init__(self, base_url: str):
+        self._base_url = base_url.rstrip("/")
+        self._session_id: str | None = None
+        self._id = 0
+        self._proc: subprocess.Popen | None = None
+
+    def ensure_running(self) -> None:
+        import urllib.request, urllib.error
+        host, port = _parse_mcp_url_port(self._base_url)
+        if _port_is_open(host, port):
+            self._init_session()
+            return
+        # not running — launch on a free port
+        try:
+            new_port = _find_free_port(port, 8999)
+        except RuntimeError:
+            new_port = port
+        self._base_url = f"http://127.0.0.1:{new_port}/mcp"
+        cmd = ["npx", "@playwright/mcp@latest", "--port", str(new_port), "--headless"]
+        self._proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        deadline = time.monotonic() + _PMCP_STARTUP_WAIT
+        while time.monotonic() < deadline:
+            if _port_is_open("127.0.0.1", new_port, 0.5):
+                break
+            if self._proc.poll() is not None:
+                raise RuntimeError(f"Playwright MCP npx exited during startup: {self._proc.stderr.read()[:300]}")
+            time.sleep(0.5)
+        self._init_session()
+
+    def call(self, tool: str, arguments: dict) -> dict:
+        msg = self._build_rpc("tools/call", {"name": tool, "arguments": arguments})
+        resp = self._post(msg)
+        content = resp.get("result", {}).get("content", [])
+        if not content:
+            return {}
+        parts = [b.get("text", "") for b in content if b.get("type") == "text"]
+        text = "\n".join(parts)
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {"text": text}
+
+    def close(self) -> None:
+        if self._proc:
+            try:
+                self._proc.terminate()
+                self._proc.wait(timeout=5)
+            except Exception:
+                try:
+                    self._proc.kill()
+                except Exception:
+                    pass
+            finally:
+                self._proc = None
+
+    # ── internals ────────────────────────────────────────────────────────────
+
+    def _init_session(self) -> None:
+        msg = self._build_rpc("initialize", {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "qa-playwright-generator", "version": "1.0"},
+        })
+        self._post(msg)
+        # fire-and-forget initialized notification
+        try:
+            self._notify("notifications/initialized")
+        except Exception:
+            pass
+
+    def _notify(self, method: str) -> None:
+        import urllib.request
+        body = json.dumps({"jsonrpc": "2.0", "method": method, "params": {}}).encode()
+        headers = {"Content-Type": "application/json"}
+        if self._session_id:
+            headers["mcp-session-id"] = self._session_id
+        req = urllib.request.Request(self._base_url, data=body, headers=headers, method="POST")
+        try:
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass
+
+    def _build_rpc(self, method: str, params: dict) -> str:
+        self._id += 1
+        return json.dumps({"jsonrpc": "2.0", "id": self._id, "method": method, "params": params})
+
+    def _post(self, body: str) -> dict:
+        import urllib.request, urllib.error
+        headers: dict = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
+        if self._session_id:
+            headers["mcp-session-id"] = self._session_id
+        req = urllib.request.Request(self._base_url, data=body.encode(), headers=headers, method="POST")
+        try:
+            resp = urllib.request.urlopen(req, timeout=_PMCP_CALL_TIMEOUT)
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(f"Playwright MCP HTTP {e.code}: {e.read(200).decode(errors='replace')}")
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"Playwright MCP connection error: {e.reason}")
+
+        sid = resp.headers.get("mcp-session-id") or resp.headers.get("Mcp-Session-Id")
+        if sid and not self._session_id:
+            self._session_id = sid
+
+        content_type = resp.headers.get("Content-Type", "")
+        raw = resp.read()
+
+        if "text/event-stream" in content_type:
+            return self._parse_sse(raw.decode(errors="replace")) or self._read_sse_get()
+
+        try:
+            data = json.loads(raw.decode(errors="replace"))
+            if "result" in data or "error" in data:
+                return data
+        except json.JSONDecodeError:
+            pass
+
+        return self._read_sse_get()
+
+    def _parse_sse(self, text: str) -> dict | None:
+        for line in text.splitlines():
+            if line.startswith("data:"):
+                payload = line[5:].strip()
+                if not payload or payload == "[DONE]":
+                    continue
+                try:
+                    data = json.loads(payload)
+                    if "result" in data or "error" in data:
+                        return data
+                except json.JSONDecodeError:
+                    continue
+        return None  # fall through to GET SSE stream
+
+    def _read_sse_get(self) -> dict:
+        import urllib.request, urllib.error
+        headers: dict = {"Accept": "text/event-stream"}
+        if self._session_id:
+            headers["mcp-session-id"] = self._session_id
+        req = urllib.request.Request(self._base_url, headers=headers, method="GET")
+        try:
+            stream = urllib.request.urlopen(req, timeout=_PMCP_CALL_TIMEOUT)
+        except (urllib.error.URLError, urllib.error.HTTPError) as e:
+            raise RuntimeError(f"Playwright MCP SSE GET failed: {e}")
+        deadline = time.monotonic() + _PMCP_CALL_TIMEOUT
+        buf = ""
+        while time.monotonic() < deadline:
+            chunk = stream.read(4096)
+            if not chunk:
+                break
+            buf += chunk.decode(errors="replace")
+            for line in buf.splitlines():
+                if line.startswith("data:"):
+                    payload = line[5:].strip()
+                    if not payload or payload == "[DONE]":
+                        continue
+                    try:
+                        data = json.loads(payload)
+                        if "result" in data or "error" in data:
+                            stream.close()
+                            return data
+                    except json.JSONDecodeError:
+                        continue
+        raise RuntimeError("Playwright MCP SSE stream ended without a JSON-RPC result")
+
+
+# ── AX-tree snapshot helpers ──────────────────────────────────────────────────
+
+_AX_REF_RE = re.compile(
+    r"^\s*-\s+(?P<role>[\w-]+)(?:\s+\"(?P<name>[^\"]+)\")?\s+\[ref=(?P<ref>[^\]]+)\]"
+)
+_AX_TEXT_RE = re.compile(r"^\s*-\s+text:\s+(?P<text>.+)$")
+
+
+def _snapshot_to_text(snapshot: dict) -> str:
+    raw = ""
+    for block in snapshot.get("content", []):
+        if isinstance(block, dict) and block.get("type") == "text":
+            raw += block.get("text", "")
+    return raw or snapshot.get("text", "")
+
+
+def _parse_ax_elements(snapshot: dict) -> list[dict]:
+    elements: list[dict] = []
+    current: dict | None = None
+    for line in _snapshot_to_text(snapshot).splitlines():
+        m = _AX_REF_RE.match(line)
+        if m:
+            current = {"role": m.group("role") or "", "name": (m.group("name") or "").strip(), "ref": m.group("ref") or ""}
+            elements.append(current)
+            continue
+        tm = _AX_TEXT_RE.match(line)
+        if tm and current is not None and not current.get("name"):
+            current["name"] = tm.group("text").strip().strip('"')
+    return elements
+
+
+def _find_ref(snapshot: dict, *, role: str | None = None, name_patterns: list[str] | None = None) -> str | None:
+    compiled = [re.compile(p, re.IGNORECASE) for p in (name_patterns or [])]
+    for el in _parse_ax_elements(snapshot):
+        if role and el.get("role") != role:
+            continue
+        name = el.get("name", "")
+        if compiled and not any(p.search(name) for p in compiled):
+            continue
+        return el.get("ref")
+    return None
+
+
+def _to_camel(s: str) -> str:
+    words = re.split(r"[\s\-_]+", s.strip())
+    if not words:
+        return "element"
+    return words[0].lower() + "".join(w.capitalize() for w in words[1:])
+
+
+def _score_selector(sel: str) -> int:
+    if "data-testid" in sel or "data-test=" in sel:
+        return 100
+    if sel.startswith("[id=") or sel.startswith("#"):
+        return 80
+    if "aria-label" in sel:
+        return 70
+    if "placeholder" in sel:
+        return 60
+    return 40
+
+
+# Matches Playwright MCP YAML AX-tree lines:
+#   - button "Add to cart" [ref=e54] [cursor=pointer]
+#   - link "Sauce Labs Backpack" [ref=e45] [cursor=pointer]
+_AX_ROLE_LINE = re.compile(
+    r"^\s*-\s+(?P<role>[\w-]+)\s+\"(?P<name>[^\"]+)\"\s+\[ref=(?P<ref>[^\]]+)\]"
+)
+
+# Interactable roles we want to capture as locators
+_INTERACTABLE_ROLES = frozenset({
+    "button", "link", "textbox", "combobox", "checkbox",
+    "radio", "menuitem", "tab", "option", "searchbox", "input",
+})
+
+
+def _build_context_map_from_snapshot(snapshot: dict) -> dict:
+    """
+    Convert a Playwright MCP browser_snapshot into a context_map dict.
+
+    Handles three snapshot formats:
+      1. Structured tree/nodes dict (some MCP versions)
+      2. YAML AX-tree text in content[].text (Playwright MCP ≥0.0.14 default)
+      3. Raw HTML text fallback (data-testid / id attribute scan)
+    """
+    context_map: dict = {}
+    seen: set = set()
+
+    # ── Format 1: structured JSON tree ───────────────────────────────────────
+    for node in (snapshot.get("tree") or snapshot.get("nodes") or []):
+        if not isinstance(node, dict):
+            continue
+        role = node.get("role", "")
+        name = node.get("name", "") or node.get("text", "")
+        selector = node.get("selector") or node.get("css") or ""
+        if not selector or not name:
+            continue
+        key = _to_camel(name)[:40]
+        if key in seen:
+            key = f"{key}_{len(seen)}"
+        seen.add(key)
+        stab = _score_selector(selector)
+        context_map[key] = {
+            "selector":  selector,
+            "intent":    f"{role} — {name}".strip(" —"),
+            "stability": stab,
+            **({"visualIntent": True} if stab >= 70 else {}),
+        }
+    if context_map:
+        return context_map
+
+    # ── Format 2: YAML AX-tree text (Playwright MCP ref= format) ─────────────
+    # Build role+name → aria selector with stability 90 (high confidence from AX tree)
+    raw = _snapshot_to_text(snapshot)
+    for line in raw.splitlines():
+        m = _AX_ROLE_LINE.match(line)
+        if not m:
+            continue
+        role = m.group("role")
+        name = m.group("name").strip()
+        if not name or role not in _INTERACTABLE_ROLES:
+            continue
+        key = _to_camel(name)[:40]
+        if key in seen:
+            key = f"{key}_{len(seen)}"
+        seen.add(key)
+        # role+name aria selector — stable for interactable elements
+        safe_name = name.replace('"', '\\"')
+        selector = f'[role="{role}"][name="{safe_name}"]'
+        context_map[key] = {
+            "selector":    selector,
+            "intent":      f"{role} — {name}",
+            "stability":   90,
+            "visualIntent": role in ("button", "link"),
+        }
+    if context_map:
+        return context_map
+
+    # ── Format 3: HTML text fallback — data-testid / id attribute scan ────────
+    for m in re.finditer(r'data-test(?:id)?=["\']([^"\']+)["\']', raw):
+        tid = m.group(1)
+        key = _to_camel(tid.replace("-", " "))
+        if key not in seen:
+            seen.add(key)
+            context_map[key] = {
+                "selector":     f"[data-testid='{tid}']",
+                "intent":       tid.replace("-", " "),
+                "stability":    100,
+                "visualIntent": True,
+            }
+    for m in re.finditer(r'\bid=["\']([A-Za-z][A-Za-z0-9_\-]+)["\']', raw):
+        eid = m.group(1)
+        key = _to_camel(eid.replace("-", " "))
+        if key not in seen:
+            seen.add(key)
+            context_map[key] = {
+                "selector":  f"#{eid}",
+                "intent":    eid.replace("-", " "),
+                "stability": 80,
+            }
+    return context_map
+
+
+def _merge_maps(*maps: dict) -> dict:
+    merged: dict = {}
+    for cmap in maps:
+        for k, v in (cmap or {}).items():
+            if k not in merged or v.get("stability", 0) > merged[k].get("stability", 0):
+                merged[k] = v
+    return merged
+
+
+# ── Login flow detection / execution ─────────────────────────────────────────
+
+def _needs_login(app_url: str, username: str, password: str) -> bool:
+    return bool(username and password)
+
+
+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."""
+    pmcp.call("browser_navigate", {"url": app_url.rstrip("/")})
+    login_snap = pmcp.call("browser_snapshot", {})
+
+    user_ref = _find_ref(login_snap, role="textbox", name_patterns=[r"user(?:name)?|email|login"])
+    pass_ref = _find_ref(login_snap, role="textbox", name_patterns=[r"pass(?:word)?"])
+
+    if not user_ref or not pass_ref:
+        # no login form detected — return the snapshot as-is
+        return login_snap
+
+    # 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", {"ref": user_ref, "value": username})
+    pmcp.call("browser_fill", {"ref": pass_ref, "value": password})
+    if btn_ref:
+        pmcp.call("browser_click", {"ref": btn_ref})
+    else:
+        # Last resort: submit via Enter key on the password field
+        pmcp.call("browser_press", {"ref": pass_ref, "key": "Enter"})
+
+    return pmcp.call("browser_snapshot", {})
+
+
+# ── Multi-step flows driven by gherkin hints ──────────────────────────────────
+
+def _capture_checkout_flow(pmcp: _PlaywrightMcp, app_url: str, username: str, password: str) -> dict:
+    """
+    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.
+    """
+    base = app_url.rstrip("/")
+
+    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})
+
+    # 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})
+    else:
+        pmcp.call("browser_navigate", {"url": f"{base}/cart.html"})
+
+    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})
+
+    checkout_snap = pmcp.call("browser_snapshot", {})
+
+    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),
+    )
+
+
+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"))
+
+
+# ── Public implementation ─────────────────────────────────────────────────────
+
+def _capture_app_context(
+    app_url: str,
+    app_username: str,
+    app_password: str,
+    gherkin_content: str,
+    playwright_mcp_url: str,
+) -> dict:
+    """
+    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.
+    """
+    if not app_url:
+        return {
+            "context_map": {},
+            "locator_source": "gherkin-inferred",
+            "note": "app_url not provided — skipping browser capture",
+        }
+
+    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)
+
+        locator_source = "playwright-mcp-verified" if context_map else "gherkin-inferred"
+        return {
+            "context_map":    context_map,
+            "locator_source": locator_source,
+            "locator_count":  len(context_map),
+        }
+
+    except Exception as exc:
+        return {
+            "context_map":    {},
+            "locator_source": "gherkin-inferred",
+            "error":          str(exc),
+            "note":           "Browser capture failed — caller may proceed with gherkin-inferred locators",
+        }
+    finally:
+        pmcp.close()
+
+
 # ============================================================================
 # generate_playwright_code
 # ============================================================================
@@ -1170,7 +1777,7 @@ def _merge_feature_file(new_feature_content: str, existing_content: str) -> str:
 def _generate_playwright_code(
     gherkin, page_class, app_name, healing_strategy,
     auth_hook, enable_visual_regression, enable_timing_healing,
-    context_map=None, helix_project_root=None,
+    context_map=None, helix_project_root=None, app_url=None,
 ):
     kebab     = _to_kebab(page_class)
     camel     = page_class[0].lower() + page_class[1:]
@@ -1185,6 +1792,17 @@ def _generate_playwright_code(
 
     # Generate new content
     new_locators = _gen_locators(page_class, kebab, gherkin, context_map)
+
+    # If app_url is provided and no live context_map, prepend a snapshot hint comment
+    # so engineers know the URL to navigate to when running AX-tree capture manually.
+    if app_url and not context_map:
+        snapshot_hint = (
+            f"// APP URL: {app_url}\n"
+            f"// Locator source: gherkin-inferred (no context_map provided).\n"
+            f"// To replace with verified selectors, run:\n"
+            f"//   browser_navigate('{app_url}') → browser_snapshot() → pass result as context_map\n"
+        )
+        new_locators = snapshot_hint + new_locators
     new_page_object = _gen_page_object(
         page_class, kebab, camel, gherkin, healing_strategy,
         enable_visual_regression, enable_timing_healing)
@@ -1372,22 +1990,23 @@ def _gen_page_object(page_class, kebab, camel, gherkin, healing_strategy,
     stubs     = _build_method_stubs(camel, steps)
     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 ""
-    vi_field  = "private readonly visual: VisualIntentChecker;" if enable_visual_regression else ""
-    th_field  = "private readonly timing: TimingHealer;" if enable_timing_healing else ""
-    vi_init   = "this.visual = new VisualIntentChecker(this.page, fixture().logger, this.repo);" if enable_visual_regression else ""
-    th_init   = "this.timing = new TimingHealer(this.page, fixture().logger, this.repo);" 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";
+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}
-import {{ EnvironmentManager }} from "@helper/environment/environmentManager.util";
 
 /**
  * {page_class}Page — Three-Layer Self-Healing Page Object
@@ -1405,25 +2024,14 @@ import {{ EnvironmentManager }} from "@helper/environment/environmentManager.uti
  *
  * RULE: Never call page.click / page.fill / page.locator directly.
  */
-export default class {page_class}Page {{
-  private readonly page:   Page;
-  private readonly healer: LocatorHealer;
-  private readonly repo:   LocatorRepository;
-  private readonly loc  = {page_class}Locators;
-  private readonly env:    EnvironmentManager;
-  {vi_field}
-  {th_field}
-
-  constructor(page?: Page) {{
-    this.page   = page ?? fixture().page;
-    this.env    = new EnvironmentManager();
-    this.repo   = fixture().locatorRepository ?? new LocatorRepository();
-    this.healer = new LocatorHealer(this.page, fixture().logger, this.repo);
-    {vi_init}
-    {th_init}
-    Object.entries(this.loc).forEach(([key, val]) =>
-      this.repo.register(key, val.selector, val.intent));
-  }}
+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}")}}`;
@@ -1539,71 +2147,326 @@ def _build_method_stubs(camel, steps):
     return "\n\n".join(stubs)
 
 
+def _step_text_to_method_name(text: str) -> str:
+    """Derive a camelCase page-method name from a Gherkin step text."""
+    lower = text.lower()
+    is_assertion = any(kw in lower for kw in (
+        "should", "must", "is displayed", "are displayed",
+        "is shown", "are shown", "should see", "should be",
+        "should have", "is visible", "are visible", "is empty",
+        "is present", "contains", "count", "equal",
+    ))
+    is_nav  = any(kw in lower for kw in (
+        "navigates to", "navigate to", "is on the", "visits",
+        "goes to", "opens", "on the page",
+    ))
+    is_click = any(kw in lower for kw in (
+        "clicks", "click", "taps", "tap", "presses", "press",
+        "selects", "select", "chooses", "choose",
+    ))
+    is_fill = any(kw in lower for kw in (
+        "enters", "enter", "fills", "fill", "types", "type",
+        "inputs", "input", "sets", "set",
+    ))
+    is_given = any(kw in lower for kw in (
+        "has", "have", "with", "contains", "there is", "there are", "exists",
+    ))
+    clean = re.sub(r'\{[^}]+\}', '', text)
+    clean = re.sub(r'"[^"]*"', '', clean)
+    clean = re.sub(r"'[^']*'", '', clean)
+    stops = {
+        'a', 'an', 'the', 'is', 'are', 'has', 'have', 'be', 'been',
+        'to', 'of', 'on', 'in', 'at', 'for', 'by', 'with', 'and',
+        'or', 'it', 'its', 'that', 'this', 'their', 'from', 'as',
+        'user', 'page', 'screen', 'should', 'will', 'can',
+        'then', 'when', 'given', 'but', 'after', 'before',
+    }
+    tokens = [t for t in re.findall(r"[a-zA-Z]+", clean) if t.lower() not in stops][:4]
+    if not tokens:
+        tokens = re.findall(r"[a-zA-Z]+", clean)[:2] or ["action"]
+    body = "".join(t.capitalize() for t in tokens)
+    if is_assertion:
+        return f"verify{body}"
+    if is_nav:
+        return f"navigateTo{body}" if body else "navigate"
+    if is_click:
+        return f"click{body}"
+    if is_fill:
+        return f"enter{body}"
+    if is_given:
+        return f"setup{body}" if body else "setup"
+    return f"action{body}" if body else "performAction"
+
+
+def _step_text_to_cucumber_pattern(text: str) -> str:
+    """Convert step text to a Cucumber expression string (no raw regex)."""
+    pattern = re.sub(r'"[^"]*"', '{string}', text)
+    pattern = re.sub(r'\b\d+\.\d+\b', '{float}', pattern)
+    pattern = re.sub(r'\b\d+\b', '{int}', pattern)
+    return pattern
+
+
+def _build_step_callback(kw, text, method_call, camel, page_class):
+    """Build one Cucumber step definition block using Cucumber expressions."""
+    pattern    = _step_text_to_cucumber_pattern(text)
+    param_types = re.findall(r'\{(string|int|float|word)\}', pattern)
+    if param_types:
+        params   = ", ".join(
+            f"p{i}: {'string' if t == 'string' else 'number'}"
+            for i, t in enumerate(param_types)
+        )
+        fn_sig   = f"async function ({params}): Promise<void>"
+        if "()" in method_call:
+            arg_list   = ", ".join(f"p{i}" for i in range(len(param_types)))
+            actual_call = method_call.replace("()", f"({arg_list})")
+        else:
+            actual_call = method_call
+    else:
+        fn_sig      = "async function (): Promise<void>"
+        actual_call = method_call
+    return (
+        f"{kw}(\n"
+        f"  '{pattern}',\n"
+        f"  {fn_sig} {{\n"
+        f"    if (!{camel}Page) {{ {camel}Page = new {page_class}Page(); }}\n"
+        f"    await {actual_call};\n"
+        f"  }},\n"
+        f");\n"
+    )
+
+
 def _gen_step_defs(page_class, kebab, camel, all_steps, auth_hook):
+    """Generate a complete *.steps.ts for EVERY step in the feature.
+
+    Previous behaviour silently dropped any step whose text didn't match one of
+    14 hardcoded keyword phrases, leaving the file with only the two SSO Given
+    stubs.  New behaviour:
+    - Extended mappings cover common e-commerce/SaaS patterns.
+    - Any step not matched gets a derived method name and typed stub.
+    - All patterns use Cucumber expression strings (not raw /^...$/ regex) to
+      avoid the paren-balance validation errors in write_helix_files.
+    """
     bg = ""
     if auth_hook == "microsoft-sso":
-        bg = f'''
-Given(
-  /^user logs in with Microsoft SSO as "(.+)"$/,
-  async function (userType: string): Promise<void> {{
-    fixture().logger.info(`SSO login as ${{userType}}`);
-  }},
-);
-Given(
-  /^user of type "(.+)" is ready to login$/,
-  async function (userType: string): Promise<void> {{
-    fixture().logger.info(`Preparing login for ${{userType}}`);
-  }},
-);
-'''
-    mappings = [
-        (["navigates to", "is on the"],             f"{camel}Page.navigate()"),
-        (["submits the form", "clicks submit"],       f"{camel}Page.submitForm()"),
-        (["confirms the action"],                     f"{camel}Page.confirmAction()"),
-        (["clicks cancel", "clicks close"],           f"{camel}Page.clickCancel()"),
-        (["clicks save"],                             f"{camel}Page.clickSave()"),
-        (["refreshes the page"],                      f"{camel}Page.refreshPage()"),
-        (["selects a valid file", "uploads a valid"], f"{camel}Page.uploadFile(Buffer.alloc(5*1024*1024),'test.jpg','image/jpeg')"),
-        (["exceeds the maximum", "oversized"],        f"{camel}Page.uploadFile(Buffer.alloc(5*1024*1024+1),'over.jpg','image/jpeg')"),
-        (["success toast", "success notification"],   f"{camel}Page.verifySuccessToast()"),
-        (["error toast", "error notification"],       f"{camel}Page.verifyErrorToast()"),
-        (["validation error"],                        f"{camel}Page.verifyValidationErrors()"),
-        (["operation completes", "updated state"],    f"{camel}Page.verifySuccessState()"),
-        (["still be visible", "persists"],            f"{camel}Page.verifyStatePersisted()"),
-        (["initials", "fallback avatar"],             f"{camel}Page.verifyInitialsAvatar()"),
+        bg = (
+            "\nGiven(\n"
+            "  'user logs in with Microsoft SSO as {string}',\n"
+            "  async function (userType: string): Promise<void> {\n"
+            f"    if (!{camel}Page) {{ {camel}Page = new {page_class}Page(); }}\n"
+            f"    fixture().logger.info(`SSO login as ${{userType}}`);\n"
+            "  },\n"
+            ");\n"
+            "Given(\n"
+            "  'user of type {string} is ready to login',\n"
+            "  async function (userType: string): Promise<void> {\n"
+            f"    if (!{camel}Page) {{ {camel}Page = new {page_class}Page(); }}\n"
+            f"    fixture().logger.info(`Preparing login for ${{userType}}`);\n"
+            "  },\n"
+            ");\n"
+        )
+
+    mappings: list = [
+        # navigation
+        (["navigates to", "is on the", "navigate to", "visits the",
+          "goes to", "opens the", "on the page", "on the site"],
+         f"{camel}Page.navigate()"),
+        # cart setup
+        (["has items in", "has item in", "items in the cart",
+          "item in the cart", "product in the cart",
+          "item in their cart", "items in their cart"],
+         f"{camel}Page.setupCartWithItems()"),
+        # add to cart
+        (["adds the item", "add the item", "adds item", "add item",
+          "clicks add to cart", "click add to cart",
+          "adds a product", "add a product",
+          "adds to cart", "add to cart"],
+         f"{camel}Page.addItemToCart()"),
+        # remove from cart
+        (["remove button", "clicks the remove", "click the remove",
+          "clicks remove", "click remove",
+          "removes the item", "remove the item",
+          "removes item", "remove item",
+          "removes the product", "remove the product"],
+         f"{camel}Page.clickRemoveButton()"),
+        # verify removed
+        (["item is removed", "item should be removed",
+          "item no longer", "product is removed",
+          "product should be removed", "product no longer"],
+         f"{camel}Page.verifyItemRemoved()"),
+        # cart empty
+        (["cart is empty", "cart should be empty",
+          "empty cart", "no items in the cart"],
+         f"{camel}Page.verifyCartEmpty()"),
+        # cart count / badge
+        (["cart count", "cart badge", "item count",
+          "number of items", "quantity in cart",
+          "shopping cart count"],
+         f"{camel}Page.verifyCartCount()"),
+        # cart total
+        (["cart total", "total price", "cart subtotal",
+          "subtotal", "order total"],
+         f"{camel}Page.verifyCartTotal()"),
+        # product display
+        (["product page", "product detail", "product listing",
+          "product is visible", "products are displayed",
+          "products are listed", "product list"],
+         f"{camel}Page.verifyProductsDisplayed()"),
+        # click product
+        (["clicks on the product", "click on the product",
+          "clicks the product", "click the product",
+          "selects the product", "select the product"],
+         f"{camel}Page.clickProduct()"),
+        # product info
+        (["product name", "product title", "product description",
+          "product price", "product detail is"],
+         f"{camel}Page.verifyProductDetails()"),
+        # checkout
+        (["proceeds to checkout", "proceed to checkout",
+          "clicks checkout", "click checkout"],
+         f"{camel}Page.proceedToCheckout()"),
+        # order confirmation
+        (["order is placed", "order placed", "order confirmed",
+          "order confirmation", "purchase complete"],
+         f"{camel}Page.verifyOrderConfirmation()"),
+        # form fill
+        (["fills in", "fill in", "fills out", "fill out",
+          "enters details", "completes the form"],
+         f"{camel}Page.fillForm()"),
+        # submit
+        (["submits the form", "submit the form",
+          "clicks submit", "click submit"],
+         f"{camel}Page.submitForm()"),
+        # confirm
+        (["confirms the action", "confirm the action",
+          "clicks confirm", "click confirm"],
+         f"{camel}Page.confirmAction()"),
+        # cancel / close
+        (["clicks cancel", "click cancel",
+          "clicks close", "click close"],
+         f"{camel}Page.clickCancel()"),
+        # save
+        (["clicks save", "click save"],
+         f"{camel}Page.clickSave()"),
+        # text input
+        (["enters", "enter", "types", "type", "fills", "fill",
+          "inputs", "input"],
+         f"{camel}Page.fillPrimaryInput()"),
+        # file upload
+        (["selects a valid file", "uploads a valid file",
+          "valid file", "valid image"],
+         f"{camel}Page.uploadFile(Buffer.alloc(5*1024*1024),'test.jpg','image/jpeg')"),
+        (["exceeds the maximum", "oversized file", "file too large"],
+         f"{camel}Page.uploadFile(Buffer.alloc(5*1024*1024+1),'over.jpg','image/jpeg')"),
+        # success
+        (["success toast", "success notification",
+          "success message", "successfully"],
+         f"{camel}Page.verifySuccessToast()"),
+        # error
+        (["error toast", "error notification",
+          "error message is displayed", "error is displayed"],
+         f"{camel}Page.verifyErrorToast()"),
+        # validation
+        (["validation error", "validation message",
+          "field error", "required field"],
+         f"{camel}Page.verifyValidationErrors()"),
+        # success state
+        (["operation completes", "updated state",
+          "action is complete", "successfully updated",
+          "successfully deleted"],
+         f"{camel}Page.verifySuccessState()"),
+        # persisted
+        (["still be visible", "persists", "is still",
+          "remains", "after reload", "after refresh"],
+         f"{camel}Page.verifyStatePersisted()"),
+        # reload
+        (["refreshes the page", "refresh the page",
+          "reloads the page", "reload the page"],
+         f"{camel}Page.refreshPage()"),
+        # generic display check
+        (["is displayed", "are displayed", "is shown",
+          "are shown", "is visible", "are visible",
+          "should see", "should display"],
+         f"{camel}Page.verifySuccessState()"),
+        # avatar
+        (["initials", "fallback avatar", "avatar"],
+         f"{camel}Page.verifyInitialsAvatar()"),
+        # modal
+        (["modal", "dialog", "popup", "overlay"],
+         f"{camel}Page.verifyModalVisible()"),
+        # sort
+        (["sorted", "sort order", "in order"],
+         f"{camel}Page.verifySortOrder()"),
+        # filter
+        (["filter", "filtered", "filters"],
+         f"{camel}Page.applyFilter()"),
+        # search
+        (["search", "searches"],
+         f"{camel}Page.search()"),
     ]
-    lines, seen = [], set()
+
+    blocks: list = []
+    seen_patterns: set = set()
+    unmapped_steps: list = []
+
     for step in all_steps:
         m = re.match(r"^(Given|When|Then|And|But)\s+", step)
-        if not m: continue
-        kw, text = m.group(1), step[len(m.group(0)):]
-        norm = re.sub(r"\s+", " ", text.lower())
-        if norm in seen: continue
-        seen.add(norm)
+        if not m:
+            continue
+        kw   = m.group(1)
+        text = step[len(m.group(0)):]
+        norm = re.sub(r"\s+", " ", text.lower().strip())
+        if norm in seen_patterns:
+            continue
+        seen_patterns.add(norm)
+
         lower = step.lower()
-        method = next((mth for kws, mth in mappings if any(k in lower for k in kws)), None)
-        if not method: continue
-        pat = re.sub(r'"[^"]+"', '(.+)', re.escape(text)).replace(r"\ ", " ")
-        lines.append(f'''{kw}(
-  /^{pat}$/,
-  async function (): Promise<void> {{
-    await {method};
-  }},
-);
-''')
-    return f'''import {{ Given, When, Then }} from "@cucumber/cucumber";
-import {{ expect }} from "@playwright/test";
-import {{ fixture }} from "@hooks/pageFixture";
-import {page_class}Page from "@pages/{kebab}/{kebab}.page";
+        method_call = next(
+            (mth for kws, mth in mappings if any(k in lower for k in kws)),
+            None,
+        )
 
-/**
- * Step Definitions: {page_class}
- * HealingDashboard: http://localhost:7890 — review pending suggestions.
- */
-let {camel}Page: {page_class}Page;
-{bg}
-{"".join(lines)}
-'''
+        if method_call:
+            blocks.append(
+                _build_step_callback(kw, text, method_call, camel, page_class)
+            )
+        else:
+            method_name = _step_text_to_method_name(text)
+            unmapped_steps.append((kw, text, method_name))
+            blocks.append(
+                _build_step_callback(
+                    kw, text, f"{camel}Page.{method_name}()", camel, page_class,
+                )
+            )
+
+    unmapped_comment = ""
+    if unmapped_steps:
+        lines_u = [
+            f" *   {kw}: {text}  →  {camel}Page.{mn}()"
+            for kw, text, mn in unmapped_steps
+        ]
+        unmapped_comment = (
+            "\n/**\n"
+            " * Derived step implementations — add these methods to the page object:\n"
+            + "\n".join(lines_u) + "\n"
+            " * (auto-generated by qa-playwright-generator)\n"
+            " */\n"
+        )
+
+    return (
+        f'import {{ Given, When, Then }} from "@cucumber/cucumber";\n'
+        f'import {{ expect }} from "@playwright/test";\n'
+        f'import {{ fixture }} from "@hooks/pageFixture";\n'
+        f'import {page_class}Page from "@pages/{kebab}.page";\n'
+        f'\n'
+        f'/**\n'
+        f' * Step Definitions: {page_class}\n'
+        f' * HealingDashboard: http://localhost:7890 — review pending suggestions.\n'
+        f' */\n'
+        f'let {camel}Page: {page_class}Page;\n'
+        f'{bg}\n'
+        f'{unmapped_comment}'
+        + "".join(blocks)
+    )
 
 
 def _gen_feature_file(gherkin: str, kebab: str, page_class: str) -> str: