schemathesis 4.2.2__py3-none-any.whl → 4.3.1__py3-none-any.whl

schemathesis/specs/openapi/stateful/dependencies/inputs.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator
+
+from schemathesis.core.parameters import ParameterLocation
+from schemathesis.specs.openapi.stateful.dependencies import naming
+from schemathesis.specs.openapi.stateful.dependencies.models import (
+    CanonicalizationCache,
+    DefinitionSource,
+    InputSlot,
+    OperationMap,
+    ResourceDefinition,
+    ResourceMap,
+)
+from schemathesis.specs.openapi.stateful.dependencies.resources import extract_resources_from_responses
+
+if TYPE_CHECKING:
+    from schemathesis.core.compat import RefResolver
+    from schemathesis.specs.openapi.schemas import APIOperation
+
+
+def extract_inputs(
+    *,
+    operation: APIOperation,
+    resources: ResourceMap,
+    updated_resources: set[str],
+    resolver: RefResolver,
+    canonicalization_cache: CanonicalizationCache,
+) -> Iterator[InputSlot]:
+    """Extract resource dependencies for an API operation from its input parameters.
+
+    Connects each parameter (e.g., `userId`) to its resource definition (`User`),
+    creating placeholder resources if not yet discovered from their schemas.
+    """
+    # Note: Currently limited to path parameters. Query / header / body will be supported in future releases.
+    for param in operation.path_parameters:
+        input_slot = _resolve_parameter_dependency(
+            parameter_name=param.name,
+            parameter_location=param.location,
+            operation=operation,
+            resources=resources,
+            updated_resources=updated_resources,
+            resolver=resolver,
+            canonicalization_cache=canonicalization_cache,
+        )
+        if input_slot is not None:
+            yield input_slot
+
+
+def _resolve_parameter_dependency(
+    *,
+    parameter_name: str,
+    parameter_location: ParameterLocation,
+    operation: APIOperation,
+    resources: ResourceMap,
+    updated_resources: set[str],
+    resolver: RefResolver,
+    canonicalization_cache: CanonicalizationCache,
+) -> InputSlot | None:
+    """Connect a parameter to its resource definition, creating placeholder if needed.
+
+    Strategy:
+    1. Infer resource name from parameter (`userId` -> `User`)
+    2. Use existing resource if high-quality definition exists
+    3. Try discovering from operation's response schemas
+    4. Fall back to creating placeholder with a single field
+    """
+    resource_name = naming.from_parameter(parameter=parameter_name, path=operation.path)
+
+    if resource_name is None:
+        return None
+
+    resource = resources.get(resource_name)
+
+    # Upgrade low-quality resource definitions (e.g., from parameter inference)
+    # by searching this operation's responses for actual schema
+    if resource is None or resource.source < DefinitionSource.SCHEMA_WITH_PROPERTIES:
+        resource = _find_resource_in_responses(
+            operation=operation,
+            resource_name=resource_name,
+            resources=resources,
+            updated_resources=updated_resources,
+            resolver=resolver,
+            canonicalization_cache=canonicalization_cache,
+        )
+        if resource is not None:
+            resources[resource_name] = resource
+
+    # Determine resource and its field
+    if resource is None:
+        # No schema found - create placeholder resource with inferred field
+        #
+        # Example: `DELETE /users/{userId}` with no response body -> `User` resource with "userId" field
+        #
+        # Later operations with schemas will upgrade this placeholder
+        if resource_name in resources:
+            # Resource exists but was empty - update with parameter field
+            resources[resource_name].fields = [parameter_name]
+            resources[resource_name].source = DefinitionSource.PARAMETER_INFERENCE
+            updated_resources.add(resource_name)
+            resource = resources[resource_name]
+        else:
+            resource = ResourceDefinition.inferred_from_parameter(
+                name=resource_name,
+                parameter_name=parameter_name,
+            )
+            resources[resource_name] = resource
+        field = parameter_name
+    else:
+        # Match parameter to resource field (`userId` → `id`, `Id` → `ChannelId`, etc.)
+        field = (
+            naming.find_matching_field(
+                parameter=parameter_name,
+                resource=resource_name,
+                fields=resource.fields,
+            )
+            or "id"
+        )
+
+    return InputSlot(
+        resource=resource,
+        resource_field=field,
+        parameter_name=parameter_name,
+        parameter_location=parameter_location,
+    )
+
+
+def _find_resource_in_responses(
+    *,
+    operation: APIOperation,
+    resource_name: str,
+    resources: ResourceMap,
+    updated_resources: set[str],
+    resolver: RefResolver,
+    canonicalization_cache: CanonicalizationCache,
+) -> ResourceDefinition | None:
+    """Search operation's successful responses for a specific resource definition.
+
+    Used when a parameter references a resource not yet discovered. Scans this
+    operation's response schemas hoping to find the resource definition.
+    """
+    for _, extracted in extract_resources_from_responses(
+        operation=operation,
+        resources=resources,
+        updated_resources=updated_resources,
+        resolver=resolver,
+        canonicalization_cache=canonicalization_cache,
+    ):
+        if extracted.resource.name == resource_name:
+            return extracted.resource
+
+    return None
+
+
+def update_input_field_bindings(resource_name: str, operations: OperationMap) -> None:
+    """Update input slots field bindings after resource definition was upgraded.
+
+    When a resource's fields change (e.g., `User` upgraded from `["userId"]` to `["id", "email"]`),
+    existing input slots may reference stale field names. This re-evaluates field matching
+    for all operations using this resource.
+
+    Example:
+        `DELETE /users/{userId}` created `InputSlot(resource_field="userId")`
+        `POST /users` revealed actual fields `["id", "email"]`
+        This updates DELETE's `InputSlot` to use `resource_field="id"`
+
+    """
+    # Re-evaluate field matching for all operations referencing this resource
+    for operation in operations.values():
+        for input_slot in operation.inputs:
+            # Skip inputs not using this resource
+            if input_slot.resource.name != resource_name:
+                continue
+
+            # Re-match parameter to upgraded resource fields
+            new_field = naming.find_matching_field(
+                parameter=input_slot.parameter_name,
+                resource=resource_name,
+                fields=input_slot.resource.fields,
+            )
+            if new_field is not None:
+                input_slot.resource_field = new_field

schemathesis/specs/openapi/stateful/dependencies/models.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import difflib
+import enum
+from dataclasses import asdict, dataclass
+from typing import Any, Iterator, Mapping
+
+from typing_extensions import TypeAlias
+
+from schemathesis.core.parameters import ParameterLocation
+from schemathesis.core.transforms import encode_pointer
+
+
+@dataclass
+class DependencyGraph:
+    """Graph of API operations and their resource dependencies."""
+
+    operations: OperationMap
+    resources: ResourceMap
+
+    __slots__ = ("operations", "resources")
+
+    def serialize(self) -> dict[str, Any]:
+        serialized = asdict(self)
+
+        for operation in serialized["operations"].values():
+            del operation["method"]
+            del operation["path"]
+            for input in operation["inputs"]:
+                input["resource"] = input["resource"]["name"]
+            for output in operation["outputs"]:
+                output["resource"] = output["resource"]["name"]
+
+        for resource in serialized["resources"].values():
+            del resource["name"]
+            del resource["source"]
+
+        return serialized
+
+    def iter_links(self) -> Iterator[ResponseLinks]:
+        """Generate OpenAPI Links connecting producer and consumer operations.
+
+        Creates links from operations that produce resources to operations that
+        consume them. For example: `POST /users` (creates `User`) -> `GET /users/{id}`
+        (needs `User.id` parameter).
+        """
+        # Connect each producer output to matching consumer inputs
+        for producer in self.operations.values():
+            producer_path = encode_pointer(producer.path)
+            for output_slot in producer.outputs:
+                for consumer in self.operations.values():
+                    # Skip self-references
+                    if producer is consumer:
+                        continue
+
+                    consumer_path = encode_pointer(consumer.path)
+                    links: dict[str, LinkDefinition] = {}
+                    for input_slot in consumer.inputs:
+                        if input_slot.resource is output_slot.resource:
+                            body_pointer = build_response_body_pointer(
+                                output_slot.pointer, input_slot.resource_field, output_slot.cardinality
+                            )
+                            link_name = f"{consumer.method.capitalize()}{input_slot.resource.name}"
+                            links[link_name] = LinkDefinition(
+                                operation_ref=f"#/paths/{consumer_path}/{consumer.method}",
+                                parameters={
+                                    # Data is extracted from response body
+                                    f"{input_slot.parameter_location.value}.{input_slot.parameter_name}": f"$response.body#{body_pointer}",
+                                },
+                            )
+                    if links:
+                        yield ResponseLinks(
+                            producer_operation_ref=f"#/paths/{producer_path}/{producer.method}",
+                            status_code=output_slot.status_code,
+                            links=links,
+                        )
+
+    def assert_fieldless_resources(self, key: str, known: dict[str, frozenset[str]]) -> None:  # pragma: no cover
+        """Verify all resources have at least one field."""
+        # Fieldless resources usually indicate failed schema extraction, which can be caused by a bug
+        known_fieldless = known.get(key, frozenset())
+
+        for name, resource in self.resources.items():
+            if not resource.fields and name not in known_fieldless:
+                raise AssertionError(f"Resource {name} has no fields")
+
+    def assert_incorrect_field_mappings(self, key: str, known: dict[str, frozenset[str]]) -> None:
+        """Verify all input slots reference valid fields in their resources."""
+        known_mismatches = known.get(key, frozenset())
+
+        for operation in self.operations.values():
+            for input in operation.inputs:
+                # Skip unreliable definition sources
+                if input.resource.source < DefinitionSource.SCHEMA_WITH_PROPERTIES:
+                    continue
+                resource = self.resources[input.resource.name]
+                if (
+                    input.resource_field not in resource.fields and resource.name not in known_mismatches
+                ):  # pragma: no cover
+                    message = (
+                        f"Operation '{operation.method.upper()} {operation.path}': "
+                        f"InputSlot references field '{input.resource_field}' "
+                        f"not found in resource '{resource.name}'"
+                    )
+                    matches = difflib.get_close_matches(input.resource_field, resource.fields, n=1, cutoff=0.6)
+                    if matches:
+                        message += f". Closest field - `{matches[0]}`"
+                    elif resource.fields:
+                        message += f". Available fields - {', '.join(resource.fields)}"
+                    else:
+                        message += ". Resource has no fields"
+                    raise AssertionError(message)
+
+
+def build_response_body_pointer(pointer: str, field: str, cardinality: Cardinality) -> str:
+    if not pointer.endswith("/"):
+        pointer += "/"
+    if cardinality == Cardinality.MANY:
+        # For arrays, reference first element: /data → /data/0
+        pointer += "0/"
+    pointer += encode_pointer(field)
+    return pointer
+
+
+@dataclass
+class LinkDefinition:
+    """OpenAPI Link Object definition.
+
+    Represents a single link from a producer operation's response to a
+    consumer operation's input parameter.
+    """
+
+    operation_ref: str
+    """Reference to target operation (e.g., '#/paths/~1users~1{id}/get')"""
+
+    parameters: dict[str, str]
+    """Parameter mappings (e.g., {'path.id': '$response.body#/id'})"""
+
+    __slots__ = ("operation_ref", "parameters")
+
+    def to_openapi(self) -> dict[str, Any]:
+        """Convert to OpenAPI Links format."""
+        return {
+            "operationRef": self.operation_ref,
+            "parameters": self.parameters,
+        }
+
+
+@dataclass
+class ResponseLinks:
+    """Collection of OpenAPI Links for a producer operation's response.
+
+    Represents all links from a single response (e.g., POST /users -> 201)
+    to consumer operations that can use the produced resource.
+
+    Example:
+        POST /users -> 201 might have links to:
+        - GET /users/{id}
+        - PATCH /users/{id}
+        - DELETE /users/{id}
+
+    """
+
+    producer_operation_ref: str
+    """Reference to producer operation (e.g., '#/paths/~1users/post')"""
+
+    status_code: str
+    """Response status code (e.g., '201', '200', 'default')"""
+
+    links: dict[str, LinkDefinition]
+    """Named links (e.g., {'GetUserById': LinkDefinition(...)})"""
+
+    __slots__ = ("producer_operation_ref", "status_code", "links")
+
+    def to_openapi(self) -> dict[str, Any]:
+        """Convert to OpenAPI response links format."""
+        return {name: link_def.to_openapi() for name, link_def in self.links.items()}
+
+
+class Cardinality(str, enum.Enum):
+    """Whether there is one or many resources in a slot."""
+
+    ONE = "ONE"
+    MANY = "MANY"
+
+
+@dataclass
+class OperationNode:
+    """An API operation with its input/output dependencies."""
+
+    method: str
+    path: str
+    # What this operation NEEDS
+    inputs: list[InputSlot]
+    # What this operation PRODUCES
+    outputs: list[OutputSlot]
+
+    __slots__ = ("method", "path", "inputs", "outputs")
+
+
+@dataclass
+class InputSlot:
+    """A required input for an operation."""
+
+    # Which resource is needed
+    resource: ResourceDefinition
+    # Which field from that resource (e.g., "id")
+    resource_field: str
+    # Where it goes in the request (e.g., "userId")
+    parameter_name: str
+    parameter_location: ParameterLocation
+
+    __slots__ = ("resource", "resource_field", "parameter_name", "parameter_location")
+
+
+@dataclass
+class OutputSlot:
+    """Describes how to extract a resource from an operation's response."""
+
+    # Which resource type
+    resource: ResourceDefinition
+    # Where in response body (JSON pointer)
+    pointer: str
+    # Is this a single resource or an array?
+    cardinality: Cardinality
+    # HTTP status code
+    status_code: str
+
+    __slots__ = ("resource", "pointer", "cardinality", "status_code")
+
+
+@dataclass
+class ResourceDefinition:
+    """A minimal description of a resource structure."""
+
+    name: str
+    # A sorted list of resource fields
+    fields: list[str]
+    # How this resource was created
+    source: DefinitionSource
+
+    __slots__ = ("name", "fields", "source")
+
+    @classmethod
+    def without_properties(cls, name: str) -> ResourceDefinition:
+        return cls(name=name, fields=[], source=DefinitionSource.SCHEMA_WITHOUT_PROPERTIES)
+
+    @classmethod
+    def inferred_from_parameter(cls, name: str, parameter_name: str) -> ResourceDefinition:
+        return cls(name=name, fields=[parameter_name], source=DefinitionSource.PARAMETER_INFERENCE)
+
+
+class DefinitionSource(enum.IntEnum):
+    """Quality level of resource information.
+
+    Lower values are less reliable and should be replaced by higher values.
+    Same values should be merged (union of fields).
+    """
+
+    # From spec but no structural information
+    SCHEMA_WITHOUT_PROPERTIES = 0
+    # Guessed from parameter names (not in spec)
+    PARAMETER_INFERENCE = 1
+    # From spec with actual field definitions
+    SCHEMA_WITH_PROPERTIES = 2
+
+
+OperationMap: TypeAlias = dict[str, OperationNode]
+ResourceMap: TypeAlias = dict[str, ResourceDefinition]
+CanonicalizationCache: TypeAlias = dict[str, Mapping[str, Any]]