nat-engine 1__py3-none-any.whl

mannf/product/integrations/postman_parser.py

@@ -0,0 +1,467 @@
+# 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.
+
+"""Postman Collection v2.1 parser.
+
+Reads a Postman Collection JSON file and auto-generates
+:class:`~mannf.core.testing.models.TestCase` objects covering both positive
+and negative test scenarios.  Discovered endpoints are also registered into a
+provided :class:`~mannf.core.distributed.endpoint.EndpointRegistry`.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse, urlunparse
+
+from mannf.core.distributed.endpoint import Endpoint, EndpointRegistry
+from mannf.core.testing.models import TestCase
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_VAR_RE = re.compile(r"\{\{([^}]+)\}\}")
+
+
+def _resolve_variables(text: str, variables: Dict[str, str]) -> str:
+    """Replace ``{{varName}}`` patterns in *text* with values from *variables*."""
+    if not text:
+        return text
+
+    def _replace(match: re.Match) -> str:  # type: ignore[type-arg]
+        return variables.get(match.group(1), match.group(0))
+
+    return _VAR_RE.sub(_replace, text)
+
+
+def _path_to_endpoint_name(path: str) -> str:
+    """Turn ``/users/:id/orders`` into ``users-id-orders``."""
+    name = re.sub(r"[{}:()]", "", path)
+    name = re.sub(r"[^a-zA-Z0-9]+", "-", name).strip("-")
+    return name or "root"
+
+
+def _extract_base_url_from_collection(
+    collection: Dict[str, Any],
+    variables: Dict[str, str],
+) -> str:
+    """Try to derive a base URL from collection variables or the first request."""
+    # 1. Check collection-level variable named "baseUrl" (common convention)
+    for var in collection.get("variable", []):
+        if var.get("key") == "baseUrl" and var.get("value"):
+            return str(var["value"]).rstrip("/")
+
+    # 2. Look for {{baseUrl}} replacement in variables dict
+    if "baseUrl" in variables:
+        return variables["baseUrl"].rstrip("/")
+
+    # 3. Fall back to extracting scheme+host from the first request's URL
+    first_url = _first_request_url(collection.get("item", []))
+    if first_url:
+        first_url = _resolve_variables(first_url, variables)
+        parsed = urlparse(first_url)
+        if parsed.scheme and parsed.netloc:
+            return urlunparse((parsed.scheme, parsed.netloc, "", "", "", ""))
+
+    return ""
+
+
+def _first_request_url(items: List[Dict[str, Any]]) -> str:
+    """Recursively find the URL string from the first leaf request."""
+    for item in items:
+        if "request" in item:
+            url = item["request"].get("url", "")
+            if isinstance(url, dict):
+                return url.get("raw", "")
+            return str(url)
+        if "item" in item:
+            result = _first_request_url(item["item"])
+            if result:
+                return result
+    return ""
+
+
+def _collect_collection_variables(collection: Dict[str, Any]) -> Dict[str, str]:
+    """Return a dict of collection-level variable definitions."""
+    variables: Dict[str, str] = {}
+    for var in collection.get("variable", []):
+        key = var.get("key") or ""
+        value = var.get("value") or ""
+        if key:
+            variables[key] = str(value)
+    return variables
+
+
+def _build_auth_headers(
+    auth_block: Optional[Dict[str, Any]],
+) -> Dict[str, str]:
+    """Convert a Postman ``auth`` block to HTTP header mappings.
+
+    Supports: bearer, apikey, basic, noauth (and unknown types → empty).
+    """
+    if not auth_block:
+        return {}
+
+    auth_type = auth_block.get("type", "").lower()
+    headers: Dict[str, str] = {}
+
+    if auth_type == "bearer":
+        token = _get_auth_param(auth_block, "bearer", "token") or ""
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+
+    elif auth_type == "apikey":
+        key = _get_auth_param(auth_block, "apikey", "key") or "X-API-Key"
+        value = _get_auth_param(auth_block, "apikey", "value") or ""
+        in_location = (_get_auth_param(auth_block, "apikey", "in") or "header").lower()
+        if in_location == "header" and value:
+            headers[key] = value
+
+    elif auth_type == "basic":
+        username = _get_auth_param(auth_block, "basic", "username") or ""
+        password = _get_auth_param(auth_block, "basic", "password") or ""
+        if username or password:
+            encoded = base64.b64encode(f"{username}:{password}".encode()).decode()
+            headers["Authorization"] = f"Basic {encoded}"
+
+    return headers
+
+
+def _get_auth_param(
+    auth_block: Dict[str, Any],
+    auth_type: str,
+    key: str,
+) -> Optional[str]:
+    """Extract a named parameter value from a Postman auth block."""
+    params = auth_block.get(auth_type, [])
+    if isinstance(params, list):
+        for param in params:
+            if param.get("key") == key:
+                return param.get("value")
+    elif isinstance(params, dict):
+        return params.get(key)
+    return None
+
+
+def _parse_url(
+    url_obj: Any,
+    variables: Dict[str, str],
+) -> Tuple[str, Dict[str, str]]:
+    """Return ``(path, query_params)`` from a Postman URL object or string.
+
+    Postman variables in path segments and query values are resolved.
+    """
+    query_params: Dict[str, str] = {}
+
+    if isinstance(url_obj, str):
+        raw = _resolve_variables(url_obj, variables)
+        parsed = urlparse(raw)
+        path = parsed.path or "/"
+        if parsed.query:
+            for part in parsed.query.split("&"):
+                if "=" in part:
+                    k, _, v = part.partition("=")
+                    query_params[k] = v
+        return path, query_params
+
+    if not isinstance(url_obj, dict):
+        return "/", query_params
+
+    # Build path from segments array (preferred) or "raw"
+    path_segments = url_obj.get("path", [])
+    if path_segments and isinstance(path_segments, list):
+        parts: List[str] = []
+        for seg in path_segments:
+            if isinstance(seg, dict):
+                seg_val = seg.get("value", "") or ""
+            else:
+                seg_val = str(seg)
+            parts.append(_resolve_variables(seg_val, variables))
+        path = "/" + "/".join(parts)
+    else:
+        raw = _resolve_variables(url_obj.get("raw", ""), variables)
+        parsed = urlparse(raw)
+        path = parsed.path or "/"
+
+    # Query parameters
+    for q in url_obj.get("query", []):
+        if q.get("disabled"):
+            continue
+        k = q.get("key", "")
+        v = _resolve_variables(q.get("value", "") or "", variables)
+        if k:
+            query_params[k] = v
+
+    return path, query_params
+
+
+def _parse_body(
+    body_obj: Optional[Dict[str, Any]],
+    variables: Dict[str, str],
+) -> Tuple[Optional[Any], List[str]]:
+    """Return ``(json_body, required_fields)`` from a Postman request body.
+
+    Only ``raw`` mode with a JSON content-type is handled; all other modes
+    return ``(None, [])``.
+    """
+    if not body_obj:
+        return None, []
+
+    mode = body_obj.get("mode", "")
+    if mode != "raw":
+        return None, []
+
+    raw = body_obj.get("raw", "") or ""
+    raw = _resolve_variables(raw, variables)
+    if not raw.strip():
+        return None, []
+
+    try:
+        parsed = json.loads(raw)
+    except (ValueError, json.JSONDecodeError):
+        return None, []
+
+    if not isinstance(parsed, dict):
+        return parsed, []
+
+    # Heuristic: treat all top-level keys as required for negative generation
+    required = list(parsed.keys())
+    return parsed, required
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+class PostmanParser:
+    """Parse a Postman Collection v2.1 file and generate :class:`TestCase` objects.
+
+    Parameters
+    ----------
+    collection_path:
+        Path to the Postman Collection JSON file.
+    base_url:
+        Override the base URL extracted from the collection.  When ``None``
+        the parser tries ``{{baseUrl}}`` collection variables first, then
+        falls back to the first request's origin.
+    registry:
+        :class:`EndpointRegistry` to populate with discovered endpoints.
+        A fresh registry is created when ``None`` is passed.
+    max_tests:
+        Maximum number of :class:`TestCase` objects to generate.  ``None``
+        means no limit.
+    variables:
+        Extra variable mappings to resolve ``{{varName}}`` patterns.  These
+        take precedence over collection-level variable definitions.
+    """
+
+    def __init__(
+        self,
+        collection_path: str,
+        base_url: Optional[str] = None,
+        registry: Optional[EndpointRegistry] = None,
+        max_tests: Optional[int] = None,
+        variables: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.collection_path = collection_path
+        self.collection = self._load_collection(collection_path)
+        self.registry = registry if registry is not None else EndpointRegistry()
+        self.max_tests = max_tests
+
+        # Merge variable resolution order: caller-supplied > collection-level
+        coll_vars = _collect_collection_variables(self.collection)
+        self.variables: Dict[str, str] = {**coll_vars, **(variables or {})}
+
+        self.base_url = (
+            base_url
+            or _extract_base_url_from_collection(self.collection, self.variables)
+        ).rstrip("/")
+
+        # Collection-level auth (lower priority than request-level)
+        self._collection_auth: Optional[Dict[str, Any]] = self.collection.get("auth")
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def parse(self) -> List[TestCase]:
+        """Parse the collection and return all generated :class:`TestCase` objects."""
+        test_cases: List[TestCase] = []
+        items = self.collection.get("item", [])
+        request_items = self._flatten_items(items)
+
+        for item in request_items:
+            cases = self._generate_cases_for_item(item)
+            test_cases.extend(cases)
+
+            if self.max_tests is not None and len(test_cases) >= self.max_tests:
+                return test_cases[: self.max_tests]
+
+        return test_cases
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _load_collection(path: str) -> Dict[str, Any]:
+        """Load and return a Postman Collection JSON from *path*."""
+        text = Path(path).read_text(encoding="utf-8")
+        data = json.loads(text)
+        # Collections are sometimes wrapped under a "collection" top-level key
+        if "collection" in data and isinstance(data["collection"], dict):
+            return data["collection"]
+        return data
+
+    def _flatten_items(
+        self,
+        items: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        """Recursively walk item/folder trees and return only leaf request items."""
+        result: List[Dict[str, Any]] = []
+        for item in items:
+            if "item" in item:
+                # This is a folder — recurse
+                result.extend(self._flatten_items(item["item"]))
+            elif "request" in item:
+                result.append(item)
+        return result
+
+    def _generate_cases_for_item(
+        self,
+        item: Dict[str, Any],
+    ) -> List[TestCase]:
+        """Return positive + negative test cases for one Postman request item."""
+        cases: List[TestCase] = []
+        name = item.get("name", "Unnamed request")
+        request = item.get("request", {})
+
+        method = (request.get("method") or "GET").upper()
+
+        # --- URL --------------------------------------------------------
+        url_obj = request.get("url", "")
+        path, query_params = _parse_url(url_obj, self.variables)
+
+        # --- Auth headers -----------------------------------------------
+        request_auth = request.get("auth")
+        effective_auth = request_auth or self._collection_auth
+        auth_headers = _build_auth_headers(effective_auth)
+
+        # --- Request headers --------------------------------------------
+        headers: Dict[str, str] = dict(auth_headers)
+        for hdr in request.get("header", []):
+            if hdr.get("disabled"):
+                continue
+            hdr_key = hdr.get("key", "")
+            hdr_val = _resolve_variables(hdr.get("value", "") or "", self.variables)
+            if hdr_key:
+                headers[hdr_key] = hdr_val
+
+        # --- Request body -----------------------------------------------
+        body_obj = request.get("body")
+        json_body, required_fields = _parse_body(body_obj, self.variables)
+
+        # --- Register endpoint -----------------------------------------
+        ep_name = _path_to_endpoint_name(path)
+        parsed_base = urlparse(self.base_url) if self.base_url else None
+        host = (parsed_base.hostname or "localhost") if parsed_base else "localhost"
+        port = (
+            parsed_base.port
+            or (443 if (parsed_base and parsed_base.scheme == "https") else 80)
+        ) if parsed_base else 80
+        protocol = (parsed_base.scheme or "http") if parsed_base else "http"
+
+        endpoint = Endpoint(
+            name=ep_name,
+            host=host,
+            port=port,
+            protocol=protocol,
+            tags={"path": path},
+        )
+        self.registry.register(endpoint)
+
+        # ---- Positive test case ----------------------------------------
+        pos_inputs: Dict[str, Any] = {"method": method}
+        if query_params:
+            pos_inputs["query_params"] = query_params
+        if headers:
+            pos_inputs["headers"] = headers
+        if json_body is not None and method in {"POST", "PUT", "PATCH"}:
+            pos_inputs["json"] = json_body
+
+        cases.append(
+            TestCase(
+                target=path,
+                inputs=pos_inputs,
+                expected_behavior=f"[positive] {name}",
+                priority=0.5,
+                metadata={
+                    "spec_path": path,
+                    "method": method,
+                    "test_type": "positive",
+                    "generator": "postman",
+                },
+            )
+        )
+
+        # ---- Negative test cases ----------------------------------------
+        # 1. Missing required body field (if JSON body with fields present)
+        if json_body is not None and required_fields and method in {"POST", "PUT", "PATCH"}:
+            if isinstance(json_body, dict):
+                field_to_drop = required_fields[0]
+                missing_body = {k: v for k, v in json_body.items() if k != field_to_drop}
+                neg_inputs = {
+                    **pos_inputs,
+                    "json": missing_body,
+                    "expected_status_codes": [400, 422],
+                }
+                cases.append(
+                    TestCase(
+                        target=path,
+                        inputs=neg_inputs,
+                        expected_behavior=(
+                            f"[negative] {name}: missing required field '{field_to_drop}'"
+                        ),
+                        priority=0.6,
+                        metadata={
+                            "spec_path": path,
+                            "method": method,
+                            "test_type": "negative",
+                            "generator": "postman",
+                            "neg_type": "missing_required_field",
+                            "missing_field": field_to_drop,
+                        },
+                    )
+                )
+
+        # 2. Empty body for requests that have a body defined
+        if json_body is not None and method in {"POST", "PUT", "PATCH"}:
+            empty_inputs = {**pos_inputs, "json": {}, "expected_status_codes": [400, 422]}
+            cases.append(
+                TestCase(
+                    target=path,
+                    inputs=empty_inputs,
+                    expected_behavior=f"[negative] {name}: empty body",
+                    priority=0.6,
+                    metadata={
+                        "spec_path": path,
+                        "method": method,
+                        "test_type": "negative",
+                        "generator": "postman",
+                        "neg_type": "empty_body",
+                    },
+                )
+            )
+
+        return cases