schemathesis 3.13.0__py3-none-any.whl → 4.4.2__py3-none-any.whl

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

@@ -0,0 +1,232 @@
+"""Dependency detection between API operations for stateful testing.
+
+Infers which operations must run before others by tracking resource creation and consumption across API operations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from schemathesis.core import NOT_SET
+from schemathesis.core.compat import RefResolutionError
+from schemathesis.core.errors import InvalidSchema
+from schemathesis.core.result import Ok
+from schemathesis.specs.openapi.stateful.dependencies.inputs import (
+    extract_inputs,
+    merge_related_resources,
+    update_input_field_bindings,
+)
+from schemathesis.specs.openapi.stateful.dependencies.models import (
+    CanonicalizationCache,
+    Cardinality,
+    DefinitionSource,
+    DependencyGraph,
+    InputSlot,
+    NormalizedLink,
+    OperationMap,
+    OperationNode,
+    OutputSlot,
+    ResourceDefinition,
+    ResourceMap,
+)
+from schemathesis.specs.openapi.stateful.dependencies.outputs import extract_outputs
+from schemathesis.specs.openapi.stateful.dependencies.resources import remove_unused_resources
+
+if TYPE_CHECKING:
+    from schemathesis.schemas import APIOperation
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
+__all__ = [
+    "analyze",
+    "inject_links",
+    "DependencyGraph",
+    "InputSlot",
+    "OutputSlot",
+    "Cardinality",
+    "ResourceDefinition",
+    "DefinitionSource",
+]
+
+
+def analyze(schema: BaseOpenAPISchema) -> DependencyGraph:
+    """Build a dependency graph by inferring resource producers and consumers from API operations."""
+    operations: OperationMap = {}
+    resources: ResourceMap = {}
+    # Track resources that got upgraded (e.g., from parameter inference to schema definition)
+    # to propagate better field information to existing input slots
+    updated_resources: set[str] = set()
+    # Cache for expensive canonicalize() calls - same schemas are often processed multiple times
+    canonicalization_cache: CanonicalizationCache = {}
+
+    for result in schema.get_all_operations():
+        if isinstance(result, Ok):
+            operation = result.ok()
+            try:
+                inputs = extract_inputs(
+                    operation=operation,
+                    resources=resources,
+                    updated_resources=updated_resources,
+                    resolver=schema.resolver,
+                    canonicalization_cache=canonicalization_cache,
+                )
+                outputs = extract_outputs(
+                    operation=operation,
+                    resources=resources,
+                    updated_resources=updated_resources,
+                    resolver=schema.resolver,
+                    canonicalization_cache=canonicalization_cache,
+                )
+                operations[operation.label] = OperationNode(
+                    method=operation.method,
+                    path=operation.path,
+                    inputs=list(inputs),
+                    outputs=list(outputs),
+                )
+            except RefResolutionError:
+                # Skip operations with unresolvable $refs (e.g., unavailable external references or references with typos)
+                # These won't participate in dependency detection
+                continue
+
+    # Update input slots with improved resource definitions discovered during extraction
+    #
+    # Example:
+    #   - `DELETE /users/{userId}` initially inferred `User.fields=["userId"]`
+    #   - then `POST /users` response revealed `User.fields=["id", "email"]`
+    for resource in updated_resources:
+        update_input_field_bindings(resource, operations)
+
+    # Merge parameter-inferred resources with schema-defined ones
+    merge_related_resources(operations, resources)
+
+    # Clean up orphaned resources
+    remove_unused_resources(operations, resources)
+
+    return DependencyGraph(operations=operations, resources=resources)
+
+
+def inject_links(schema: BaseOpenAPISchema) -> int:
+    graph = analyze(schema)
+    return _inject_links(schema, graph)
+
+
+def _inject_links(schema: BaseOpenAPISchema, graph: DependencyGraph) -> int:
+    injected = 0
+    for response_links in graph.iter_links():
+        operation = schema.find_operation_by_reference(response_links.producer_operation_ref)
+        response = operation.responses.get(response_links.status_code)
+        links = response.definition.setdefault(schema.adapter.links_keyword, {})
+
+        # Normalize existing links once
+        if links:
+            normalized_existing = [_normalize_link(link, schema) for link in links.values()]
+        else:
+            normalized_existing = []
+
+        for link_name, definition in response_links.links.items():
+            inferred_link = definition.to_openapi()
+
+            # Check if duplicate / subsets exists
+            if normalized_existing:
+                normalized = _normalize_link(inferred_link, schema)
+                if any(_is_subset_link(normalized, existing) for existing in normalized_existing):
+                    continue
+
+            # Find unique name if collision exists
+            final_name = _resolve_link_name_collision(link_name, links)
+            links[final_name] = inferred_link
+            injected += 1
+    return injected
+
+
+def _normalize_link(link: dict[str, Any], schema: BaseOpenAPISchema) -> NormalizedLink:
+    """Normalize a link definition for comparison."""
+    operation = _resolve_link_operation(link, schema)
+
+    normalized_params = _normalize_parameter_keys(link.get("parameters", {}), operation)
+
+    return NormalizedLink(
+        path=operation.path,
+        method=operation.method,
+        parameters=normalized_params,
+        request_body=link.get("requestBody", {}),
+    )
+
+
+def _normalize_parameter_keys(parameters: dict, operation: APIOperation) -> set[str]:
+    """Normalize parameter keys to location.name format."""
+    normalized = set()
+
+    for parameter_name in parameters.keys():
+        # If already has location prefix, use as-is
+        if "." in parameter_name:
+            normalized.add(parameter_name)
+            continue
+
+        # Find the parameter and prepend location
+        for parameter in operation.iter_parameters():
+            if parameter.name == parameter_name:
+                normalized.add(f"{parameter.location.value}.{parameter_name}")
+                break
+
+    return normalized
+
+
+def _resolve_link_operation(link: dict, schema: BaseOpenAPISchema) -> APIOperation:
+    """Resolve link to operation."""
+    if "operationRef" in link:
+        return schema.find_operation_by_reference(link["operationRef"])
+    if "operationId" in link:
+        return schema.find_operation_by_id(link["operationId"])
+    raise InvalidSchema(
+        "Link definition is missing both 'operationRef' and 'operationId'. "
+        "At least one of these fields must be present to identify the target operation."
+    )
+
+
+def _resolve_link_name_collision(proposed_name: str, existing_links: dict[str, Any]) -> str:
+    """Find unique link name if collision exists."""
+    if proposed_name not in existing_links:
+        return proposed_name
+
+    suffix = 0
+    while True:
+        candidate = f"{proposed_name}_{suffix}"
+        if candidate not in existing_links:
+            return candidate
+        suffix += 1
+
+
+def _is_subset_link(inferred: NormalizedLink, existing: NormalizedLink) -> bool:
+    """Check if inferred link is a subset of existing link."""
+    # Must target the same operation
+    if inferred.path != existing.path or inferred.method != existing.method:
+        return False
+
+    # Inferred parameters must be subset of existing parameters
+    if not inferred.parameters.issubset(existing.parameters):
+        return False
+
+    # Inferred request body must be subset of existing body
+    return _is_request_body_subset(inferred.request_body, existing.request_body)
+
+
+def _is_request_body_subset(inferred_body: Any, existing_body: Any) -> bool:
+    """Check if inferred body is a subset of existing body."""
+    # Empty inferred body is always a subset
+    if not inferred_body:
+        return True
+
+    # If existing is empty but inferred isn't, not a subset
+    if not existing_body:
+        return False
+
+    # Both must be dicts for subset comparison, otherwise check for equality
+    if not isinstance(inferred_body, dict) or not isinstance(existing_body, dict):
+        return inferred_body == existing_body
+
+    # Check if all inferred fields exist in existing with same values
+    for key, value in inferred_body.items():
+        if existing_body.get(key, NOT_SET) != value:
+            return False
+
+    return True

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

@@ -0,0 +1,428 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterator
+
+from schemathesis.core import media_types
+from schemathesis.core.errors import MalformedMediaType
+from schemathesis.core.jsonschema.bundler import BUNDLE_STORAGE_KEY
+from schemathesis.core.jsonschema.types import get_type
+from schemathesis.core.parameters import ParameterLocation
+from schemathesis.specs.openapi.adapter.parameters import resource_name_from_ref
+from schemathesis.specs.openapi.stateful.dependencies import naming
+from schemathesis.specs.openapi.stateful.dependencies.models import (
+    CanonicalizationCache,
+    DefinitionSource,
+    InputSlot,
+    OperationMap,
+    OutputSlot,
+    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.adapter.parameters import OpenApiBody
+    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.
+    """
+    known_dependencies = set()
+    for param in operation.iter_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:
+            if input_slot.resource.source >= DefinitionSource.SCHEMA_WITH_PROPERTIES:
+                known_dependencies.add(input_slot.resource.name)
+            yield input_slot
+
+    for body in operation.body:
+        try:
+            if media_types.is_json(body.media_type):
+                yield from _resolve_body_dependencies(
+                    body=body, operation=operation, resources=resources, known_dependencies=known_dependencies
+                )
+        except MalformedMediaType:
+            continue
+
+
+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
+
+
+GENERIC_FIELD_NAMES = frozenset(
+    {
+        "body",
+        "text",
+        "content",
+        "message",
+        "description",
+    }
+)
+
+
+def _maybe_resolve_bundled(root: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
+    # Right now, the body schema comes bundled to dependency analysis
+    if BUNDLE_STORAGE_KEY in root and "$ref" in schema:
+        key = schema["$ref"].split("/")[-1]
+        return root[BUNDLE_STORAGE_KEY][key]
+    return schema
+
+
+def _resolve_body_dependencies(
+    *,
+    body: OpenApiBody,
+    operation: APIOperation,
+    resources: ResourceMap,
+    known_dependencies: set[str],
+) -> Iterator[InputSlot]:
+    schema = body.raw_schema
+    if not isinstance(schema, dict):
+        return
+
+    resolved = _maybe_resolve_bundled(schema, schema)
+
+    # For `items`, we'll inject an array with extracted resource
+    items = resolved.get("items", {})
+    if items is not None:
+        resource_name = naming.from_path(operation.path)
+
+        if "$ref" in items:
+            schema_key = items["$ref"].split("/")[-1]
+            original_ref = body.name_to_uri[schema_key]
+            resource_name = resource_name_from_ref(original_ref)
+            resource = resources.get(resource_name)
+            if resource is None:
+                resource = ResourceDefinition.inferred_from_parameter(name=resource_name, parameter_name=None)
+                resources[resource_name] = resource
+                field = None
+            else:
+                field = None
+            yield InputSlot(
+                resource=resource,
+                resource_field=field,
+                parameter_name=0,
+                parameter_location=ParameterLocation.BODY,
+            )
+
+    # Inspect each property that could be a part of some other resource
+    properties = resolved.get("properties", {})
+    required = resolved.get("required", [])
+    path = operation.path
+    for property_name, subschema in properties.items():
+        resource_name = naming.from_parameter(property_name, path)
+        if resource_name is not None:
+            resource = resources.get(resource_name)
+            if resource is None:
+                resource = ResourceDefinition.inferred_from_parameter(
+                    name=resource_name,
+                    parameter_name=property_name,
+                )
+                resources[resource_name] = resource
+                field = property_name
+            else:
+                field = (
+                    naming.find_matching_field(
+                        parameter=property_name,
+                        resource=resource_name,
+                        fields=resource.fields,
+                    )
+                    or "id"
+                )
+            yield InputSlot(
+                resource=resource,
+                resource_field=field,
+                parameter_name=property_name,
+                parameter_location=ParameterLocation.BODY,
+            )
+            continue
+
+        # Skip generic property names & optional fields (at least for now)
+        if property_name in GENERIC_FIELD_NAMES or property_name not in required:
+            continue
+
+        # Find candidate resources among known dependencies that actually have this field
+        candidates = [
+            resources[dep] for dep in known_dependencies if dep in resources and property_name in resources[dep].fields
+        ]
+
+        # Skip ambiguous cases when multiple resources have same field name
+        if len(candidates) != 1:
+            continue
+
+        resource = candidates[0]
+        # Ensure the target field supports the same type
+        if not resource.types[property_name] & set(get_type(subschema)):
+            continue
+
+        yield InputSlot(
+            resource=resource,
+            resource_field=property_name,
+            parameter_name=property_name,
+            parameter_location=ParameterLocation.BODY,
+        )
+
+
+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 or isinstance(input_slot.parameter_name, int):
+                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
+
+
+def merge_related_resources(operations: OperationMap, resources: ResourceMap) -> None:
+    """Merge parameter-inferred resources with schema-defined resources from related operations."""
+    candidates = find_producer_consumer_candidates(operations)
+
+    for producer_name, consumer_name in candidates:
+        producer = operations[producer_name]
+        consumer = operations[consumer_name]
+
+        # Try to upgrade each input slot
+        for input_slot in consumer.inputs:
+            result = try_merge_input_resource(input_slot, producer.outputs, resources)
+
+            if result is not None:
+                new_resource_name, new_field_name = result
+                # Update input slot to use the better resource definition
+                input_slot.resource = resources[new_resource_name]
+                input_slot.resource_field = new_field_name
+
+
+def try_merge_input_resource(
+    input_slot: InputSlot,
+    producer_outputs: list[OutputSlot],
+    resources: ResourceMap,
+) -> tuple[str, str] | None:
+    """Try to upgrade an input's resource to a producer's resource."""
+    consumer_resource = input_slot.resource
+
+    # Only upgrade parameter-inferred resources (low confidence)
+    if consumer_resource.source != DefinitionSource.PARAMETER_INFERENCE:
+        return None
+
+    # Try each producer output
+    for output in producer_outputs:
+        producer_resource = resources[output.resource.name]
+
+        # Only merge to schema-defined resources (high confidence)
+        if producer_resource.source != DefinitionSource.SCHEMA_WITH_PROPERTIES:
+            continue
+
+        # Try to match the input parameter to producer's fields
+        param_name = input_slot.parameter_name
+        if not isinstance(param_name, str):
+            continue
+
+        for resource_name in (input_slot.resource.name, producer_resource.name):
+            matched_field = naming.find_matching_field(
+                parameter=param_name,
+                resource=resource_name,
+                fields=producer_resource.fields,
+            )
+
+            if matched_field is not None:
+                return (producer_resource.name, matched_field)
+
+    return None
+
+
+def find_producer_consumer_candidates(operations: OperationMap) -> list[tuple[str, str]]:
+    """Find operation pairs that might produce/consume the same resource via REST patterns."""
+    candidates = []
+
+    # Group by base path to reduce comparisons
+    paths: dict[str, list[str]] = {}
+    for name, node in operations.items():
+        base = _extract_base_path(node.path)
+        paths.setdefault(base, []).append(name)
+
+    # Within each path group, find POST/PUT → GET/DELETE/PATCH patterns
+    for names in paths.values():
+        for producer_name in names:
+            producer = operations[producer_name]
+            # Producer must create/update and return data
+            if producer.method not in ("post", "put") or not producer.outputs:
+                continue
+
+            for consumer_name in names:
+                consumer = operations[consumer_name]
+                # Consumer must have path parameters
+                if not consumer.inputs:
+                    continue
+                # Paths must be related (collection + item pattern)
+                if _is_collection_item_pattern(producer.path, consumer.path):
+                    candidates.append((producer_name, consumer_name))
+
+    return candidates
+
+
+def _extract_base_path(path: str) -> str:
+    """Extract collection path: /blog/posts/{id} -> /blog/posts."""
+    parts = [p for p in path.split("/") if not p.startswith("{")]
+    return "/".join(parts).rstrip("/")
+
+
+def _is_collection_item_pattern(collection_path: str, item_path: str) -> bool:
+    """Check if paths follow REST collection/item pattern."""
+    # /blog/posts + /blog/posts/{postId}
+    normalized_collection = collection_path.rstrip("/")
+    normalized_item = item_path.rstrip("/")
+
+    # Must start with collection path
+    if not normalized_item.startswith(normalized_collection + "/"):
+        return False
+
+    # Extract the segment after collection path
+    remainder = normalized_item[len(normalized_collection) + 1 :]
+
+    # Must be a single path parameter: {paramName} with no slashes
+    return (
+        remainder.startswith("{")
+        and remainder.endswith("}")
+        and len(remainder) > 2  # Not empty {}
+        and "/" not in remainder
+    )