schemathesis 4.2.1__py3-none-any.whl → 4.3.0__py3-none-any.whl

schemathesis/specs/openapi/adapter/v2.py

@@ -5,6 +5,7 @@ from schemathesis.specs.openapi.adapter.protocol import (
     BuildPathParameter,
     ExtractHeaderSchema,
     ExtractParameterSchema,
+    ExtractRawResponseSchema,
     ExtractResponseSchema,
     ExtractSecurityParameters,
     IterParameters,
@@ -18,6 +19,7 @@ example_keyword = "x-example"
 examples_container_keyword = "x-examples"
 
 extract_parameter_schema: ExtractParameterSchema = parameters.extract_parameter_schema_v2
+extract_raw_response_schema: ExtractRawResponseSchema = responses.extract_raw_response_schema_v2
 extract_response_schema: ExtractResponseSchema = responses.extract_response_schema_v2
 extract_header_schema: ExtractHeaderSchema = responses.extract_header_schema_v2
 iter_parameters: IterParameters = parameters.iter_parameters_v2

schemathesis/specs/openapi/adapter/v3_0.py

@@ -5,6 +5,7 @@ from schemathesis.specs.openapi.adapter.protocol import (
     BuildPathParameter,
     ExtractHeaderSchema,
     ExtractParameterSchema,
+    ExtractRawResponseSchema,
     ExtractResponseSchema,
     ExtractSecurityParameters,
     IterParameters,
@@ -18,6 +19,7 @@ example_keyword = "example"
 examples_container_keyword = "examples"
 
 extract_parameter_schema: ExtractParameterSchema = parameters.extract_parameter_schema_v3
+extract_raw_response_schema: ExtractRawResponseSchema = responses.extract_raw_response_schema_v3
 extract_response_schema: ExtractResponseSchema = responses.extract_response_schema_v3
 extract_header_schema: ExtractHeaderSchema = responses.extract_header_schema_v3
 iter_parameters: IterParameters = parameters.iter_parameters_v3

schemathesis/specs/openapi/adapter/v3_1.py

@@ -5,6 +5,7 @@ from schemathesis.specs.openapi.adapter.protocol import (
     BuildPathParameter,
     ExtractHeaderSchema,
     ExtractParameterSchema,
+    ExtractRawResponseSchema,
     ExtractResponseSchema,
     ExtractSecurityParameters,
     IterParameters,
@@ -18,6 +19,7 @@ example_keyword = "example"
 examples_container_keyword = "examples"
 
 extract_parameter_schema: ExtractParameterSchema = parameters.extract_parameter_schema_v3
+extract_raw_response_schema: ExtractRawResponseSchema = responses.extract_raw_response_schema_v3
 extract_response_schema: ExtractResponseSchema = responses.extract_response_schema_v3
 extract_header_schema: ExtractHeaderSchema = responses.extract_header_schema_v3
 iter_parameters: IterParameters = parameters.iter_parameters_v3

schemathesis/specs/openapi/examples.py

@@ -109,15 +109,19 @@ def extract_top_level(
     assert isinstance(operation.schema, BaseOpenAPISchema)
 
     responses = list(operation.responses.iter_examples())
-    seen_references: set[str] = set()
     for parameter in operation.iter_parameters():
         if "schema" in parameter.definition:
             schema = parameter.definition["schema"]
             resolver = RefResolver.from_schema(schema)
-            seen_references.clear()
+            reference_path: tuple[str, ...] = ()
             definitions = [
                 parameter.definition,
-                *_expand_subschemas(schema=schema, resolver=resolver, seen_references=seen_references),
+                *[
+                    expanded_schema
+                    for expanded_schema, _ in _expand_subschemas(
+                        schema=schema, resolver=resolver, reference_path=reference_path
+                    )
+                ],
             ]
         else:
             definitions = [parameter.definition]
@@ -138,10 +142,15 @@ def extract_top_level(
         if "schema" in parameter.definition:
             schema = parameter.definition["schema"]
             resolver = RefResolver.from_schema(schema)
-            seen_references.clear()
-            for expanded in _expand_subschemas(schema=schema, resolver=resolver, seen_references=seen_references):
-                if isinstance(expanded, dict) and parameter.adapter.examples_container_keyword in expanded:
-                    for value in expanded[parameter.adapter.examples_container_keyword]:
+            reference_path = ()
+            for expanded_schema, _ in _expand_subschemas(
+                schema=schema, resolver=resolver, reference_path=reference_path
+            ):
+                if (
+                    isinstance(expanded_schema, dict)
+                    and parameter.adapter.examples_container_keyword in expanded_schema
+                ):
+                    for value in expanded_schema[parameter.adapter.examples_container_keyword]:
                         yield ParameterExample(
                             container=parameter.location.container_name, name=parameter.name, value=value
                         )
@@ -152,10 +161,15 @@ def extract_top_level(
         if "schema" in body.definition:
             schema = body.definition["schema"]
             resolver = RefResolver.from_schema(schema)
-            seen_references.clear()
+            reference_path = ()
             definitions = [
                 body.definition,
-                *_expand_subschemas(schema=schema, resolver=resolver, seen_references=seen_references),
+                *[
+                    expanded_schema
+                    for expanded_schema, _ in _expand_subschemas(
+                        schema=schema, resolver=resolver, reference_path=reference_path
+                    )
+                ],
             ]
         else:
             definitions = [body.definition]
@@ -172,58 +186,76 @@ def extract_top_level(
         if "schema" in body.definition:
             schema = body.definition["schema"]
             resolver = RefResolver.from_schema(schema)
-            seen_references.clear()
-            for expanded in _expand_subschemas(schema=schema, resolver=resolver, seen_references=seen_references):
-                if isinstance(expanded, dict) and body.adapter.examples_container_keyword in expanded:
-                    for value in expanded[body.adapter.examples_container_keyword]:
+            reference_path = ()
+            for expanded_schema, _ in _expand_subschemas(
+                schema=schema, resolver=resolver, reference_path=reference_path
+            ):
+                if isinstance(expanded_schema, dict) and body.adapter.examples_container_keyword in expanded_schema:
+                    for value in expanded_schema[body.adapter.examples_container_keyword]:
                         yield BodyExample(value=value, media_type=body.media_type)
 
 
 @overload
 def _resolve_bundled(
-    schema: dict[str, Any], resolver: RefResolver, seen_references: set[str]
-) -> dict[str, Any]: ...  # pragma: no cover
+    schema: dict[str, Any], resolver: RefResolver, reference_path: tuple[str, ...]
+) -> tuple[dict[str, Any], tuple[str, ...]]: ...
 
 
 @overload
-def _resolve_bundled(schema: bool, resolver: RefResolver, seen_references: set[str]) -> bool: ...  # pragma: no cover
+def _resolve_bundled(
+    schema: bool, resolver: RefResolver, reference_path: tuple[str, ...]
+) -> tuple[bool, tuple[str, ...]]: ...
 
 
 def _resolve_bundled(
-    schema: dict[str, Any] | bool, resolver: RefResolver, seen_references: set[str]
-) -> dict[str, Any] | bool:
+    schema: dict[str, Any] | bool, resolver: RefResolver, reference_path: tuple[str, ...]
+) -> tuple[dict[str, Any] | bool, tuple[str, ...]]:
+    """Resolve $ref if present."""
     if isinstance(schema, dict):
         reference = schema.get("$ref")
         if isinstance(reference, str):
-            if reference in seen_references:
+            # Check if this reference is already in the current path
+            if reference in reference_path:
                 # Try to remove recursive references to avoid infinite recursion
                 remaining_references = references.sanitize(schema)
                 if reference in remaining_references:
                     raise InfiniteRecursiveReference(reference)
-            seen_references.add(reference)
+
+            new_path = reference_path + (reference,)
+
             try:
-                _, schema = resolver.resolve(schema["$ref"])
+                _, resolved_schema = resolver.resolve(reference)
             except RefResolutionError as exc:
                 raise UnresolvableReference(reference) from exc
-    return schema
+
+            return resolved_schema, new_path
+
+    return schema, reference_path
 
 
 def _expand_subschemas(
-    *, schema: dict[str, Any] | bool, resolver: RefResolver, seen_references: set[str]
-) -> Generator[dict[str, Any] | bool, None, None]:
-    schema = _resolve_bundled(schema, resolver, seen_references)
-    yield schema
+    *, schema: dict[str, Any] | bool, resolver: RefResolver, reference_path: tuple[str, ...]
+) -> Generator[tuple[dict[str, Any] | bool, tuple[str, ...]], None, None]:
+    """Expand schema and all its subschemas."""
+    schema, current_path = _resolve_bundled(schema, resolver, reference_path)
+    yield (schema, current_path)
+
     if isinstance(schema, dict):
+        # For anyOf/oneOf, yield each alternative with the same path
         for key in ("anyOf", "oneOf"):
             if key in schema:
                 for subschema in schema[key]:
-                    yield subschema
+                    # Each alternative starts with the current path
+                    yield (subschema, current_path)
+
+        # For allOf, merge all alternatives
         if "allOf" in schema:
             subschema = deepclone(schema["allOf"][0])
-            subschema = _resolve_bundled(subschema, resolver, seen_references)
+            subschema, _ = _resolve_bundled(subschema, resolver, current_path)
+
             for sub in schema["allOf"][1:]:
                 if isinstance(sub, dict):
-                    sub = _resolve_bundled(sub, resolver, seen_references)
+                    sub, _ = _resolve_bundled(sub, resolver, current_path)
                     for key, value in sub.items():
                         if key == "properties":
                             subschema.setdefault("properties", {}).update(value)
@@ -235,7 +267,8 @@ def _expand_subschemas(
                             subschema.setdefault("examples", []).append(value)
                         else:
                             subschema[key] = value
-            yield subschema
+
+            yield (subschema, current_path)
 
 
 def extract_inner_examples(examples: dict[str, Any] | list, schema: BaseOpenAPISchema) -> Generator[Any, None, None]:
@@ -269,13 +302,12 @@ def extract_from_schemas(
     operation: APIOperation[OpenApiParameter, OpenApiResponses, OpenApiSecurityParameters],
 ) -> Generator[Example, None, None]:
     """Extract examples from parameters' schema definitions."""
-    seen_references: set[str] = set()
     for parameter in operation.iter_parameters():
         schema = parameter.optimized_schema
         if isinstance(schema, bool):
             continue
         resolver = RefResolver.from_schema(schema)
-        seen_references.clear()
+        reference_path: tuple[str, ...] = ()
         bundle_storage = schema.get(BUNDLE_STORAGE_KEY)
         for value in extract_from_schema(
             operation=operation,
@@ -283,7 +315,7 @@ def extract_from_schemas(
             example_keyword=parameter.adapter.example_keyword,
             examples_container_keyword=parameter.adapter.examples_container_keyword,
             resolver=resolver,
-            seen_references=seen_references,
+            reference_path=reference_path,
             bundle_storage=bundle_storage,
         ):
             yield ParameterExample(container=parameter.location.container_name, name=parameter.name, value=value)
@@ -295,14 +327,14 @@ def extract_from_schemas(
         resolver = RefResolver.from_schema(schema)
         bundle_storage = schema.get(BUNDLE_STORAGE_KEY)
         for example_keyword, examples_container_keyword in (("example", "examples"), ("x-example", "x-examples")):
-            seen_references.clear()
+            reference_path = ()
             for value in extract_from_schema(
                 operation=operation,
                 schema=schema,
                 example_keyword=example_keyword,
                 examples_container_keyword=examples_container_keyword,
                 resolver=resolver,
-                seen_references=seen_references,
+                reference_path=reference_path,
                 bundle_storage=bundle_storage,
             ):
                 yield BodyExample(value=value, media_type=body.media_type)
@@ -315,49 +347,57 @@ def extract_from_schema(
     example_keyword: str,
     examples_container_keyword: str,
     resolver: RefResolver,
-    seen_references: set[str],
+    reference_path: tuple[str, ...],
     bundle_storage: dict[str, Any] | None,
 ) -> Generator[Any, None, None]:
     """Extract all examples from a single schema definition."""
     # This implementation supports only `properties` and `items`
-    schema = _resolve_bundled(schema, resolver, seen_references)
+    schema, current_path = _resolve_bundled(schema, resolver, reference_path)
+
     if "properties" in schema:
         variants = {}
         required = schema.get("required", [])
         to_generate: dict[str, Any] = {}
+
         for name, subschema in schema["properties"].items():
             values = []
-            for subsubschema in _expand_subschemas(
-                schema=subschema, resolver=resolver, seen_references=seen_references
+            for expanded_schema, expanded_path in _expand_subschemas(
+                schema=subschema, resolver=resolver, reference_path=current_path
             ):
-                if isinstance(subsubschema, bool):
-                    to_generate[name] = subsubschema
+                if isinstance(expanded_schema, bool):
+                    to_generate[name] = expanded_schema
                     continue
-                if example_keyword in subsubschema:
-                    values.append(subsubschema[example_keyword])
-                if examples_container_keyword in subsubschema and isinstance(
-                    subsubschema[examples_container_keyword], list
+
+                if example_keyword in expanded_schema:
+                    values.append(expanded_schema[example_keyword])
+
+                if examples_container_keyword in expanded_schema and isinstance(
+                    expanded_schema[examples_container_keyword], list
                 ):
                     # These are JSON Schema examples, which is an array of values
-                    values.extend(subsubschema[examples_container_keyword])
+                    values.extend(expanded_schema[examples_container_keyword])
+
                 # Check nested examples as well
                 values.extend(
                     extract_from_schema(
                         operation=operation,
-                        schema=subsubschema,
+                        schema=expanded_schema,
                         example_keyword=example_keyword,
                         examples_container_keyword=examples_container_keyword,
                         resolver=resolver,
-                        seen_references=seen_references,
+                        reference_path=expanded_path,
                         bundle_storage=bundle_storage,
                     )
                 )
+
                 if not values:
                     if name in required:
                         # Defer generation to only generate these variants if at least one property has examples
-                        to_generate[name] = subsubschema
+                        to_generate[name] = expanded_schema
                     continue
+
                 variants[name] = values
+
         if variants:
             config = operation.schema.config.generation_for(operation=operation, phase="examples")
             for name, subschema in to_generate.items():
@@ -369,6 +409,7 @@ def extract_from_schema(
                     subschema[BUNDLE_STORAGE_KEY] = bundle_storage
                 generated = _generate_single_example(subschema, config)
                 variants[name] = [generated]
+
             # Calculate the maximum number of examples any property has
             total_combos = max(len(examples) for examples in variants.values())
             # Evenly distribute examples by cycling through them
@@ -377,6 +418,7 @@ def extract_from_schema(
                     name: next(islice(cycle(property_variants), idx, None))
                     for name, property_variants in variants.items()
                 }
+
     elif "items" in schema and isinstance(schema["items"], dict):
         # Each inner value should be wrapped in an array
         for value in extract_from_schema(
@@ -385,7 +427,7 @@ def extract_from_schema(
             example_keyword=example_keyword,
             examples_container_keyword=examples_container_keyword,
             resolver=resolver,
-            seen_references=seen_references,
+            reference_path=current_path,
             bundle_storage=bundle_storage,
         ):
             yield [value]

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

@@ -0,0 +1,88 @@
+"""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
+
+from schemathesis.core.compat import RefResolutionError
+from schemathesis.core.result import Ok
+from schemathesis.specs.openapi.stateful.dependencies.inputs import extract_inputs, update_input_field_bindings
+from schemathesis.specs.openapi.stateful.dependencies.models import (
+    CanonicalizationCache,
+    Cardinality,
+    DefinitionSource,
+    DependencyGraph,
+    InputSlot,
+    OperationMap,
+    OperationNode,
+    OutputSlot,
+    ResourceDefinition,
+    ResourceMap,
+)
+from schemathesis.specs.openapi.stateful.dependencies.outputs import extract_outputs
+
+if TYPE_CHECKING:
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
+__all__ = [
+    "analyze",
+    "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)
+
+    return DependencyGraph(operations=operations, resources=resources)

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