nat-engine 1__py3-none-any.whl

mannf/core/browser/ingestor_bridge.py

@@ -0,0 +1,371 @@
+# 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.
+
+"""Ingestor Bridge — converts IngestResult artifacts into scenario task dicts.
+
+Bridges any :class:`~mannf.product.ingestors.models.IngestResult` produced by
+an ingestor plugin (HAR, Postman, cURL, Playwright, etc.) into the same
+``{"url": ..., "steps": [...], "metadata": {...}}`` shape that
+:class:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator` and the
+Phase 3 dashboard discovery flow expect.
+
+Usage::
+
+    from mannf.product.ingestors import HARIngestor, IngestorSource
+    from mannf.core.browser.ingestor_bridge import IngestorBridge
+
+    source = IngestorSource(format="har", path="/path/to/recording.har")
+    result = await HARIngestor().ingest(source, config={})
+
+    bridge = IngestorBridge(base_url="https://example.com")
+    scenarios = bridge.convert(result)
+    # scenarios matches ScenarioConfigGenerator.generate_all() output shape
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import urljoin, urlparse
+
+from mannf.product.ingestors.models import IngestedTestCase, IngestResult
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Action mapping: ingestor step actions → browser actions
+# ---------------------------------------------------------------------------
+
+# Maps ingestor-level step action names to FunctionalTestOrchestrator actions.
+_ACTION_MAP: dict[str, str] = {
+    # Browser-level actions (already in the right shape)
+    "navigate": "navigate",
+    "goto": "navigate",
+    "fill": "fill",
+    "type": "fill",
+    "click": "click",
+    "submit": "click",
+    "check": "click",
+    "uncheck": "click",
+    "select": "fill",
+    # HTTP-level actions from API ingestors — mapped to navigate for GET, fill
+    # for POST bodies (best-effort)
+    "send_request": "navigate",
+    "get": "navigate",
+    "post": "navigate",
+    "put": "navigate",
+    "delete": "navigate",
+    "patch": "navigate",
+    # Assertion steps — kept as-is so the orchestrator can handle them
+    "assert_status": "assert",
+    "assert_text": "assert",
+    "assert": "assert",
+    "wait": "wait",
+    "screenshot": "screenshot",
+}
+
+# Selector/field patterns that indicate an authentication step
+_AUTH_SELECTOR_PATTERNS: tuple[str, ...] = (
+    "password", "passwd", "pass", "secret", "pin",
+    "token", "api_key", "apikey",
+)
+
+# Selector/field patterns that indicate a username/email auth step
+_AUTH_USER_PATTERNS: tuple[str, ...] = (
+    "email", "username", "user", "login", "signin",
+)
+
+# URL path patterns that indicate an auth/login navigation step
+_AUTH_URL_PATTERNS: tuple[str, ...] = (
+    "/login", "/signin", "/auth", "/oauth", "/sso",
+    "/signup", "/register", "/logout",
+)
+
+
+def _map_action(action: str) -> str:
+    """Return the orchestrator-compatible action name for *action*."""
+    return _ACTION_MAP.get(action.lower(), action)
+
+
+def _resolve_url(step: dict[str, Any], base_url: str) -> str:
+    """Extract a URL from a step dict, falling back to *base_url*."""
+    for key in ("url", "selector", "href", "location", "path"):
+        value = step.get(key, "")
+        if isinstance(value, str) and value.strip():
+            # Absolute URL
+            parsed = urlparse(value)
+            if parsed.scheme in ("http", "https"):
+                return value
+            # Relative path — resolve against base_url
+            if value.startswith("/"):
+                return urljoin(base_url.rstrip("/") + "/", value.lstrip("/"))
+    return base_url
+
+
+def _is_auth_selector(selector: str) -> bool:
+    """Return ``True`` when *selector* looks like an authentication field."""
+    lower = selector.lower()
+    return any(pat in lower for pat in _AUTH_SELECTOR_PATTERNS)
+
+
+def _is_auth_user_selector(selector: str) -> bool:
+    """Return ``True`` when *selector* looks like a username/email field."""
+    lower = selector.lower()
+    return any(pat in lower for pat in _AUTH_USER_PATTERNS)
+
+
+def _is_auth_url(url: str) -> bool:
+    """Return ``True`` when *url* path indicates an auth page."""
+    lower = url.lower()
+    return any(pat in lower for pat in _AUTH_URL_PATTERNS)
+
+
+def _extract_nav_flow(steps: list[dict[str, Any]]) -> list[str]:
+    """Return the ordered list of URLs visited in *steps*."""
+    urls: list[str] = []
+    for step in steps:
+        if step.get("action") == "navigate":
+            url = step.get("url") or step.get("selector", "")
+            if url and url not in urls:
+                urls.append(url)
+    return urls
+
+
+def _extract_auth_steps(steps: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return steps that look like authentication interactions.
+
+    Includes:
+    * Navigate steps to auth URLs
+    * Fill steps targeting password / email / username fields
+    """
+    auth: list[dict[str, Any]] = []
+    for step in steps:
+        action = step.get("action", "")
+        if action == "navigate":
+            url = step.get("url") or step.get("selector", "")
+            if url and _is_auth_url(str(url)):
+                auth.append(step)
+        elif action == "fill":
+            selector = str(step.get("selector", ""))
+            if _is_auth_selector(selector) or _is_auth_user_selector(selector):
+                auth.append(step)
+    return auth
+
+
+def _extract_assertion_steps(steps: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return steps that are assertions (action == 'assert' or 'assert_*')."""
+    return [
+        step for step in steps
+        if str(step.get("action", "")).startswith("assert")
+    ]
+
+
+def _convert_step(step: dict[str, Any], base_url: str) -> dict[str, Any]:
+    """Normalise a single ingestor step into a browser-action step dict."""
+    if not isinstance(step, dict):
+        return {"action": "navigate", "selector": base_url}
+
+    action = step.get("action", step.get("type", "navigate"))
+    mapped = _map_action(str(action))
+
+    converted: dict[str, Any] = {"action": mapped}
+
+    if mapped == "navigate":
+        url = _resolve_url(step, base_url)
+        converted["selector"] = url
+        converted["url"] = url
+    elif mapped == "fill":
+        converted["selector"] = step.get(
+            "selector", step.get("element", step.get("target", ""))
+        )
+        converted["value"] = str(
+            step.get("value", step.get("text", step.get("data", "")))
+        )
+    elif mapped == "click":
+        converted["selector"] = step.get(
+            "selector", step.get("element", step.get("target", ""))
+        )
+    else:
+        # Pass through unknown/assertion/wait steps
+        converted.update({k: v for k, v in step.items() if k != "action"})
+
+    return converted
+
+
+# ---------------------------------------------------------------------------
+# IngestorBridge
+# ---------------------------------------------------------------------------
+
+
+class IngestorBridge:
+    """Converts an :class:`IngestResult` into a list of scenario task dicts.
+
+    Parameters
+    ----------
+    base_url:
+        Fallback URL used when a step doesn't provide an explicit URL.
+    source_tag:
+        Label embedded in ``metadata.source_ingestor`` to identify the origin.
+    """
+
+    def __init__(self, base_url: str = "", source_tag: str = "ingestor") -> None:
+        self._base_url = base_url
+        self._source_tag = source_tag
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def convert(self, result: IngestResult) -> list[dict[str, Any]]:
+        """Convert *result* into a list of scenario task dicts.
+
+        Parameters
+        ----------
+        result:
+            An :class:`IngestResult` from any ingestor plugin.
+
+        Returns
+        -------
+        list[dict]
+            Scenario dicts matching
+            ``{"url": ..., "steps": [...], "metadata": {...}}``.
+        """
+        if not result.success and not result.test_cases:
+            logger.warning(
+                "IngestorBridge: result from %r has no test cases (success=%s, errors=%s)",
+                result.source.format,
+                result.success,
+                result.errors,
+            )
+
+        scenarios: list[dict[str, Any]] = []
+
+        # Convert test_cases → scenarios
+        for tc in result.test_cases:
+            scenario = self._test_case_to_scenario(tc, result)
+            if scenario:
+                scenarios.append(scenario)
+
+        # If no test cases, generate one scenario per endpoint (navigate-only)
+        if not scenarios:
+            for ep in result.endpoints:
+                scenario = self._endpoint_to_scenario(ep, result)
+                if scenario:
+                    scenarios.append(scenario)
+
+        logger.debug(
+            "IngestorBridge: converted %d test_cases + %d endpoints → %d scenarios",
+            len(result.test_cases),
+            len(result.endpoints),
+            len(scenarios),
+        )
+        return scenarios
+
+    # ------------------------------------------------------------------
+    # Internal converters
+    # ------------------------------------------------------------------
+
+    def _test_case_to_scenario(
+        self, tc: IngestedTestCase, result: IngestResult
+    ) -> dict[str, Any] | None:
+        """Convert a single :class:`IngestedTestCase` to a scenario dict."""
+        # Determine the URL from the first navigate-type step or base_url
+        url = self._base_url
+        steps: list[dict[str, Any]] = []
+
+        for raw_step in tc.steps:
+            converted = _convert_step(raw_step, self._base_url)
+            if converted["action"] in ("navigate", "goto") and url == self._base_url:
+                url = converted.get("url", converted.get("selector", self._base_url))
+            steps.append(converted)
+
+        if not steps and not url:
+            return None
+
+        # Enrich metadata with nav flow, auth steps, and assertions
+        nav_flow = _extract_nav_flow(steps)
+        auth_steps = _extract_auth_steps(steps)
+        assertion_steps = _extract_assertion_steps(steps)
+        has_auth = bool(auth_steps)
+
+        return {
+            "url": url,
+            "steps": steps,
+            "metadata": {
+                "scenario_type": self._infer_scenario_type(tc),
+                "source_page": url,
+                "source_form_action": "",
+                "description": tc.description or tc.name,
+                "generator": "ingestor",
+                "source_ingestor": self._source_tag or result.source.format,
+                "source_ref": tc.source_ref,
+                "priority": tc.priority,
+                "tags": list(tc.tags),
+                # Enriched fields
+                "nav_flow": nav_flow,
+                "has_auth": has_auth,
+                "auth_steps": auth_steps,
+                "assertions": assertion_steps,
+                **tc.metadata,
+            },
+        }
+
+    def _endpoint_to_scenario(
+        self, ep: Any, result: IngestResult
+    ) -> dict[str, Any] | None:
+        """Create a minimal navigate scenario from an :class:`IngestedEndpoint`."""
+        # Build URL from endpoint path + base_url
+        path = getattr(ep, "path", "") or ""
+        if urlparse(path).scheme in ("http", "https"):
+            url = path
+        else:
+            url = urljoin(self._base_url.rstrip("/") + "/", path.lstrip("/"))
+
+        if not url:
+            return None
+
+        method = getattr(ep, "method", "GET").upper()
+        steps: list[dict[str, Any]] = [{"action": "navigate", "selector": url, "url": url}]
+
+        return {
+            "url": url,
+            "steps": steps,
+            "metadata": {
+                "scenario_type": "api_endpoint",
+                "source_page": url,
+                "source_form_action": path,
+                "description": getattr(ep, "summary", "") or f"{method} {path}",
+                "generator": "ingestor",
+                "source_ingestor": self._source_tag or result.source.format,
+                "http_method": method,
+                "tags": list(getattr(ep, "tags", [])),
+            },
+        }
+
+    @staticmethod
+    def _infer_scenario_type(tc: IngestedTestCase) -> str:
+        """Heuristically determine a scenario_type label from a test case."""
+        tags_lower = {t.lower() for t in tc.tags}
+        name_lower = tc.name.lower()
+        desc_lower = tc.description.lower()
+
+        if any(kw in tags_lower for kw in ("negative", "edge", "error", "invalid")):
+            return "negative"
+        if any(kw in tags_lower for kw in ("happy", "smoke", "positive", "sunny")):
+            return "happy_path"
+        if any(kw in tags_lower for kw in ("boundary", "limit", "min", "max")):
+            return "boundary"
+        if any(kw in tags_lower for kw in ("exploratory", "flow", "journey")):
+            return "flow"
+
+        # Fall back to name/description heuristics
+        for kw in ("negative", "invalid", "error", "fail", "reject"):
+            if kw in name_lower or kw in desc_lower:
+                return "negative"
+        for kw in ("happy", "success", "valid", "positive"):
+            if kw in name_lower or kw in desc_lower:
+                return "happy_path"
+
+        return "exploratory"

mannf/core/browser/performance_metrics.py

@@ -0,0 +1,217 @@
+# 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.
+
+"""PerformanceMetrics – Web Vitals evaluation engine.
+
+Evaluates raw performance metric dictionaries (e.g. collected from a browser
+Performance API or provided programmatically) against Google Core Web Vitals
+thresholds and produces a :class:`PerformanceResult`.
+
+**No browser runtime is required** — all evaluation operates on numeric
+dictionaries passed by callers.
+
+Default thresholds (Google Core Web Vitals)
+-------------------------------------------
+* ``LCP``            — Largest Contentful Paint      good ≤ 2500 ms  poor > 4000 ms
+* ``FCP``            — First Contentful Paint         good ≤ 1800 ms  poor > 3000 ms
+* ``TTI``            — Time to Interactive            good ≤ 3800 ms  poor > 7300 ms
+* ``CLS``            — Cumulative Layout Shift        good ≤ 0.1      poor > 0.25 (unitless)
+* ``TBT``            — Total Blocking Time            good ≤ 200 ms   poor > 600 ms
+* ``page_load_time`` — Total page load time           good ≤ 3000 ms  poor > 6000 ms
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+
+# ---------------------------------------------------------------------------
+# Default thresholds
+# ---------------------------------------------------------------------------
+
+#: Mapping of metric name → ``(threshold_good, threshold_poor, unit)``.
+#:
+#: * ``threshold_good`` — maximum value rated "good"
+#: * ``threshold_poor`` — minimum value rated "poor" (anything between the two
+#:   is "needs-improvement")
+#: * ``unit``           — ``"ms"``, ``"s"``, or ``""`` (unitless)
+DEFAULT_THRESHOLDS: dict[str, tuple[float, float, str]] = {
+    "LCP":            (2500.0, 4000.0, "ms"),
+    "FCP":            (1800.0, 3000.0, "ms"),
+    "TTI":            (3800.0, 7300.0, "ms"),
+    "CLS":            (0.1,    0.25,   ""),
+    "TBT":            (200.0,  600.0,  "ms"),
+    "page_load_time": (3000.0, 6000.0, "ms"),
+}
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PerformanceMetric:
+    """A single evaluated performance metric.
+
+    Parameters
+    ----------
+    name:
+        Metric identifier, e.g. ``"LCP"``, ``"FCP"``, ``"page_load_time"``.
+    value:
+        Measured value (milliseconds, or unitless for CLS).
+    unit:
+        ``"ms"``, ``"s"``, or ``""`` for unitless metrics.
+    rating:
+        One of ``"good"``, ``"needs-improvement"``, or ``"poor"``.
+    threshold_good:
+        Maximum value that qualifies as ``"good"``.
+    threshold_poor:
+        Minimum value that qualifies as ``"poor"``.
+    """
+
+    name: str
+    value: float
+    unit: str
+    rating: str
+    threshold_good: float
+    threshold_poor: float
+
+
+@dataclass
+class PerformanceResult:
+    """Aggregated result of a performance evaluation for a single page.
+
+    Parameters
+    ----------
+    url:
+        URL of the page the metrics were collected from.
+    timestamp:
+        ISO 8601 UTC timestamp of when the evaluation was performed.
+    metrics:
+        All evaluated :class:`PerformanceMetric` objects.
+    page_load_time_ms:
+        Total page load time in milliseconds.
+    """
+
+    url: str
+    timestamp: str
+    metrics: list[PerformanceMetric] = field(default_factory=list)
+    page_load_time_ms: float = 0.0
+
+    @property
+    def good_count(self) -> int:
+        """Number of metrics rated ``"good"``."""
+        return sum(1 for m in self.metrics if m.rating == "good")
+
+    @property
+    def poor_count(self) -> int:
+        """Number of metrics rated ``"poor"``."""
+        return sum(1 for m in self.metrics if m.rating == "poor")
+
+    @property
+    def performance_score(self) -> float:
+        """0.0–100.0 performance score based on metric ratings.
+
+        Weights: good = 1.0, needs-improvement = 0.5, poor = 0.0.
+        Returns ``100.0`` when no metrics are present.
+        """
+        if not self.metrics:
+            return 100.0
+        weights = {"good": 1.0, "needs-improvement": 0.5, "poor": 0.0}
+        total = sum(weights.get(m.rating, 0.5) for m in self.metrics)
+        return round((total / len(self.metrics)) * 100.0, 1)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _rate_metric(value: float, threshold_good: float, threshold_poor: float) -> str:
+    """Return the rating string for *value* given the two thresholds."""
+    if value <= threshold_good:
+        return "good"
+    if value > threshold_poor:
+        return "poor"
+    return "needs-improvement"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def evaluate_metrics(
+    raw_metrics: dict[str, float],
+    url: str = "",
+    custom_thresholds: dict[str, tuple[float, float, str]] | None = None,
+) -> PerformanceResult:
+    """Evaluate raw performance metrics against Web Vitals thresholds.
+
+    Parameters
+    ----------
+    raw_metrics:
+        Dict mapping metric names to values, e.g.
+        ``{"LCP": 2100, "FCP": 1500, ...}``.
+    url:
+        The page URL these metrics were collected from.
+    custom_thresholds:
+        Optional overrides for default thresholds.  Any metric name present
+        here will use the supplied ``(good, poor, unit)`` tuple instead of
+        the default.
+
+    Returns
+    -------
+    PerformanceResult
+        Evaluated metrics with ratings and an overall performance score.
+    """
+    timestamp = datetime.now(timezone.utc).isoformat()
+    thresholds = dict(DEFAULT_THRESHOLDS)
+    if custom_thresholds:
+        thresholds.update(custom_thresholds)
+
+    evaluated: list[PerformanceMetric] = []
+    for name, value in raw_metrics.items():
+        if name in thresholds:
+            good, poor, unit = thresholds[name]
+        else:
+            # Unknown metric: treat as unitless with no hard thresholds
+            good, poor, unit = float("inf"), float("inf"), "ms"
+        rating = _rate_metric(value, good, poor)
+        evaluated.append(
+            PerformanceMetric(
+                name=name,
+                value=value,
+                unit=unit,
+                rating=rating,
+                threshold_good=good,
+                threshold_poor=poor,
+            )
+        )
+
+    page_load = raw_metrics.get("page_load_time", 0.0)
+
+    return PerformanceResult(
+        url=url,
+        timestamp=timestamp,
+        metrics=evaluated,
+        page_load_time_ms=page_load,
+    )
+
+
+def get_threshold_violations(result: PerformanceResult) -> list[PerformanceMetric]:
+    """Return metrics from *result* that are rated ``"poor"``.
+
+    Parameters
+    ----------
+    result:
+        A :class:`PerformanceResult` previously returned by
+        :func:`evaluate_metrics`.
+
+    Returns
+    -------
+    list[PerformanceMetric]
+        All metrics whose :attr:`~PerformanceMetric.rating` is ``"poor"``.
+    """
+    return [m for m in result.metrics if m.rating == "poor"]