nat-engine 1__py3-none-any.whl

mannf/product/integrations/openapi_parser.py

@@ -0,0 +1,513 @@
+# 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.
+
+"""OpenAPI 3.x / Swagger 2.x spec parser.
+
+Reads a spec file (JSON or YAML) 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 json
+import logging
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+import yaml
+
+from mannf.core.distributed.endpoint import Endpoint, EndpointRegistry
+from mannf.core.testing.models import TestCase
+
+if TYPE_CHECKING:
+    from mannf.product.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_SCALAR_DEFAULTS: Dict[str, Any] = {
+    "string": "example",
+    "integer": 1,
+    "number": 1.0,
+    "boolean": True,
+    "array": [],
+    "object": {},
+}
+
+_WRONG_TYPE_VALUES: Dict[str, Any] = {
+    "string": 42,
+    "integer": "not-a-number",
+    "number": "not-a-number",
+    "boolean": "not-a-boolean",
+}
+
+
+def _load_spec(path: str) -> Dict[str, Any]:
+    """Load a JSON or YAML spec file from *path*."""
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    if p.suffix.lower() in {".yaml", ".yml"}:
+        return yaml.safe_load(text)
+    return json.loads(text)
+
+
+def _resolve_ref(spec: Dict[str, Any], ref: str) -> Dict[str, Any]:
+    """Resolve a ``$ref`` pointer within *spec* (internal refs only)."""
+    if not ref.startswith("#/"):
+        return {}
+    parts = ref.lstrip("#/").split("/")
+    node: Any = spec
+    for part in parts:
+        part = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(node, dict) or part not in node:
+            return {}
+        node = node[part]
+    return node if isinstance(node, dict) else {}
+
+
+def _schema_example(spec: Dict[str, Any], schema: Dict[str, Any], depth: int = 0) -> Any:
+    """Generate a minimal valid example value for *schema*."""
+    if depth > 5:
+        return None
+
+    if "$ref" in schema:
+        schema = _resolve_ref(spec, schema["$ref"])
+
+    schema_type = schema.get("type", "object")
+
+    if "example" in schema:
+        return schema["example"]
+    if "default" in schema:
+        return schema["default"]
+    if "enum" in schema and schema["enum"]:
+        return schema["enum"][0]
+
+    if schema_type == "object" or "properties" in schema:
+        props = schema.get("properties", {})
+        return {k: _schema_example(spec, v, depth + 1) for k, v in props.items()}
+
+    if schema_type == "array":
+        items = schema.get("items", {})
+        return [_schema_example(spec, items, depth + 1)]
+
+    return _SCALAR_DEFAULTS.get(schema_type, None)
+
+
+def _detect_version(spec: Dict[str, Any]) -> str:
+    """Return ``"openapi3"`` or ``"swagger2"``."""
+    if "openapi" in spec:
+        return "openapi3"
+    if "swagger" in spec:
+        return "swagger2"
+    return "openapi3"
+
+
+def _base_url_from_spec(spec: Dict[str, Any]) -> Optional[str]:
+    """Extract base URL from the spec if present."""
+    version = _detect_version(spec)
+    if version == "openapi3":
+        servers = spec.get("servers", [])
+        if servers:
+            return servers[0].get("url", "").rstrip("/")
+    else:  # swagger2
+        host = spec.get("host", "")
+        base_path = spec.get("basePath", "/").rstrip("/")
+        scheme = (spec.get("schemes") or ["http"])[0]
+        if host:
+            return f"{scheme}://{host}{base_path}"
+    return None
+
+
+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"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+class OpenApiParser:
+    """Parse an OpenAPI / Swagger spec and generate :class:`TestCase` objects.
+
+    Parameters
+    ----------
+    spec_path:
+        Path to the spec file (JSON or YAML).
+    base_url:
+        Override the base URL extracted from the spec.  When ``None`` the
+        parser tries to read ``servers[0].url`` (OpenAPI 3) or
+        ``host`` + ``basePath`` (Swagger 2).
+    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.
+    """
+
+    def __init__(
+        self,
+        spec_path: str,
+        base_url: Optional[str] = None,
+        registry: Optional[EndpointRegistry] = None,
+        max_tests: Optional[int] = None,
+        llm_provider: Optional["LLMProvider"] = None,
+    ) -> None:
+        self.spec_path = spec_path
+        self.spec = _load_spec(spec_path)
+        self.base_url = (base_url or _base_url_from_spec(self.spec) or "").rstrip("/")
+        self.registry = registry if registry is not None else EndpointRegistry()
+        self.max_tests = max_tests
+        self._version = _detect_version(self.spec)
+        self.llm_provider = llm_provider
+
+    def parse(self) -> List[TestCase]:
+        """Parse the spec and return all generated :class:`TestCase` objects."""
+        test_cases: List[TestCase] = []
+        paths = self.spec.get("paths", {})
+
+        for path, path_item in paths.items():
+            if not isinstance(path_item, dict):
+                continue
+
+            # Register endpoint
+            ep_name = _path_to_endpoint_name(path)
+            parsed_url = urlparse(self.base_url) if self.base_url else None
+            host = parsed_url.hostname or "localhost" if parsed_url else "localhost"
+            port = (
+                parsed_url.port or (443 if (parsed_url and parsed_url.scheme == "https") else 80)
+                if parsed_url else 80
+            )
+            protocol = (parsed_url.scheme or "http") if parsed_url else "http"
+
+            endpoint = Endpoint(
+                name=ep_name,
+                host=host,
+                port=port,
+                protocol=protocol,
+                tags={"path": path},
+            )
+            self.registry.register(endpoint)
+
+            for method in ("get", "post", "put", "patch", "delete", "head", "options"):
+                operation = path_item.get(method)
+                if not isinstance(operation, dict):
+                    continue
+
+                cases = self._generate_cases_for_operation(path, method.upper(), operation)
+                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
+
+    async def parse_with_llm(self) -> List[TestCase]:
+        """Parse the spec and augment with LLM-generated test cases when available.
+
+        Behaves identically to :meth:`parse` when no LLM provider is configured
+        or when the provider is not available (fail-safe).
+        """
+        test_cases: List[TestCase] = []
+        paths = self.spec.get("paths", {})
+
+        for path, path_item in paths.items():
+            if not isinstance(path_item, dict):
+                continue
+
+            # Register endpoint
+            ep_name = _path_to_endpoint_name(path)
+            parsed_url = urlparse(self.base_url) if self.base_url else None
+            host = parsed_url.hostname or "localhost" if parsed_url else "localhost"
+            port = (
+                parsed_url.port or (443 if (parsed_url and parsed_url.scheme == "https") else 80)
+                if parsed_url else 80
+            )
+            protocol = (parsed_url.scheme or "http") if parsed_url else "http"
+
+            endpoint = Endpoint(
+                name=ep_name,
+                host=host,
+                port=port,
+                protocol=protocol,
+                tags={"path": path},
+            )
+            self.registry.register(endpoint)
+
+            for method in ("get", "post", "put", "patch", "delete", "head", "options"):
+                operation = path_item.get(method)
+                if not isinstance(operation, dict):
+                    continue
+
+                cases = self._generate_cases_for_operation(path, method.upper(), operation)
+
+                # LLM augmentation
+                if self.llm_provider is not None and self.llm_provider.is_available():
+                    body_schema, _ = self._extract_body_schema(operation)
+                    parameters = operation.get("parameters", [])
+                    endpoint_info = {
+                        "method": method.upper(),
+                        "path": path,
+                        "description": (
+                            operation.get("summary")
+                            or operation.get("description")
+                            or ""
+                        ),
+                        "parameters": parameters,
+                        "schema": body_schema or {},
+                    }
+                    spec_context = {
+                        "info": self.spec.get("info", {}),
+                        "servers": self.spec.get("servers", []),
+                    }
+                    llm_cases = await self._generate_llm_cases(
+                        path, method.upper(), operation, endpoint_info, spec_context
+                    )
+                    cases.extend(llm_cases)
+
+                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
+
+    async def _generate_llm_cases(
+        self,
+        path: str,
+        method: str,
+        operation: Dict[str, Any],
+        endpoint_info: Dict[str, Any],
+        spec_context: Dict[str, Any],
+    ) -> List[TestCase]:
+        """Call the LLM provider and convert results to :class:`TestCase` objects."""
+        assert self.llm_provider is not None
+        try:
+            raw_cases = await self.llm_provider.generate_test_cases(
+                endpoint_info, spec_context, n=5
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("OpenApiParser: LLM generation failed for %s %s: %s", method, path, exc)
+            return []
+
+        cases: List[TestCase] = []
+        summary = operation.get("summary") or operation.get("operationId") or f"{method} {path}"
+        for raw in raw_cases:
+            if not isinstance(raw, dict):
+                continue
+            inputs = raw.get("inputs", {})
+            if not isinstance(inputs, dict):
+                inputs = {}
+            inputs.setdefault("method", method)
+            cases.append(
+                TestCase(
+                    target=path,
+                    inputs=inputs,
+                    expected_behavior=raw.get("expected_behavior", f"[llm] {summary}"),
+                    priority=0.7,
+                    metadata={
+                        "spec_path": path,
+                        "method": method,
+                        "test_type": raw.get("test_type", "llm"),
+                        "generator": "llm",
+                        "generation_strategy": "llm_edge_case",
+                    },
+                )
+            )
+        return cases
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _generate_cases_for_operation(
+        self,
+        path: str,
+        method: str,
+        operation: Dict[str, Any],
+    ) -> List[TestCase]:
+        """Return positive + negative test cases for one operation."""
+        cases: List[TestCase] = []
+        summary = operation.get("summary") or operation.get("operationId") or f"{method} {path}"
+
+        # Collect parameter info
+        parameters: List[Dict[str, Any]] = operation.get("parameters", [])
+        # Inherit path-level parameters if any
+        path_params, query_params, header_params = self._parse_parameters(parameters)
+
+        # Request body (OpenAPI 3 / Swagger 2)
+        body_schema, required_body_fields = self._extract_body_schema(operation)
+
+        # ---- Positive test case ----------------------------------------
+        pos_inputs: Dict[str, Any] = {"method": method}
+        if query_params:
+            pos_inputs["query_params"] = query_params
+        if header_params:
+            pos_inputs["headers"] = header_params
+
+        if body_schema and method in {"POST", "PUT", "PATCH"}:
+            pos_inputs["json"] = _schema_example(self.spec, body_schema)
+
+        # Replace path parameters in the target path
+        resolved_path = path
+        for param_name, param_value in path_params.items():
+            resolved_path = resolved_path.replace(f"{{{param_name}}}", str(param_value))
+
+        cases.append(
+            TestCase(
+                target=resolved_path,
+                inputs=pos_inputs,
+                expected_behavior=f"[positive] {summary}",
+                priority=0.5,
+                metadata={"spec_path": path, "method": method, "test_type": "positive"},
+            )
+        )
+
+        # ---- Negative test cases ----------------------------------------
+        # 1. Missing required body fields
+        if body_schema and required_body_fields and method in {"POST", "PUT", "PATCH"}:
+            full_body = _schema_example(self.spec, body_schema) or {}
+            if isinstance(full_body, dict) and required_body_fields:
+                # Drop the first required field
+                field_to_drop = next(iter(required_body_fields))
+                missing_body = {k: v for k, v in full_body.items() if k != field_to_drop}
+                neg_inputs = {**pos_inputs, "json": missing_body, "expected_status_codes": [400, 422]}
+                cases.append(
+                    TestCase(
+                        target=resolved_path,
+                        inputs=neg_inputs,
+                        expected_behavior=f"[negative] {summary}: missing required field '{field_to_drop}'",
+                        priority=0.6,
+                        metadata={
+                            "spec_path": path,
+                            "method": method,
+                            "test_type": "negative",
+                            "neg_type": "missing_required_field",
+                            "missing_field": field_to_drop,
+                        },
+                    )
+                )
+
+        # 2. Wrong type for first required body field
+        if body_schema and required_body_fields and method in {"POST", "PUT", "PATCH"}:
+            full_body = _schema_example(self.spec, body_schema) or {}
+            if isinstance(full_body, dict):
+                field_name = next(iter(required_body_fields))
+                props = body_schema.get("properties", {})
+                field_schema = props.get(field_name, {})
+                if "$ref" in field_schema:
+                    field_schema = _resolve_ref(self.spec, field_schema["$ref"])
+                field_type = field_schema.get("type", "string")
+                wrong_val = _WRONG_TYPE_VALUES.get(field_type)
+                if wrong_val is not None:
+                    wrong_body = {**full_body, field_name: wrong_val}
+                    neg_inputs2 = {
+                        **pos_inputs,
+                        "json": wrong_body,
+                        "expected_status_codes": [400, 422],
+                    }
+                    cases.append(
+                        TestCase(
+                            target=resolved_path,
+                            inputs=neg_inputs2,
+                            expected_behavior=(
+                                f"[negative] {summary}: wrong type for '{field_name}'"
+                            ),
+                            priority=0.6,
+                            metadata={
+                                "spec_path": path,
+                                "method": method,
+                                "test_type": "negative",
+                                "neg_type": "wrong_type",
+                                "field": field_name,
+                            },
+                        )
+                    )
+
+        # 3. Non-existent resource (append bogus ID for paths ending with a param)
+        if "{" not in path and method == "GET":
+            neg_path = resolved_path.rstrip("/") + "/99999999"
+            neg_inputs3 = {**pos_inputs, "expected_status_codes": [404]}
+            cases.append(
+                TestCase(
+                    target=neg_path,
+                    inputs=neg_inputs3,
+                    expected_behavior=f"[negative] {summary}: non-existent resource",
+                    priority=0.4,
+                    metadata={
+                        "spec_path": path,
+                        "method": method,
+                        "test_type": "negative",
+                        "neg_type": "not_found",
+                    },
+                )
+            )
+
+        return cases
+
+    def _parse_parameters(
+        self,
+        parameters: List[Dict[str, Any]],
+    ) -> Tuple[Dict[str, Any], Dict[str, Any], Dict[str, Any]]:
+        """Return (path_params, query_params, header_params) example dicts."""
+        path_params: Dict[str, Any] = {}
+        query_params: Dict[str, Any] = {}
+        header_params: Dict[str, Any] = {}
+
+        for param in parameters:
+            if "$ref" in param:
+                param = _resolve_ref(self.spec, param["$ref"])
+            name = param.get("name", "")
+            location = param.get("in", "")
+            schema = param.get("schema", {}) or {}
+            example = param.get("example") or _schema_example(self.spec, schema)
+
+            if location == "path":
+                path_params[name] = example if example is not None else "1"
+            elif location == "query":
+                query_params[name] = example if example is not None else ""
+            elif location == "header":
+                header_params[name] = str(example) if example is not None else ""
+
+        return path_params, query_params, header_params
+
+    def _extract_body_schema(
+        self,
+        operation: Dict[str, Any],
+    ) -> Tuple[Optional[Dict[str, Any]], List[str]]:
+        """Return (body_schema, required_fields) for the operation's request body."""
+        # OpenAPI 3
+        request_body = operation.get("requestBody", {})
+        if request_body:
+            content = request_body.get("content", {})
+            for media_type in ("application/json", "application/x-www-form-urlencoded"):
+                if media_type in content:
+                    schema = content[media_type].get("schema", {})
+                    if "$ref" in schema:
+                        schema = _resolve_ref(self.spec, schema["$ref"])
+                    required = schema.get("required", [])
+                    return schema, list(required)
+
+        # Swagger 2 body parameter
+        for param in operation.get("parameters", []):
+            if "$ref" in param:
+                param = _resolve_ref(self.spec, param["$ref"])
+            if param.get("in") == "body":
+                schema = param.get("schema", {})
+                if "$ref" in schema:
+                    schema = _resolve_ref(self.spec, schema["$ref"])
+                required = schema.get("required", [])
+                return schema, list(required)
+
+        return None, []