nat-engine 1__py3-none-any.whl

mannf/product/integrations/graphql_sut.py

@@ -0,0 +1,247 @@
+# 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.
+
+"""GraphQL System-Under-Test implementation.
+
+:class:`GraphQLSUT` introspects a GraphQL endpoint, generates test cases via
+:class:`~mannf.product.integrations.graphql_parser.GraphQLParser`, and executes them
+using ``httpx``.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from mannf.product.integrations.auth import AuthStrategy, NoAuth
+from mannf.product.integrations.graphql_parser import GraphQLParser
+from mannf.core.testing.models import TestCase, TestResult
+
+logger = logging.getLogger(__name__)
+
+# Standard GraphQL introspection query
+_INTROSPECTION_QUERY = """
+{
+  __schema {
+    queryType { name }
+    mutationType { name }
+    subscriptionType { name }
+    types {
+      name
+      kind
+      fields {
+        name
+        type { name kind ofType { name kind } }
+        args { name type { name kind ofType { name kind } } defaultValue }
+      }
+    }
+  }
+}
+"""
+
+
+class GraphQLSUT:
+    """Execute GraphQL test cases against a GraphQL API endpoint.
+
+    Parameters
+    ----------
+    endpoint_url:
+        Full URL to the GraphQL endpoint (e.g. ``"http://localhost:4000/graphql"``).
+    auth:
+        Authentication strategy applied before each request.
+        Defaults to :class:`~mannf.product.integrations.auth.NoAuth`.
+    timeout:
+        HTTP request timeout in seconds (default: 10).
+    headers:
+        Additional HTTP headers added to every request.
+    """
+
+    def __init__(
+        self,
+        endpoint_url: str,
+        auth: Optional[AuthStrategy] = None,
+        timeout: float = 10.0,
+        headers: Optional[Dict[str, str]] = None,
+        recorder: Optional[Any] = None,
+    ) -> None:
+        self.endpoint_url = endpoint_url
+        self.auth: AuthStrategy = auth or NoAuth()
+        self.timeout = timeout
+        self.headers: Dict[str, str] = {
+            "Content-Type": "application/json",
+            **(headers or {}),
+        }
+        self.recorder = recorder
+
+    # ------------------------------------------------------------------
+    # Core helpers
+    # ------------------------------------------------------------------
+
+    async def _post(self, payload: Any) -> httpx.Response:
+        """POST *payload* to the GraphQL endpoint, applying auth."""
+        request_kwargs: Dict[str, Any] = {
+            "method": "POST",
+            "url": self.endpoint_url,
+            "headers": dict(self.headers),
+            "json": payload,
+            "timeout": self.timeout,
+        }
+        request_kwargs = await self.auth.apply(request_kwargs)
+
+        async with httpx.AsyncClient() as client:
+            return await client.request(**request_kwargs)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def introspect(self) -> dict:
+        """Send a GraphQL introspection query and return the raw result dict."""
+        response = await self._post({"query": _INTROSPECTION_QUERY})
+        return response.json()
+
+    async def execute_query(
+        self, query: str, variables: Optional[dict] = None
+    ) -> dict:
+        """Execute a GraphQL query.
+
+        Returns
+        -------
+        dict
+            Parsed JSON body — typically ``{"data": ..., "errors": [...]}``.
+        """
+        payload: Dict[str, Any] = {"query": query}
+        if variables:
+            payload["variables"] = variables
+        response = await self._post(payload)
+        return response.json()
+
+    async def execute_mutation(
+        self, mutation: str, variables: Optional[dict] = None
+    ) -> dict:
+        """Execute a GraphQL mutation.
+
+        Parameters
+        ----------
+        mutation:
+            The GraphQL mutation document string.
+        variables:
+            Optional dict of variable values.
+        """
+        return await self.execute_query(mutation, variables)
+
+    async def generate_test_cases(self) -> List[TestCase]:
+        """Introspect the schema and return generated :class:`~mannf.core.testing.models.TestCase` objects."""
+        raw = await self.introspect()
+        parser = GraphQLParser(raw)
+        schema = parser.parse()
+        return parser.generate_test_cases(schema, self.endpoint_url)
+
+    async def run_test(self, test_case: TestCase) -> TestResult:
+        """Execute a single :class:`~mannf.core.testing.models.TestCase` and return a :class:`~mannf.core.testing.models.TestResult`.
+
+        A GraphQL response is considered **passing** when:
+
+        1. The HTTP status code is 200 (or matches ``expected_status_codes``).
+        2. The response body contains a ``"data"`` key.
+
+        If the response has an ``"errors"`` key it is logged as a warning but
+        does **not** automatically cause the test to fail.
+        """
+        json_payload = test_case.inputs.get("json")
+        expected_codes = frozenset(
+            test_case.inputs.get("expected_status_codes") or [200]
+        )
+
+        start = time.monotonic()
+        try:
+            response = await self._post(json_payload)
+            elapsed_ms = (time.monotonic() - start) * 1000.0
+
+            status_ok = response.status_code in expected_codes
+
+            try:
+                body: Any = response.json()
+            except Exception:
+                body = response.text
+
+            error_msg: Optional[str] = None
+
+            if not status_ok:
+                error_msg = f"Unexpected HTTP status {response.status_code}"
+                result = TestResult(
+                    test_case_id=test_case.id,
+                    passed=False,
+                    actual_output=body,
+                    execution_time_ms=elapsed_ms,
+                    error=error_msg,
+                )
+            else:
+                # A valid GraphQL response must have a "data" key
+                if isinstance(body, dict):
+                    has_data = "data" in body
+                    gql_errors = body.get("errors")
+                    if gql_errors:
+                        logger.warning(
+                            "GraphQL errors in response for %s: %s",
+                            test_case.target,
+                            gql_errors,
+                        )
+                    passed = has_data
+                    if not passed:
+                        error_msg = "Response missing 'data' key"
+                else:
+                    # Batch responses are lists — treat as passing when status is OK
+                    passed = True
+
+                result = TestResult(
+                    test_case_id=test_case.id,
+                    passed=passed,
+                    actual_output=body,
+                    execution_time_ms=elapsed_ms,
+                    error=error_msg,
+                )
+
+            if self.recorder is not None:
+                self.recorder.record(
+                    test_case_id=test_case.id,
+                    method="POST",
+                    url=self.endpoint_url,
+                    request_headers=dict(self.headers),
+                    request_body=json_payload,
+                    query_params=None,
+                    status_code=response.status_code,
+                    response_headers=dict(response.headers),
+                    response_body=body,
+                    latency_ms=elapsed_ms,
+                    passed=result.passed,
+                    error=result.error,
+                )
+
+            return result
+
+        except httpx.TimeoutException as exc:
+            elapsed_ms = (time.monotonic() - start) * 1000.0
+            logger.warning("GraphQLSUT: timeout for %s — %s", self.endpoint_url, exc)
+            return TestResult(
+                test_case_id=test_case.id,
+                passed=False,
+                actual_output=None,
+                execution_time_ms=elapsed_ms,
+                error=f"Request timed out: {exc}",
+            )
+        except httpx.RequestError as exc:
+            elapsed_ms = (time.monotonic() - start) * 1000.0
+            logger.warning("GraphQLSUT: connection error for %s — %s", self.endpoint_url, exc)
+            return TestResult(
+                test_case_id=test_case.id,
+                passed=False,
+                actual_output=None,
+                execution_time_ms=elapsed_ms,
+                error=f"Connection error: {exc}",
+            )