nat-engine 1__py3-none-any.whl

mannf/core/browser/scenario_generator.py

@@ -0,0 +1,1100 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Scenario Config Generator — Phase 2 of the functional testing pipeline.
+
+Transforms the structured :class:`~mannf.core.browser.discovery_model.DiscoveryModel`
+produced by :class:`~mannf.core.agents.web_crawler_agent.WebCrawlerAgent` (Phase 1)
+into actionable scenario config dicts that match the task shape expected by
+:meth:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator.run`.
+
+Each generated scenario looks like::
+
+    {
+        "url": "https://example.com/login",
+        "steps": [
+            {"action": "fill", "selector": "#email", "value": "test@example.com"},
+            {"action": "fill", "selector": "#password", "value": "TestP@ss123!"},
+            {"action": "click", "selector": "button[type=submit]"},
+        ],
+        "metadata": {
+            "scenario_type": "happy_path",
+            "source_page": "/login",
+            "source_form_action": "/api/auth/login",
+            "description": "Login with valid credentials",
+        },
+    }
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import re
+from collections import deque
+from typing import Any
+
+from mannf.core.browser.discovery_model import (
+    DiscoveredField,
+    DiscoveredForm,
+    DiscoveredPage,
+    DiscoveryModel,
+    InteractiveElement,
+    PageEdge,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants — realistic valid values per field type
+# ---------------------------------------------------------------------------
+
+_TODAY = datetime.date.today().isoformat()
+
+_VALID_VALUES: dict[str, str] = {
+    "email": "test@example.com",
+    "password": "TestP@ss123!",
+    "tel": "+1-555-0100",
+    "url": "https://example.com",
+    "number": "42",
+    "date": _TODAY,
+    "datetime-local": f"{_TODAY}T12:00",
+    "time": "12:00",
+    "color": "#ff5733",
+    "range": "50",
+    "month": _TODAY[:7],
+    "week": f"{datetime.date.today().isocalendar()[0]}-W{datetime.date.today().isocalendar()[1]:02d}",
+    "search": "test query",
+    "checkbox": "true",
+    "radio": "option1",
+    "file": "",
+    "hidden": "",
+    "textarea": "Sample text input for testing purposes.",
+    "select": "",
+    "text": "Sample text",
+}
+
+# Heuristic label/name → value mapping (lower-cased keyword matching)
+_LABEL_HEURISTICS: list[tuple[tuple[str, ...], str]] = [
+    (("first_name", "firstname", "fname", "first name"), "John"),
+    (("last_name", "lastname", "lname", "last name", "surname"), "Doe"),
+    (("full_name", "fullname", "name"), "John Doe"),
+    (("username", "user_name", "user name", "login"), "johndoe"),
+    (("email", "e-mail", "mail"), "test@example.com"),
+    (("password", "pass", "pwd"), "TestP@ss123!"),
+    (("confirm_password", "confirm password", "password_confirm", "retype"), "TestP@ss123!"),
+    (("phone", "tel", "telephone", "mobile", "cell"), "+1-555-0100"),
+    (("address", "street", "addr"), "123 Main St"),
+    (("city", "town"), "Springfield"),
+    (("state", "province", "region"), "IL"),
+    (("zip", "postal", "postcode", "zipcode"), "62701"),
+    (("country",), "US"),
+    (("age",), "30"),
+    (("dob", "birthdate", "birth_date", "date_of_birth"), "1990-01-15"),
+    (("company", "organization", "organisation"), "Acme Corp"),
+    (("title", "job_title", "position"), "Software Engineer"),
+    (("website", "url", "homepage"), "https://example.com"),
+    (("message", "comment", "description", "note", "bio", "about"), "This is a test message."),
+    (("subject",), "Test Subject"),
+    (("quantity", "qty", "amount", "count"), "1"),
+    (("price", "cost"), "9.99"),
+    (("search", "query", "keyword"), "test"),
+]
+
+# Boundary / edge-case values per field type
+_BOUNDARY_VALUES: dict[str, list[str]] = {
+    "text": [
+        "",
+        "a" * 1001,
+        "<script>alert('xss')</script>",
+        "'; DROP TABLE users; --",
+        "\u0000\u0001\u001f",
+        "\U0001F600\U0001F4A5",  # emoji
+        "\u202e\u0041\u202c",    # RTL override
+    ],
+    "email": [
+        "",
+        "notanemail",
+        "double@@domain.com",
+        "nodomain@",
+        "@nodomain.com",
+        "a" * 250 + "@example.com",
+    ],
+    "password": [
+        "",
+        "a",
+        "a" * 1001,
+        " ",
+        "\t\n",
+    ],
+    "number": [
+        "0",
+        "-1",
+        "999999999",
+        "NaN",
+        "",
+        "1.7976931348623157e+308",
+    ],
+    "tel": [
+        "",
+        "abc",
+        "+" + "1" * 30,
+        "0000000000",
+    ],
+    "url": [
+        "",
+        "not-a-url",
+        "javascript:alert(1)",
+        "http://",
+        "ftp://example.com/../../../etc/passwd",
+    ],
+    "date": [
+        "",
+        "9999-12-31",
+        "0000-01-01",
+        "not-a-date",
+        "2000-13-01",
+        "2000-01-32",
+    ],
+    "textarea": [
+        "",
+        "a" * 10001,
+        "<script>alert('xss')</script>",
+        "'; DROP TABLE users; --",
+        "\u202e\u0041\u202c",
+    ],
+    "select": ["", "__invalid_option__"],
+    "checkbox": ["false"],
+    "search": ["", "<script>alert(1)</script>", "' OR '1'='1"],
+}
+
+
+class ScenarioConfigGenerator:
+    """Generate functional test scenario configs from a :class:`DiscoveryModel`.
+
+    Parameters
+    ----------
+    discovery_model:
+        The structured page graph produced by :class:`WebCrawlerAgent`.
+    adaptive_controller:
+        Optional :class:`~mannf.core.prioritization.adaptive_controller.AdaptiveController`
+        instance for belief-guided strategy selection.
+    llm_provider:
+        Optional LLM provider (any object with an async ``generate`` method).
+        When set, LLM prompts are used for richer test data; when ``None`` the
+        generator falls back to heuristic value generation.
+    max_scenarios_per_form:
+        Upper bound on scenarios produced for any single form.
+    max_flow_depth:
+        Maximum number of pages in a generated multi-step flow.
+    include_negative:
+        Whether to include negative / invalid-input scenarios.
+    include_boundary:
+        Whether to include boundary-value scenarios.
+    include_exploratory:
+        Whether to include click-through scenarios for interactive elements.
+    """
+
+    def __init__(
+        self,
+        discovery_model: DiscoveryModel,
+        *,
+        adaptive_controller: Any | None = None,
+        llm_provider: Any | None = None,
+        max_scenarios_per_form: int = 10,
+        max_flow_depth: int = 5,
+        include_negative: bool = True,
+        include_boundary: bool = True,
+        include_exploratory: bool = True,
+        include_security: bool = False,
+        locale: str = "en-US",
+        domain_context: str = "",
+    ) -> None:
+        self._model = discovery_model
+        self._ac = adaptive_controller
+        self._llm = llm_provider
+        self._max_per_form = max_scenarios_per_form
+        self._max_flow_depth = max_flow_depth
+        self._include_negative = include_negative
+        self._include_boundary = include_boundary
+        self._include_exploratory = include_exploratory
+        self._include_security = include_security
+        self._locale = locale
+        self._domain_context = domain_context
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def generate_all(self) -> list[dict[str, Any]]:
+        """Generate all scenario configs from the discovery model.
+
+        Returns
+        -------
+        list[dict]
+            A list of task dicts compatible with
+            :meth:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator.run`.
+        """
+        scenarios: list[dict[str, Any]] = []
+
+        for page in self._model.pages:
+            for form in page.forms:
+                scenarios.extend(self._generate_form_scenarios(page, form))
+            if self._include_exploratory:
+                scenarios.extend(self._generate_interactive_element_scenarios(page))
+
+        scenarios.extend(self._generate_flow_scenarios())
+
+        if self._include_security:
+            from mannf.core.browser.security_scenario_generator import SecurityScenarioGenerator  # noqa: PLC0415
+            sec_gen = SecurityScenarioGenerator(self._model)
+            scenarios.extend(sec_gen.generate())
+
+        return self._rank_by_adaptive_controller(scenarios)
+
+    async def generate_all_async(self) -> list[dict[str, Any]]:
+        """Generate all scenario configs, optionally augmented with LLM suggestions.
+
+        Generates heuristic scenarios first via :meth:`generate_all`, then—when
+        an LLM provider is configured and available—appends additional scenarios
+        produced by the three UI-focused LLM prompts:
+
+        * :meth:`_llm_form_fill` — realistic happy-path field values per form.
+        * :meth:`_llm_negative_path` — negative / edge-case field values per form.
+        * :meth:`_llm_flow_suggestions` — AI-suggested multi-step user journeys.
+
+        LLM calls are best-effort: any failure is logged and the heuristic
+        scenarios are returned unchanged.
+
+        Returns
+        -------
+        list[dict]
+            Heuristic scenarios followed by LLM-generated scenarios (if any).
+        """
+        scenarios: list[dict[str, Any]] = self.generate_all()
+
+        if self._llm is None or not self._llm.is_available():
+            return scenarios
+
+        llm_scenarios: list[dict[str, Any]] = []
+
+        for page in self._model.pages:
+            for form in page.forms:
+                # Happy-path LLM fill
+                try:
+                    fill_results = await self._llm_form_fill(page, form)
+                    if fill_results:
+                        llm_scenarios.extend(
+                            self._convert_llm_form_fill_to_scenarios(
+                                page, form, fill_results
+                            )
+                        )
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("LLM form-fill conversion failed for %s: %s", page.url, exc)
+
+                # Negative-path LLM scenarios
+                try:
+                    neg_results = await self._llm_negative_path(page, form)
+                    if neg_results:
+                        llm_scenarios.extend(
+                            self._convert_llm_negative_to_scenarios(
+                                page, form, neg_results
+                            )
+                        )
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning(
+                        "LLM negative-path conversion failed for %s: %s", page.url, exc
+                    )
+
+        # Flow suggestions (once per model)
+        try:
+            flow_results = await self._llm_flow_suggestions()
+            if flow_results:
+                llm_scenarios.extend(
+                    self._convert_llm_flow_to_scenarios(flow_results)
+                )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("LLM flow-suggestion conversion failed: %s", exc)
+
+        # Security scenarios (LLM-augmented when include_security is set)
+        if self._include_security:
+            from mannf.core.browser.security_scenario_generator import SecurityScenarioGenerator  # noqa: PLC0415
+            sec_gen = SecurityScenarioGenerator(self._model, llm_provider=self._llm)
+            try:
+                sec_scenarios = await sec_gen.generate_async()
+                llm_scenarios.extend(sec_scenarios)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Security scenario generation failed: %s", exc)
+
+        return self._rank_by_adaptive_controller(scenarios + llm_scenarios)
+
+    # ------------------------------------------------------------------
+    # Form scenarios
+    # ------------------------------------------------------------------
+
+    def _generate_form_scenarios(
+        self, page: DiscoveredPage, form: DiscoveredForm
+    ) -> list[dict[str, Any]]:
+        """Generate scenario configs for a single form on a page.
+
+        Produces (up to ``max_scenarios_per_form``):
+
+        1. Happy path — all fields filled with valid data.
+        2. Required-field omission — one variant per required field that skips it.
+        3. Boundary values — edge-case values per field.
+        4. Negative values — invalid format values per field.
+        5. Empty submit — submit the form without filling anything.
+        """
+        scenarios: list[dict[str, Any]] = []
+        fillable = [f for f in form.fields if f.type not in ("hidden", "file")]
+
+        # 1. Happy path
+        scenarios.append(self._happy_path_scenario(page, form, fillable))
+
+        # 2. Required field omission
+        required_fields = [f for f in fillable if f.required]
+        for field in required_fields:
+            if len(scenarios) >= self._max_per_form:
+                break
+            scenarios.append(self._omit_field_scenario(page, form, fillable, field))
+
+        # 3. Boundary values
+        if self._include_boundary:
+            for field in fillable:
+                if len(scenarios) >= self._max_per_form:
+                    break
+                boundary_vals = self._generate_boundary_value(field)
+                for bval in boundary_vals[:2]:  # cap at 2 per field
+                    if len(scenarios) >= self._max_per_form:
+                        break
+                    scenarios.append(
+                        self._boundary_scenario(page, form, fillable, field, bval)
+                    )
+
+        # 4. Negative values
+        if self._include_negative:
+            for field in fillable:
+                if len(scenarios) >= self._max_per_form:
+                    break
+                neg_vals = self._generate_negative_value(field)
+                if neg_vals:
+                    scenarios.append(
+                        self._negative_scenario(page, form, fillable, field, neg_vals[0])
+                    )
+
+        # 5. Empty submit
+        if len(scenarios) < self._max_per_form:
+            scenarios.append(self._empty_submit_scenario(page, form))
+
+        return scenarios[: self._max_per_form]
+
+    def _happy_path_scenario(
+        self,
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        fillable: list[DiscoveredField],
+    ) -> dict[str, Any]:
+        steps = self._navigate_step(page.url)
+        for field in fillable:
+            value = self._generate_valid_value(field)
+            if value:
+                steps.append({"action": "fill", "selector": field.selector, "value": value})
+        steps.append({"action": "click", "selector": form.submit_selector})
+        return self._make_scenario(
+            page=page,
+            form=form,
+            steps=steps,
+            scenario_type="happy_path",
+            description=f"Happy path — fill {form.action or page.url} with valid data",
+        )
+
+    def _omit_field_scenario(
+        self,
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        fillable: list[DiscoveredField],
+        omitted: DiscoveredField,
+    ) -> dict[str, Any]:
+        steps = self._navigate_step(page.url)
+        for field in fillable:
+            if field.selector == omitted.selector:
+                continue
+            value = self._generate_valid_value(field)
+            if value:
+                steps.append({"action": "fill", "selector": field.selector, "value": value})
+        steps.append({"action": "click", "selector": form.submit_selector})
+        label_hint = omitted.label or omitted.name or omitted.selector
+        return self._make_scenario(
+            page=page,
+            form=form,
+            steps=steps,
+            scenario_type="negative",
+            description=f"Required field omission — skip '{label_hint}'",
+        )
+
+    def _boundary_scenario(
+        self,
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        fillable: list[DiscoveredField],
+        target_field: DiscoveredField,
+        boundary_value: str,
+    ) -> dict[str, Any]:
+        steps = self._navigate_step(page.url)
+        for field in fillable:
+            if field.selector == target_field.selector:
+                value = boundary_value
+            else:
+                value = self._generate_valid_value(field)
+            if value:
+                steps.append({"action": "fill", "selector": field.selector, "value": value})
+        steps.append({"action": "click", "selector": form.submit_selector})
+        label_hint = target_field.label or target_field.name or target_field.selector
+        return self._make_scenario(
+            page=page,
+            form=form,
+            steps=steps,
+            scenario_type="boundary",
+            description=(
+                f"Boundary value for '{label_hint}': {boundary_value!r}"
+            ),
+        )
+
+    def _negative_scenario(
+        self,
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        fillable: list[DiscoveredField],
+        target_field: DiscoveredField,
+        negative_value: str,
+    ) -> dict[str, Any]:
+        steps = self._navigate_step(page.url)
+        for field in fillable:
+            if field.selector == target_field.selector:
+                value = negative_value
+            else:
+                value = self._generate_valid_value(field)
+            if value:
+                steps.append({"action": "fill", "selector": field.selector, "value": value})
+        steps.append({"action": "click", "selector": form.submit_selector})
+        label_hint = target_field.label or target_field.name or target_field.selector
+        return self._make_scenario(
+            page=page,
+            form=form,
+            steps=steps,
+            scenario_type="negative",
+            description=f"Negative value for '{label_hint}': {negative_value!r}",
+        )
+
+    def _empty_submit_scenario(
+        self, page: DiscoveredPage, form: DiscoveredForm
+    ) -> dict[str, Any]:
+        steps = self._navigate_step(page.url)
+        steps.append({"action": "click", "selector": form.submit_selector})
+        return self._make_scenario(
+            page=page,
+            form=form,
+            steps=steps,
+            scenario_type="negative",
+            description="Submit empty form without filling any fields",
+        )
+
+    # ------------------------------------------------------------------
+    # Flow scenarios
+    # ------------------------------------------------------------------
+
+    def _generate_flow_scenarios(self) -> list[dict[str, Any]]:
+        """Generate multi-step flow scenarios by traversing the page graph.
+
+        Uses BFS from each discovered page to find paths up to
+        ``max_flow_depth`` hops.  Detects login-like forms (those with a
+        password field) and chains them with subsequent pages.
+        """
+        if not self._model.edges:
+            return []
+
+        # Build adjacency list: from_url → list[(to_url, edge)]
+        adjacency: dict[str, list[tuple[str, PageEdge]]] = {}
+        for edge in self._model.edges:
+            adjacency.setdefault(edge.from_url, []).append((edge.to_url, edge))
+
+        # Index pages by URL for quick lookup
+        page_by_url: dict[str, DiscoveredPage] = {p.url: p for p in self._model.pages}
+
+        # Identify entry pages (pages that have no incoming edges or are the first page)
+        destinations = {e.to_url for e in self._model.edges}
+        entry_pages = [
+            p.url
+            for p in self._model.pages
+            if p.url not in destinations or p.url == self._model.base_url
+        ]
+        if not entry_pages:
+            entry_pages = [self._model.pages[0].url] if self._model.pages else []
+
+        scenarios: list[dict[str, Any]] = []
+
+        for entry in entry_pages:
+            paths = self._bfs_paths(entry, adjacency, self._max_flow_depth)
+            for path in paths:
+                if len(path) < 2:
+                    continue
+                flow_steps: list[dict[str, Any]] = []
+                for url in path:
+                    page = page_by_url.get(url)
+                    if page is None:
+                        flow_steps.append({"action": "navigate", "selector": url})
+                        continue
+                    flow_steps.extend(self._navigate_step(url))
+                    # Fill any login-like (password) form on this page
+                    for form in page.forms:
+                        fillable = [
+                            f for f in form.fields if f.type not in ("hidden", "file")
+                        ]
+                        has_password = any(f.type == "password" for f in fillable)
+                        if has_password or url == path[0]:
+                            for field in fillable:
+                                value = self._generate_valid_value(field)
+                                if value:
+                                    flow_steps.append(
+                                        {
+                                            "action": "fill",
+                                            "selector": field.selector,
+                                            "value": value,
+                                        }
+                                    )
+                            flow_steps.append(
+                                {"action": "click", "selector": form.submit_selector}
+                            )
+                            break  # only interact with the first form per page in a flow
+
+                if flow_steps:
+                    page_titles = [
+                        (page_by_url[u].title if u in page_by_url else u) for u in path
+                    ]
+                    scenarios.append(
+                        {
+                            "url": self._model.base_url,
+                            "steps": flow_steps,
+                            "metadata": {
+                                "scenario_type": "flow",
+                                "source_page": entry,
+                                "source_form_action": "",
+                                "description": (
+                                    f"Multi-step flow: {' → '.join(page_titles)}"
+                                ),
+                            },
+                        }
+                    )
+
+        return scenarios
+
+    def _bfs_paths(
+        self,
+        start: str,
+        adjacency: dict[str, list[tuple[str, PageEdge]]],
+        max_depth: int,
+    ) -> list[list[str]]:
+        """Return all simple paths reachable from *start* via BFS."""
+        paths: list[list[str]] = []
+        queue: deque[list[str]] = deque([[start]])
+        while queue:
+            path = queue.popleft()
+            current = path[-1]
+            neighbours = adjacency.get(current, [])
+            for neighbour_url, _ in neighbours:
+                if neighbour_url in path:
+                    continue  # avoid cycles
+                new_path = path + [neighbour_url]
+                paths.append(new_path)
+                if len(new_path) < max_depth:
+                    queue.append(new_path)
+        return paths
+
+    # ------------------------------------------------------------------
+    # Interactive element scenarios
+    # ------------------------------------------------------------------
+
+    def _generate_interactive_element_scenarios(
+        self, page: DiscoveredPage
+    ) -> list[dict[str, Any]]:
+        """Generate click-through scenarios for non-form interactive elements."""
+        scenarios: list[dict[str, Any]] = []
+        for element in page.interactive_elements:
+            if element.type in ("button", "link"):
+                steps = self._navigate_step(page.url)
+                steps.append({"action": "click", "selector": element.selector})
+                scenarios.append(
+                    {
+                        "url": page.url,
+                        "steps": steps,
+                        "metadata": {
+                            "scenario_type": "exploratory",
+                            "source_page": page.url,
+                            "source_form_action": "",
+                            "description": (
+                                f"Click interactive element: {element.text or element.selector}"
+                            ),
+                        },
+                    }
+                )
+        return scenarios
+
+    # ------------------------------------------------------------------
+    # Value generation helpers
+    # ------------------------------------------------------------------
+
+    def _generate_valid_value(self, field: DiscoveredField) -> str:
+        """Generate a realistic valid value for *field*.
+
+        Priority order:
+        1. Heuristic match on label/name/placeholder.
+        2. Type-specific default value from ``_VALID_VALUES``.
+        3. Generic ``"test"`` fallback.
+        """
+        heuristic = self._infer_field_value_from_label(field)
+        if heuristic:
+            return heuristic
+        return _VALID_VALUES.get(field.type, "test")
+
+    def _generate_boundary_value(self, field: DiscoveredField) -> list[str]:
+        """Generate boundary / edge-case values for *field*.
+
+        Returns a list of strings (may be empty for types without known boundaries).
+        """
+        ftype = field.type
+        # Map some types to their common boundary category
+        if ftype in ("textarea",):
+            return list(_BOUNDARY_VALUES.get("textarea", []))
+        if ftype in ("text", "search") or ftype not in _BOUNDARY_VALUES:
+            return list(_BOUNDARY_VALUES.get("text", []))
+        return list(_BOUNDARY_VALUES.get(ftype, []))
+
+    def _generate_negative_value(self, field: DiscoveredField) -> list[str]:
+        """Generate invalid-format values for *field* based on its type."""
+        ftype = field.type
+        if ftype == "email":
+            return ["notanemail", "double@@host.com", "@nodomain"]
+        if ftype == "password":
+            return ["", "a", " "]
+        if ftype == "url":
+            return ["not-a-url", "javascript:alert(1)", ""]
+        if ftype == "number":
+            return ["abc", "NaN", "--1"]
+        if ftype == "tel":
+            return ["abc", "000", ""]
+        if ftype == "date":
+            return ["not-a-date", "9999-99-99", ""]
+        if ftype in ("text", "textarea", "search"):
+            return [
+                "<script>alert('xss')</script>",
+                "'; DROP TABLE users; --",
+                "\u202e",
+            ]
+        if ftype == "checkbox":
+            return ["notabool"]
+        return []
+
+    def _infer_field_value_from_label(self, field: DiscoveredField) -> str:
+        """Use label/name/placeholder heuristics to infer a contextual value."""
+        # Build a candidate string from available text attributes and split into tokens
+        raw = " ".join(
+            filter(
+                None,
+                [
+                    field.label,
+                    field.name,
+                    field.placeholder,
+                ],
+            )
+        ).lower()
+        candidate = re.sub(r"[\s_\-]+", "_", raw)
+        # Token set for whole-word matching (underscore-delimited)
+        tokens = set(candidate.split("_")) if candidate else set()
+
+        for keywords, value in _LABEL_HEURISTICS:
+            for kw in keywords:
+                normalised_kw = re.sub(r"[\s_\-]+", "_", kw.lower())
+                kw_tokens = set(normalised_kw.split("_"))
+                # Match if the keyword tokens are a subset of the candidate tokens,
+                # or if the full normalised keyword is an exact substring of the candidate
+                # when the keyword is a single token (avoids "name" matching "username").
+                if len(kw_tokens) == 1:
+                    # Single-token keyword: require exact token match
+                    if kw_tokens <= tokens:
+                        return value
+                else:
+                    # Multi-token keyword: require all tokens to be present
+                    if kw_tokens <= tokens:
+                        return value
+
+        # Special case: if the field type already implies an email address
+        if field.type == "email":
+            return "test@example.com"
+        if field.type == "password":
+            return "TestP@ss123!"
+
+        return ""
+
+    # ------------------------------------------------------------------
+    # LLM integration (optional)
+    # ------------------------------------------------------------------
+
+    async def _llm_form_fill(
+        self, page: DiscoveredPage, form: DiscoveredForm, n: int = 1
+    ) -> list[dict[str, Any]] | None:
+        """Call LLM for realistic happy-path fill values.
+
+        Returns parsed list of test case dicts, or ``None`` on failure.
+        """
+        if self._llm is None:
+            return None
+        from mannf.product.llm.prompts import UI_FORM_FILL_PROMPT  # local import
+
+        fields_desc = self._format_fields_description(form.fields)
+        prompt = UI_FORM_FILL_PROMPT.format(
+            n=n,
+            locale=self._locale,
+            domain_context=self._domain_context or "general web application",
+            page_url=page.url,
+            form_action=form.action,
+            form_method=form.method,
+            fields_description=fields_desc,
+        )
+        try:
+            raw = await self._llm.generate(prompt)
+            return json.loads(raw)
+        except Exception as exc:
+            logger.warning("LLM form-fill call failed: %s", exc)
+            return None
+
+    async def _llm_negative_path(
+        self, page: DiscoveredPage, form: DiscoveredForm, n: int = 3
+    ) -> list[dict[str, Any]] | None:
+        """Call LLM for negative/edge-case fill values.
+
+        Returns parsed list of test case dicts, or ``None`` on failure.
+        """
+        if self._llm is None:
+            return None
+        from mannf.product.llm.prompts import UI_NEGATIVE_PATH_PROMPT  # local import
+
+        fields_desc = self._format_fields_description(form.fields)
+        prompt = UI_NEGATIVE_PATH_PROMPT.format(
+            n=n,
+            page_url=page.url,
+            form_action=form.action,
+            form_method=form.method,
+            fields_description=fields_desc,
+        )
+        try:
+            raw = await self._llm.generate(prompt)
+            return json.loads(raw)
+        except Exception as exc:
+            logger.warning("LLM negative-path call failed: %s", exc)
+            return None
+
+    async def _llm_flow_suggestions(self, n: int = 3) -> list[dict[str, Any]] | None:
+        """Call LLM for multi-step flow suggestions.
+
+        Returns parsed list of scenario dicts, or ``None`` on failure.
+        """
+        if self._llm is None:
+            return None
+        from mannf.product.llm.prompts import UI_FLOW_SUGGESTION_PROMPT  # local import
+
+        pages_desc = "\n".join(
+            f"    - {p.url}: {p.title} ({len(p.forms)} forms, {len(p.links)} links)"
+            for p in self._model.pages
+        )
+        edges_desc = "\n".join(
+            f"    - {e.from_url} --[{e.action}:{e.selector}]--> {e.to_url}"
+            for e in self._model.edges
+        )
+        prompt = UI_FLOW_SUGGESTION_PROMPT.format(
+            n=n,
+            base_url=self._model.base_url,
+            pages_description=pages_desc,
+            edges_description=edges_desc,
+        )
+        try:
+            raw = await self._llm.generate(prompt)
+            return json.loads(raw)
+        except Exception as exc:
+            logger.warning("LLM flow-suggestion call failed: %s", exc)
+            return None
+
+    async def _llm_accessibility(
+        self, page: DiscoveredPage, form: DiscoveredForm, n: int = 3
+    ) -> list[dict[str, Any]] | None:
+        """Call LLM for accessibility-focused test cases.
+
+        Returns parsed list of test case dicts, or ``None`` on failure.
+        """
+        if self._llm is None:
+            return None
+        from mannf.product.llm.prompts import UI_ACCESSIBILITY_PROMPT  # local import
+
+        fields_desc = self._format_fields_description(form.fields)
+        prompt = UI_ACCESSIBILITY_PROMPT.format(
+            n=n,
+            page_url=page.url,
+            fields_description=fields_desc,
+        )
+        try:
+            raw = await self._llm.generate(prompt)
+            return json.loads(raw)
+        except Exception as exc:
+            logger.warning("LLM accessibility call failed: %s", exc)
+            return None
+
+    # ------------------------------------------------------------------
+    # LLM response → scenario dict converters
+    # ------------------------------------------------------------------
+
+    def _convert_llm_form_fill_to_scenarios(
+        self,
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        fill_results: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Convert ``_llm_form_fill`` results into standard scenario dicts.
+
+        Parameters
+        ----------
+        page:
+            The page the form lives on.
+        form:
+            The form whose fields were filled.
+        fill_results:
+            List of dicts from the LLM, each with at least an ``"inputs"`` key
+            mapping ``selector → value``.
+
+        Returns
+        -------
+        list[dict]
+            Standard scenario dicts tagged with ``"generator": "llm"``.
+        """
+        scenarios: list[dict[str, Any]] = []
+        for item in fill_results:
+            if not isinstance(item, dict):
+                continue
+            inputs: dict[str, str] = item.get("inputs", {})
+            if not isinstance(inputs, dict):
+                continue
+            description = item.get("description", "LLM-generated happy-path scenario")
+            fill_steps = [
+                {"action": "fill", "selector": selector, "value": str(value)}
+                for selector, value in inputs.items()
+            ]
+            if form.submit_selector:
+                fill_steps.append({"action": "click", "selector": form.submit_selector})
+            steps = self._navigate_step(page.url) + fill_steps
+            scenario = {
+                "url": page.url,
+                "steps": steps,
+                "metadata": {
+                    "scenario_type": "happy_path",
+                    "source_page": page.url,
+                    "source_form_action": form.action,
+                    "description": f"LLM-generated: {description}",
+                    "generator": "llm",
+                },
+            }
+            scenarios.append(scenario)
+        return scenarios
+
+    def _convert_llm_negative_to_scenarios(
+        self,
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        neg_results: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Convert ``_llm_negative_path`` results into standard scenario dicts.
+
+        Parameters
+        ----------
+        page:
+            The page the form lives on.
+        form:
+            The form whose fields are being tested negatively.
+        neg_results:
+            List of dicts from the LLM, each with at least an ``"inputs"`` key.
+
+        Returns
+        -------
+        list[dict]
+            Standard scenario dicts tagged with ``"generator": "llm"``.
+        """
+        scenarios: list[dict[str, Any]] = []
+        for item in neg_results:
+            if not isinstance(item, dict):
+                continue
+            inputs: dict[str, str] = item.get("inputs", {})
+            if not isinstance(inputs, dict):
+                continue
+            description = item.get(
+                "expected_behavior",
+                item.get("description", "LLM-generated negative scenario"),
+            )
+            fill_steps = [
+                {"action": "fill", "selector": selector, "value": str(value)}
+                for selector, value in inputs.items()
+            ]
+            if form.submit_selector:
+                fill_steps.append({"action": "click", "selector": form.submit_selector})
+            steps = self._navigate_step(page.url) + fill_steps
+            scenario = {
+                "url": page.url,
+                "steps": steps,
+                "metadata": {
+                    "scenario_type": "negative",
+                    "source_page": page.url,
+                    "source_form_action": form.action,
+                    "description": f"LLM-generated: {description}",
+                    "generator": "llm",
+                },
+            }
+            scenarios.append(scenario)
+        return scenarios
+
+    def _convert_llm_flow_to_scenarios(
+        self,
+        flow_results: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Convert ``_llm_flow_suggestions`` results into standard scenario dicts.
+
+        Parameters
+        ----------
+        flow_results:
+            List of flow dicts from the LLM, each with ``"name"``, ``"steps"``,
+            ``"description"``, and optional ``"priority"`` keys.
+
+        Returns
+        -------
+        list[dict]
+            Standard scenario dicts tagged with ``"generator": "llm"``.
+        """
+        scenarios: list[dict[str, Any]] = []
+        base_url = self._model.base_url
+        for flow in flow_results:
+            if not isinstance(flow, dict):
+                continue
+            raw_steps: list[dict[str, Any]] = flow.get("steps", [])
+            if not isinstance(raw_steps, list):
+                raw_steps = []
+            # Derive the URL from the first navigate step, or fall back to base_url
+            url = base_url
+            for step in raw_steps:
+                if isinstance(step, dict) and step.get("action") == "navigate":
+                    sel = step.get("selector", "")
+                    if sel:
+                        url = sel if sel.startswith("http") else f"{base_url.rstrip('/')}/{sel.lstrip('/')}"
+                    break
+            description = flow.get("description", flow.get("name", "LLM-generated flow"))
+            scenario = {
+                "url": url,
+                "steps": raw_steps,
+                "metadata": {
+                    "scenario_type": "flow",
+                    "source_page": url,
+                    "source_form_action": "",
+                    "description": f"LLM-generated: {description}",
+                    "generator": "llm",
+                },
+            }
+            scenarios.append(scenario)
+        return scenarios
+
+    # ------------------------------------------------------------------
+    # AdaptiveController ranking
+    # ------------------------------------------------------------------
+
+    def _rank_by_adaptive_controller(
+        self, scenarios: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Sort *scenarios* by descending risk score using the AdaptiveController.
+
+        When no ``adaptive_controller`` is set the input list is returned
+        unchanged.  When one is set, each scenario's target page URL is scored
+        via ``_endpoint_risk()`` and the scenarios are re-ordered so that
+        higher-risk pages appear first.  The computed ``risk_score`` and
+        ``confidence`` values are also stored in each scenario's ``metadata``
+        so downstream consumers can surface them directly.
+
+        Parameters
+        ----------
+        scenarios:
+            List of scenario dicts to rank.
+
+        Returns
+        -------
+        list[dict]
+            Scenarios sorted by descending risk (highest-risk first) when an
+            adaptive controller is available; otherwise the original list.
+        """
+        if self._ac is None or not scenarios:
+            return scenarios
+
+        def _risk(scenario: dict[str, Any]) -> float:
+            target = scenario.get("metadata", {}).get("source_page") or scenario.get("url", "")
+            belief_states = getattr(self._ac, "belief_states", None) or []
+            try:
+                return self._ac._endpoint_risk(target, belief_states)
+            except Exception:  # noqa: BLE001
+                return 0.5
+
+        for scenario in scenarios:
+            risk = _risk(scenario)
+            meta = scenario.setdefault("metadata", {})
+            meta["risk_score"] = round(risk, 4)
+            meta["confidence"] = round(max(0.0, 1.0 - risk * 0.5), 4)
+
+        return sorted(scenarios, key=_risk, reverse=True)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _navigate_step(url: str) -> list[dict[str, Any]]:
+        """Return a navigate step list for the given URL."""
+        return [{"action": "navigate", "selector": url}]
+
+    @staticmethod
+    def _make_scenario(
+        page: DiscoveredPage,
+        form: DiscoveredForm,
+        steps: list[dict[str, Any]],
+        scenario_type: str,
+        description: str,
+    ) -> dict[str, Any]:
+        return {
+            "url": page.url,
+            "steps": steps,
+            "metadata": {
+                "scenario_type": scenario_type,
+                "source_page": page.url,
+                "source_form_action": form.action,
+                "description": description,
+            },
+        }
+
+    @staticmethod
+    def _format_fields_description(fields: list[DiscoveredField]) -> str:
+        lines: list[str] = []
+        for f in fields:
+            lines.append(f"    - selector={f.selector!r}")
+            lines.append(f"      type={f.type!r}")
+            if f.label:
+                lines.append(f"      label={f.label!r}")
+            if f.name:
+                lines.append(f"      name={f.name!r}")
+            lines.append(f"      required={f.required}")
+            if f.placeholder:
+                lines.append(f"      placeholder={f.placeholder!r}")
+            if f.pattern:
+                lines.append(f"      pattern={f.pattern!r}  ← values MUST match this regex")
+        return "\n".join(lines)