schemathesis 3.39.16__py3-none-any.whl → 4.0.0__py3-none-any.whl

schemathesis/generation/stateful/state_machine.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import hypothesis
+from hypothesis.errors import InvalidDefinition
+from hypothesis.stateful import RuleBasedStateMachine
+
+from schemathesis.checks import CheckFunction
+from schemathesis.core import DEFAULT_STATEFUL_STEP_COUNT
+from schemathesis.core.errors import NoLinksFound
+from schemathesis.core.result import Result
+from schemathesis.core.transport import Response
+from schemathesis.generation.case import Case
+
+if TYPE_CHECKING:
+    import hypothesis
+    from requests.structures import CaseInsensitiveDict
+
+    from schemathesis.schemas import BaseSchema
+
+
+DEFAULT_STATE_MACHINE_SETTINGS = hypothesis.settings(
+    phases=[hypothesis.Phase.generate],
+    deadline=None,
+    stateful_step_count=DEFAULT_STATEFUL_STEP_COUNT,
+    suppress_health_check=list(hypothesis.HealthCheck),
+)
+
+
+@dataclass
+class StepInput:
+    """Input for a single state machine step."""
+
+    case: Case
+    transition: Transition | None  # None for initial steps
+
+    __slots__ = ("case", "transition")
+
+    @classmethod
+    def initial(cls, case: Case) -> StepInput:
+        return cls(case=case, transition=None)
+
+
+@dataclass
+class Transition:
+    """Data about transition execution."""
+
+    # ID of the transition (e.g. link name)
+    id: str
+    parent_id: str
+    parameters: dict[str, dict[str, ExtractedParam]]
+    request_body: ExtractedParam | None
+
+    __slots__ = ("id", "parent_id", "parameters", "request_body")
+
+
+@dataclass
+class ExtractedParam:
+    """Result of parameter extraction."""
+
+    definition: Any
+    value: Result[Any, Exception]
+
+    __slots__ = ("definition", "value")
+
+
+@dataclass
+class ExtractionFailure:
+    """Represents a failure to extract data from a transition."""
+
+    # e.g., "GetUser"
+    id: str
+    case_id: str
+    # e.g., "POST /users"
+    source: str
+    # e.g., "GET /users/{userId}"
+    target: str
+    # e.g., "userId"
+    parameter_name: str
+    # e.g., "$response.body#/id"
+    expression: str
+    # Previous test cases in the chain, from newest to oldest
+    # Stored as a case + response pair
+    history: list[tuple[Case, Response]]
+    # The actual response that caused the failure
+    response: Response
+    error: Exception | None
+
+    __slots__ = ("id", "case_id", "source", "target", "parameter_name", "expression", "history", "response", "error")
+
+    def __eq__(self, other: object) -> bool:
+        assert isinstance(other, ExtractionFailure)
+        return (
+            self.source == other.source
+            and self.target == other.target
+            and self.id == other.id
+            and self.parameter_name == other.parameter_name
+            and self.expression == other.expression
+        )
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                self.source,
+                self.target,
+                self.id,
+                self.parameter_name,
+                self.expression,
+            )
+        )
+
+
+@dataclass
+class StepOutput:
+    """Output from a single transition of a state machine."""
+
+    response: Response
+    case: Case
+
+    __slots__ = ("response", "case")
+
+
+def _normalize_name(name: str) -> str:
+    return re.sub(r"\W|^(?=\d)", "_", name).replace("__", "_")
+
+
+class APIStateMachine(RuleBasedStateMachine):
+    """State machine for executing API operation sequences based on OpenAPI links.
+
+    Automatically generates test scenarios by chaining API operations according
+    to their defined relationships in the schema.
+    """
+
+    # This is a convenience attribute, which happened to clash with `RuleBasedStateMachine` instance level attribute
+    # They don't interfere, since it is properly overridden on the Hypothesis side, but it is likely that this
+    # attribute will be renamed in the future
+    bundles: ClassVar[dict[str, CaseInsensitiveDict]]  # type: ignore
+    schema: BaseSchema
+
+    def __init__(self) -> None:
+        try:
+            super().__init__()  # type: ignore
+        except InvalidDefinition as exc:
+            if "defines no rules" in str(exc):
+                if not self.schema.statistic.links.total:
+                    message = "Schema contains no link definitions required for stateful testing"
+                else:
+                    message = "All link definitions required for stateful testing are excluded by filters"
+                raise NoLinksFound(message) from None
+            raise
+        self.setup()
+
+    @classmethod
+    @lru_cache
+    def _to_test_case(cls) -> type:
+        from schemathesis.generation.stateful import run_state_machine_as_test
+
+        class StateMachineTestCase(RuleBasedStateMachine.TestCase):
+            settings = DEFAULT_STATE_MACHINE_SETTINGS
+
+            def runTest(self) -> None:
+                run_state_machine_as_test(cls, settings=self.settings)
+
+            runTest.is_hypothesis_test = True  # type: ignore[attr-defined]
+
+        StateMachineTestCase.__name__ = cls.__name__ + ".TestCase"
+        StateMachineTestCase.__qualname__ = cls.__qualname__ + ".TestCase"
+        return StateMachineTestCase
+
+    def _new_name(self, target: str) -> str:
+        target = _normalize_name(target)
+        return super()._new_name(target)  # type: ignore
+
+    def _get_target_for_result(self, result: StepOutput) -> str | None:
+        raise NotImplementedError
+
+    def _add_result_to_targets(self, targets: tuple[str, ...], result: StepOutput | None) -> None:
+        if result is None:
+            return
+        target = self._get_target_for_result(result)
+        if target is not None:
+            super()._add_result_to_targets((target,), result)
+
+    def _add_results_to_targets(self, targets: tuple[str, ...], results: list[StepOutput]) -> None:
+        # Hypothesis >6.131.15
+        for result in results:
+            target = self._get_target_for_result(result)
+            if target is not None:
+                super()._add_results_to_targets((target,), [result])
+
+    @classmethod
+    def run(cls, *, settings: hypothesis.settings | None = None) -> None:
+        """Execute the state machine test scenarios.
+
+        Args:
+            settings: Hypothesis settings for test execution.
+
+        """
+        from . import run_state_machine_as_test
+
+        __tracebackhide__ = True
+        return run_state_machine_as_test(cls, settings=settings)
+
+    def setup(self) -> None:
+        """Called once at the beginning of each test scenario."""
+
+    def teardown(self) -> None:
+        """Called once at the end of each test scenario."""
+
+    # To provide the return type in the rendered documentation
+    teardown.__doc__ = RuleBasedStateMachine.teardown.__doc__
+
+    def _step(self, input: StepInput) -> StepOutput | None:
+        __tracebackhide__ = True
+        return self.step(input)
+
+    def step(self, input: StepInput) -> StepOutput:
+        __tracebackhide__ = True
+        self.before_call(input.case)
+        kwargs = self.get_call_kwargs(input.case)
+        response = self.call(input.case, **kwargs)
+        self.after_call(response, input.case)
+        self.validate_response(response, input.case, **kwargs)
+        return StepOutput(response, input.case)
+
+    def before_call(self, case: Case) -> None:
+        """Called before each API operation in the scenario.
+
+        Args:
+            case: Test case data for the operation.
+
+        """
+
+    def after_call(self, response: Response, case: Case) -> None:
+        """Called after each API operation in the scenario.
+
+        Args:
+            response: HTTP response from the operation.
+            case: Test case data that was executed.
+
+        """
+
+    def call(self, case: Case, **kwargs: Any) -> Response:
+        return case.call(**kwargs)
+
+    def get_call_kwargs(self, case: Case) -> dict[str, Any]:
+        """Returns keyword arguments for the API call.
+
+        Args:
+            case: Test case being executed.
+
+        Returns:
+            Dictionary passed to the `case.call()` method.
+
+        """
+        return {}
+
+    def validate_response(
+        self, response: Response, case: Case, additional_checks: list[CheckFunction] | None = None, **kwargs: Any
+    ) -> None:
+        """Validates the API response using configured checks.
+
+        Args:
+            response: HTTP response to validate.
+            case: Test case that generated the response.
+            additional_checks: Extra validation functions to run.
+            kwargs: Transport-level keyword arguments.
+
+        Raises:
+            FailureGroup: When validation checks fail.
+
+        """
+        __tracebackhide__ = True
+        case.validate_response(response, additional_checks=additional_checks, transport_kwargs=kwargs)

schemathesis/graphql/__init__.py

@@ -0,0 +1,15 @@
+from schemathesis.graphql.loaders import from_asgi, from_dict, from_file, from_path, from_url, from_wsgi
+
+from ..specs.graphql import nodes
+from ..specs.graphql.scalars import scalar
+
+__all__ = [
+    "from_url",
+    "from_asgi",
+    "from_wsgi",
+    "from_file",
+    "from_path",
+    "from_dict",
+    "nodes",
+    "scalar",
+]

schemathesis/graphql/checks.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from schemathesis.core.failures import Failure, Severity
+
+if TYPE_CHECKING:
+    from graphql.error import GraphQLFormattedError
+
+
+class UnexpectedGraphQLResponse(Failure):
+    """GraphQL response is not a JSON object."""
+
+    __slots__ = ("operation", "type_name", "title", "message", "case_id", "severity")
+
+    def __init__(
+        self,
+        *,
+        operation: str,
+        type_name: str,
+        title: str = "Unexpected GraphQL Response",
+        message: str,
+        case_id: str | None = None,
+    ) -> None:
+        self.operation = operation
+        self.type_name = type_name
+        self.title = title
+        self.message = message
+        self.case_id = case_id
+        self.severity = Severity.MEDIUM
+
+    @property
+    def _unique_key(self) -> str:
+        return self.type_name
+
+
+class GraphQLClientError(Failure):
+    """GraphQL query has not been executed."""
+
+    __slots__ = ("operation", "errors", "title", "message", "case_id", "_unique_key_cache", "severity")
+
+    def __init__(
+        self,
+        *,
+        operation: str,
+        message: str,
+        errors: list[GraphQLFormattedError],
+        title: str = "GraphQL client error",
+        case_id: str | None = None,
+    ) -> None:
+        self.operation = operation
+        self.errors = errors
+        self.title = title
+        self.message = message
+        self.case_id = case_id
+        self._unique_key_cache: str | None = None
+        self.severity = Severity.MEDIUM
+
+    @property
+    def _unique_key(self) -> str:
+        if self._unique_key_cache is None:
+            self._unique_key_cache = _group_graphql_errors(self.errors)
+        return self._unique_key_cache
+
+
+class GraphQLServerError(Failure):
+    """GraphQL response indicates at least one server error."""
+
+    __slots__ = ("operation", "errors", "title", "message", "case_id", "_unique_key_cache", "severity")
+
+    def __init__(
+        self,
+        *,
+        operation: str,
+        message: str,
+        errors: list[GraphQLFormattedError],
+        title: str = "GraphQL server error",
+        case_id: str | None = None,
+    ) -> None:
+        self.operation = operation
+        self.errors = errors
+        self.title = title
+        self.message = message
+        self.case_id = case_id
+        self._unique_key_cache: str | None = None
+        self.severity = Severity.CRITICAL
+
+    @property
+    def _unique_key(self) -> str:
+        if self._unique_key_cache is None:
+            self._unique_key_cache = _group_graphql_errors(self.errors)
+        return self._unique_key_cache
+
+
+def _group_graphql_errors(errors: list[GraphQLFormattedError]) -> str:
+    entries = []
+    for error in errors:
+        message = error["message"]
+        if "locations" in error:
+            message += ";locations:"
+            for location in sorted(error["locations"]):
+                message += f"({location['line'], location['column']})"
+        if "path" in error:
+            message += ";path:"
+            for chunk in error["path"]:
+                message += str(chunk)
+        entries.append(message)
+    entries.sort()
+    return "".join(entries)

schemathesis/graphql/loaders.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from os import PathLike
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any, Callable, Dict, NoReturn, TypeVar, cast
+
+from schemathesis.config import SchemathesisConfig
+from schemathesis.core.errors import LoaderError, LoaderErrorKind
+from schemathesis.core.loaders import load_from_url, prepare_request_kwargs, raise_for_status, require_relative_url
+from schemathesis.hooks import HookContext, dispatch
+from schemathesis.python import asgi, wsgi
+
+if TYPE_CHECKING:
+    from graphql import DocumentNode
+
+    from schemathesis.specs.graphql.schemas import GraphQLSchema
+
+
+def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> GraphQLSchema:
+    """Load GraphQL schema from an ASGI application via introspection.
+
+    Args:
+        path: Relative URL path to the GraphQL endpoint (e.g., "/graphql")
+        app: ASGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the ASGI test client.
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        import schemathesis
+
+        app = FastAPI()
+        schema = schemathesis.graphql.from_asgi("/graphql", app)
+        ```
+
+    """
+    require_relative_url(path)
+    kwargs.setdefault("json", {"query": get_introspection_query()})
+    client = asgi.get_client(app)
+    response = load_from_url(client.post, url=path, **kwargs)
+    schema = extract_schema_from_response(response, lambda r: r.json())
+    loaded = from_dict(schema=schema, config=config)
+    loaded.app = app
+    loaded.location = path
+    return loaded
+
+
+def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> GraphQLSchema:
+    """Load GraphQL schema from a WSGI application via introspection.
+
+    Args:
+        path: Relative URL path to the GraphQL endpoint (e.g., "/graphql")
+        app: WSGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the WSGI test client.
+
+    Example:
+        ```python
+        from flask import Flask
+        import schemathesis
+
+        app = Flask(__name__)
+        schema = schemathesis.graphql.from_wsgi("/graphql", app)
+        ```
+
+    """
+    require_relative_url(path)
+    prepare_request_kwargs(kwargs)
+    kwargs.setdefault("json", {"query": get_introspection_query()})
+    client = wsgi.get_client(app)
+    response = client.post(path=path, **kwargs)
+    raise_for_status(response)
+    schema = extract_schema_from_response(response, lambda r: r.json)
+    loaded = from_dict(schema=schema, config=config)
+    loaded.app = app
+    loaded.location = path
+    return loaded
+
+
+def from_url(
+    url: str, *, config: SchemathesisConfig | None = None, wait_for_schema: float | None = None, **kwargs: Any
+) -> GraphQLSchema:
+    """Load GraphQL schema from a URL via introspection query.
+
+    Args:
+        url: Full URL to the GraphQL endpoint
+        config: Custom configuration. If `None`, uses auto-discovered config
+        wait_for_schema: Maximum time in seconds to wait for schema availability
+        **kwargs: Additional parameters passed to `requests.post()` (headers, timeout, auth, etc.).
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Basic usage
+        schema = schemathesis.graphql.from_url("https://api.example.com/graphql")
+
+        # With authentication and timeout
+        schema = schemathesis.graphql.from_url(
+            "https://api.example.com/graphql",
+            headers={"Authorization": "Bearer token"},
+            timeout=30,
+            wait_for_schema=10.0
+        )
+        ```
+
+    """
+    import requests
+
+    kwargs.setdefault("json", {"query": get_introspection_query()})
+    response = load_from_url(requests.post, url=url, wait_for_schema=wait_for_schema, **kwargs)
+    schema = extract_schema_from_response(response, lambda r: r.json())
+    loaded = from_dict(schema, config=config)
+    loaded.location = url
+    return loaded
+
+
+def from_path(
+    path: PathLike | str, *, config: SchemathesisConfig | None = None, encoding: str = "utf-8"
+) -> GraphQLSchema:
+    """Load GraphQL schema from a filesystem path.
+
+    Args:
+        path: File path to the GraphQL schema file (.graphql, .gql)
+        config: Custom configuration. If `None`, uses auto-discovered config
+        encoding: Text encoding for reading the file
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Load from GraphQL SDL file
+        schema = schemathesis.graphql.from_path("./schema.graphql")
+        ```
+
+    """
+    with open(path, encoding=encoding) as file:
+        loaded = from_file(file=file, config=config)
+    loaded.location = Path(path).absolute().as_uri()
+    return loaded
+
+
+def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None) -> GraphQLSchema:
+    """Load GraphQL schema from a file-like object or string.
+
+    Args:
+        file: File-like object or raw string containing GraphQL SDL
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
+
+        # From GraphQL SDL string
+        schema_sdl = '''
+            type Query {
+                user(id: ID!): User
+            }
+            type User {
+                id: ID!
+                name: String!
+            }
+        '''
+        schema = schemathesis.graphql.from_file(schema_sdl)
+
+        # From file object
+        with open("schema.graphql") as f:
+            schema = schemathesis.graphql.from_file(f)
+        ```
+
+    """
+    import graphql
+
+    if isinstance(file, str):
+        data = file
+    else:
+        data = file.read()
+    try:
+        document = graphql.build_schema(data)
+        result = graphql.execute(document, get_introspection_query_ast())
+        # TYPES: We don't pass `is_awaitable` above, therefore `result` is of the `ExecutionResult` type
+        result = cast(graphql.ExecutionResult, result)
+        # TYPES:
+        #  - `document` is a valid schema, because otherwise `build_schema` will rise an error;
+        #  - `INTROSPECTION_QUERY` is a valid query - it is known upfront;
+        # Therefore the execution result is always valid at this point and `result.data` is not `None`
+        schema = cast(Dict[str, Any], result.data)
+    except Exception as exc:
+        try:
+            schema = json.loads(data)
+            if not isinstance(schema, dict) or "__schema" not in schema:
+                _on_invalid_schema(exc)
+        except json.JSONDecodeError:
+            _on_invalid_schema(exc, extras=[entry for entry in str(exc).splitlines() if entry])
+    return from_dict(schema, config=config)
+
+
+def from_dict(schema: dict[str, Any], *, config: SchemathesisConfig | None = None) -> GraphQLSchema:
+    """Load GraphQL schema from a dictionary containing introspection result.
+
+    Args:
+        schema: Dictionary containing GraphQL introspection result or wrapped in 'data' key
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
+
+        # From introspection result
+        introspection = {
+            "__schema": {
+                "types": [...],
+                "queryType": {"name": "Query"},
+                # ... rest of introspection result
+            }
+        }
+        schema = schemathesis.graphql.from_dict(introspection)
+
+        # From GraphQL response format (with 'data' wrapper)
+        response_data = {
+            "data": {
+                "__schema": {
+                    "types": [...],
+                    "queryType": {"name": "Query"}
+                }
+            }
+        }
+        schema = schemathesis.graphql.from_dict(response_data)
+        ```
+
+    """
+    from schemathesis.specs.graphql.schemas import GraphQLSchema
+
+    if "data" in schema:
+        schema = schema["data"]
+    hook_context = HookContext()
+    dispatch("before_load_schema", hook_context, schema)
+
+    if config is None:
+        config = SchemathesisConfig.discover()
+    project_config = config.projects.get(schema)
+    instance = GraphQLSchema(schema, config=project_config)
+    dispatch("after_load_schema", hook_context, instance)
+    return instance
+
+
+@lru_cache
+def get_introspection_query() -> str:
+    import graphql
+
+    return graphql.get_introspection_query()
+
+
+@lru_cache
+def get_introspection_query_ast() -> DocumentNode:
+    import graphql
+
+    query = get_introspection_query()
+    return graphql.parse(query)
+
+
+R = TypeVar("R")
+
+
+def extract_schema_from_response(response: R, callback: Callable[[R], Any]) -> dict[str, Any]:
+    try:
+        decoded = callback(response)
+    except json.JSONDecodeError as exc:
+        raise LoaderError(
+            LoaderErrorKind.UNEXPECTED_CONTENT_TYPE,
+            "Received unsupported content while expecting a JSON payload for GraphQL",
+        ) from exc
+    return decoded
+
+
+def _on_invalid_schema(exc: Exception, extras: list[str] | None = None) -> NoReturn:
+    raise LoaderError(
+        LoaderErrorKind.GRAPHQL_INVALID_SCHEMA,
+        "The provided API schema does not appear to be a valid GraphQL schema",
+        extras=extras or [],
+    ) from exc