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

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

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable, Mapping
+
+from schemathesis.core.jsonschema import ALL_KEYWORDS
+from schemathesis.core.jsonschema.bundler import BUNDLE_STORAGE_KEY, bundle
+from schemathesis.core.jsonschema.types import JsonSchema, JsonSchemaObject, get_type
+from schemathesis.core.transforms import encode_pointer
+from schemathesis.specs.openapi.adapter.parameters import resource_name_from_ref
+from schemathesis.specs.openapi.adapter.references import maybe_resolve
+from schemathesis.specs.openapi.stateful.dependencies import naming
+
+if TYPE_CHECKING:
+    from schemathesis.core.compat import RefResolver
+
+ROOT_POINTER = "/"
+SCHEMA_KEYS = frozenset(
+    {
+        "propertyNames",
+        "contains",
+        "if",
+        "items",
+        "oneOf",
+        "anyOf",
+        "additionalProperties",
+        "then",
+        "else",
+        "not",
+        "additionalItems",
+        "allOf",
+    }
+)
+SCHEMA_OBJECT_KEYS = frozenset({"dependencies", "properties", "patternProperties"})
+
+
+def resolve_all_refs(schema: JsonSchemaObject) -> dict[str, Any]:
+    if not schema:
+        return schema
+    bundled = schema.get(BUNDLE_STORAGE_KEY, {})
+
+    resolved_cache: dict[str, dict[str, Any]] = {}
+
+    def resolve(ref: str) -> dict[str, Any]:
+        # All references here are bundled, therefore it is safe to avoid full reference resolving
+        if ref in resolved_cache:
+            return resolved_cache[ref]
+        key = ref.split("/")[-1]
+        # No clone needed, as it will be cloned inside `merged`
+        result = resolve_all_refs_inner(bundled[key], resolve=resolve)
+        resolved_cache[ref] = result
+        return result
+
+    return resolve_all_refs_inner(schema, resolve=resolve)
+
+
+def resolve_all_refs_inner(schema: JsonSchema, *, resolve: Callable[[str], dict[str, Any]]) -> dict[str, Any]:
+    from hypothesis_jsonschema._canonicalise import merged
+
+    if schema is True:
+        return {}
+    if schema is False:
+        return {"not": {}}
+    if not schema:
+        return schema
+
+    reference = schema.get("$ref")
+    if reference is not None:
+        resolved = resolve(reference)
+        if len(schema) == 1 or (len(schema) == 2 and BUNDLE_STORAGE_KEY in schema):
+            return resolved
+        del schema["$ref"]
+        schema.pop(BUNDLE_STORAGE_KEY, None)
+        schema.pop("example", None)
+        return merged([resolve_all_refs_inner(schema, resolve=resolve), resolved])
+
+    for key, value in schema.items():
+        if key in SCHEMA_KEYS:
+            if isinstance(value, list):
+                schema[key] = [resolve_all_refs_inner(v, resolve=resolve) if isinstance(v, dict) else v for v in value]
+            elif isinstance(value, dict):
+                schema[key] = resolve_all_refs_inner(value, resolve=resolve)
+        if key in SCHEMA_OBJECT_KEYS:
+            schema[key] = {
+                k: resolve_all_refs_inner(v, resolve=resolve) if isinstance(v, dict) else v for k, v in value.items()
+            }
+    return schema
+
+
+def canonicalize(schema: dict[str, Any], resolver: RefResolver) -> Mapping[str, Any]:
+    """Transform the input schema into its canonical-ish form."""
+    from hypothesis_jsonschema._canonicalise import canonicalish
+
+    # Canonicalisation in `hypothesis_jsonschema` requires all references to be resovable and non-recursive
+    # On the Schemathesis side bundling solves this problem
+    bundled = bundle(schema, resolver, inline_recursive=True).schema
+    canonicalized = canonicalish(bundled)
+    resolved = resolve_all_refs(canonicalized)
+    resolved.pop(BUNDLE_STORAGE_KEY, None)
+    if "allOf" in resolved or "anyOf" in resolved or "oneOf" in resolved:
+        return canonicalish(resolved)
+    return resolved
+
+
+def try_unwrap_composition(schema: Mapping[str, Any], resolver: RefResolver) -> Mapping[str, Any]:
+    """Unwrap oneOf/anyOf if we can safely extract a single schema."""
+    keys = ("anyOf", "oneOf")
+    composition_key = None
+    for key in keys:
+        if key in schema:
+            composition_key = key
+            break
+
+    if composition_key is None:
+        return schema
+
+    alternatives = schema[composition_key]
+
+    if not isinstance(alternatives, list):
+        return schema
+
+    # Filter to interesting alternatives
+    interesting = _filter_composition_alternatives(alternatives, resolver)
+
+    # If no interesting alternatives, return original
+    if not interesting:
+        return schema
+
+    # If exactly one interesting alternative, unwrap it
+    if len(interesting) == 1:
+        return interesting[0]
+
+    # Pick the first one
+    # TODO: Support multiple alternatives
+    return interesting[0]
+
+
+def try_unwrap_all_of(schema: Mapping[str, Any]) -> Mapping[str, Any]:
+    alternatives = schema.get("allOf")
+    if not isinstance(alternatives, list):
+        return schema
+
+    interesting = []
+
+    for subschema in alternatives:
+        if isinstance(subschema, dict) and _is_interesting_schema(subschema):
+            interesting.append(subschema)
+
+    if len(interesting) == 1:
+        return interesting[0]
+    return schema
+
+
+def _filter_composition_alternatives(alternatives: list[dict], resolver: RefResolver) -> list[dict]:
+    """Filter oneOf/anyOf alternatives to keep only interesting schemas."""
+    interesting = []
+
+    for alt_schema in alternatives:
+        _, resolved = maybe_resolve(alt_schema, resolver, "")
+
+        if _is_interesting_schema(resolved):
+            # Keep original (with $ref)
+            interesting.append(alt_schema)
+
+    return interesting
+
+
+def _is_interesting_schema(schema: Mapping[str, Any]) -> bool:
+    """Check if a schema represents interesting structured data."""
+    # Has $ref - definitely interesting (references a named schema)
+    if "$ref" in schema:
+        return True
+
+    ty = schema.get("type")
+
+    # Primitives are not interesting
+    if ty in {"string", "number", "integer", "boolean", "null"}:
+        return False
+
+    # Arrays - check items
+    if ty == "array":
+        items = schema.get("items")
+        if not isinstance(items, dict):
+            return False
+        # Recursively check if items are interesting
+        return _is_interesting_schema(items)
+
+    # allOf/anyOf/oneOf - interesting (composition)
+    if any(key in schema for key in ["allOf", "anyOf", "oneOf"]):
+        return True
+
+    # Objects (or untyped) - check if they have any keywords
+    return bool(set(schema).intersection(ALL_KEYWORDS))
+
+
+@dataclass
+class UnwrappedSchema:
+    """Result of wrapper pattern detection."""
+
+    pointer: str
+    schema: Mapping[str, Any]
+    ref: str | None
+
+    __slots__ = ("pointer", "schema", "ref")
+
+
+def unwrap_schema(
+    schema: Mapping[str, Any], path: str, parent_ref: str | None, resolver: RefResolver
+) -> UnwrappedSchema:
+    # Array at root
+    if schema.get("type") == "array":
+        return UnwrappedSchema(pointer="/", schema=schema, ref=None)
+
+    properties = schema.get("properties", {})
+
+    # HAL _embedded (Spring-specific)
+    hal_field = _detect_hal_embedded(schema)
+    if hal_field:
+        embedded_schema = properties["_embedded"]
+        _, resolved_embedded = maybe_resolve(embedded_schema, resolver, "")
+        resource_schema = resolved_embedded.get("properties", {}).get(hal_field, {})
+        _, resolved_resource = maybe_resolve(resource_schema, resolver, "")
+
+        return UnwrappedSchema(
+            pointer=f"/_embedded/{encode_pointer(hal_field)}", schema=resolved_resource, ref=resource_schema.get("$ref")
+        )
+
+    # Pagination wrapper
+    array_field = _is_pagination_wrapper(schema=schema, path=path, parent_ref=parent_ref, resolver=resolver)
+    if array_field:
+        array_schema = properties[array_field]
+        _, resolved = maybe_resolve(array_schema, resolver, "")
+        pointer = f"/{encode_pointer(array_field)}"
+
+        uses_parent_ref = False
+        # Try to unwrap one more time
+        if resolved.get("type") == "array" or "items" in resolved:
+            nested_items = resolved.get("items")
+            if isinstance(nested_items, dict):
+                _, resolved_items = maybe_resolve(nested_items, resolver, "")
+                external_tag = _detect_externally_tagged_pattern(resolved_items, path, parent_ref)
+                if external_tag:
+                    external_tag_, uses_parent_ref = external_tag
+                    nested_properties = resolved_items["properties"][external_tag_]
+                    _, resolved = maybe_resolve(nested_properties, resolver, "")
+                    pointer += f"/{encode_pointer(external_tag_)}"
+
+        ref = parent_ref if uses_parent_ref else array_schema.get("$ref")
+        return UnwrappedSchema(pointer=pointer, schema=resolved, ref=array_schema.get("$ref"))
+
+    # External tag
+    external_tag = _detect_externally_tagged_pattern(schema, path, parent_ref)
+    if external_tag:
+        external_tag_, uses_parent_ref = external_tag
+        tagged_schema = properties[external_tag_]
+        _, resolved_tagged = maybe_resolve(tagged_schema, resolver, "")
+
+        resolved = try_unwrap_all_of(resolved_tagged)
+        ref = (
+            parent_ref
+            if uses_parent_ref
+            else resolved.get("$ref") or resolved_tagged.get("$ref") or tagged_schema.get("$ref")
+        )
+
+        _, resolved = maybe_resolve(resolved, resolver, "")
+        return UnwrappedSchema(pointer=f"/{encode_pointer(external_tag_)}", schema=resolved, ref=ref)
+
+    # No wrapper - single object at root
+    return UnwrappedSchema(pointer="/", schema=schema, ref=schema.get("$ref"))
+
+
+def _detect_hal_embedded(schema: Mapping[str, Any]) -> str | None:
+    """Detect HAL _embedded pattern.
+
+    Spring Data REST uses: {_embedded: {users: [...]}}
+    """
+    properties = schema.get("properties", {})
+    embedded = properties.get("_embedded")
+
+    if not isinstance(embedded, dict):
+        return None
+
+    embedded_properties = embedded.get("properties", {})
+
+    # Find array properties in _embedded
+    for name, subschema in embedded_properties.items():
+        if isinstance(subschema, dict) and subschema.get("type") == "array":
+            # Found array in _embedded
+            return name
+
+    return None
+
+
+def _is_pagination_wrapper(
+    schema: Mapping[str, Any], path: str, parent_ref: str | None, resolver: RefResolver
+) -> str | None:
+    """Detect if schema is a pagination wrapper."""
+    properties = schema.get("properties", {})
+
+    if not properties:
+        return None
+
+    metadata_fields = frozenset(["links", "errors"])
+
+    # Find array properties
+    arrays = []
+    for name, subschema in properties.items():
+        if name in metadata_fields:
+            continue
+        if isinstance(subschema, dict):
+            _, subschema = maybe_resolve(subschema, resolver, "")
+            if subschema.get("type") == "array":
+                arrays.append(name)
+
+    # Must have exactly one array property
+    if len(arrays) != 1:
+        return None
+
+    array_field = arrays[0]
+
+    # Check if array field name matches common patterns
+    common_data_fields = {"data", "items", "results", "value", "content", "elements", "records", "list"}
+
+    if parent_ref:
+        resource_name = resource_name_from_ref(parent_ref)
+        resource_name = naming.strip_affixes(resource_name, ["get", "create", "list", "delete"], ["response"])
+        common_data_fields.add(resource_name.lower())
+
+    if array_field.lower() not in common_data_fields:
+        # Check if field name matches resource-specific pattern
+        # Example: path="/items/runner-groups" -> resource="RunnerGroup" -> "runner_groups"
+        resource_name_from_path = naming.from_path(path)
+        if resource_name_from_path is None:
+            return None
+
+        candidate = naming.to_plural(naming.to_snake_case(resource_name_from_path))
+        if array_field.lower() != candidate:
+            # Field name doesn't match resource pattern
+            return None
+
+    # Check for pagination metadata indicators
+    others = [p for p in properties if p != array_field]
+
+    pagination_indicators = {
+        "count",
+        "total",
+        "totalcount",
+        "total_count",
+        "totalelements",
+        "total_elements",
+        "page",
+        "pagenumber",
+        "page_number",
+        "currentpage",
+        "current_page",
+        "next",
+        "previous",
+        "prev",
+        "nextpage",
+        "prevpage",
+        "nextpageurl",
+        "prevpageurl",
+        "next_page_url",
+        "prev_page_url",
+        "next_page_token",
+        "nextpagetoken",
+        "cursor",
+        "nextcursor",
+        "next_cursor",
+        "nextlink",
+        "next_link",
+        "endcursor",
+        "hasmore",
+        "has_more",
+        "hasnextpage",
+        "haspreviouspage",
+        "pagesize",
+        "page_size",
+        "perpage",
+        "per_page",
+        "limit",
+        "size",
+        "pageinfo",
+        "page_info",
+        "pagination",
+        "links",
+        "meta",
+    }
+
+    # Check if any other property looks like pagination metadata
+    has_pagination_metadata = any(
+        prop.lower().replace("_", "").replace("-", "") in pagination_indicators for prop in others
+    )
+
+    # Either there is pagination metadata or the wrapper has just items + some other field which is likely an unrecognized metadata
+    if has_pagination_metadata or len(properties) <= 2:
+        return array_field
+
+    return None
+
+
+def _detect_externally_tagged_pattern(
+    schema: Mapping[str, Any], path: str, parent_ref: str | None
+) -> tuple[str, bool] | None:
+    """Detect externally tagged resource pattern.
+
+    Pattern: {ResourceName: [...]} or {resourceName: [...]}
+
+    Examples:
+        - GET /merchants -> {"Merchants": [...]}
+        - GET /users -> {"Users": [...]} or {"users": [...]}
+
+    """
+    properties = schema.get("properties", {})
+
+    if not properties:
+        return None
+
+    resource_name = naming.from_path(path)
+
+    if not resource_name:
+        return None
+
+    # For example, for `DataRequest`:
+    possible_names = {
+        # `datarequest`
+        resource_name.lower(),
+        # `datarequests`
+        naming.to_plural(resource_name.lower()),
+        # `data_request`
+        naming.to_snake_case(resource_name),
+    }
+    parent_names = set()
+    if parent_ref is not None:
+        maybe_resource_name = resource_name_from_ref(parent_ref)
+        parent_names.add(naming.to_plural(maybe_resource_name.lower()))
+        parent_names.add(naming.to_snake_case(maybe_resource_name))
+        possible_names = possible_names.union(parent_names)
+
+    for name, subschema in properties.items():
+        if name.lower() not in possible_names:
+            continue
+
+        if isinstance(subschema, dict) and "object" in get_type(subschema):
+            return name, name.lower() in parent_names
+
+    return None

schemathesis/specs/openapi/stateful/inference.py

@@ -0,0 +1,254 @@
+"""Inferencing connections between API operations.
+
+The current implementation extracts information from the `Location` header and
+generates OpenAPI links for exact and prefix matches.
+
+When a `Location` header points to `/users/123`, the inference:
+
+    1. Finds the exact match: `GET /users/{userId}`
+    2. Finds prefix matches: `GET /users/{userId}/posts`, `GET /users/{userId}/posts/{postId}`
+    3. Generates OpenAPI links with regex parameter extractors
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Mapping, Union
+from urllib.parse import urlsplit
+
+from werkzeug.exceptions import MethodNotAllowed, NotFound
+from werkzeug.routing import Map, MapAdapter, Rule
+
+from schemathesis.core.adapter import ResponsesContainer
+from schemathesis.core.transforms import encode_pointer
+from schemathesis.specs.openapi.stateful.links import SCHEMATHESIS_LINK_EXTENSION
+
+if TYPE_CHECKING:
+    from schemathesis.engine.observations import LocationHeaderEntry
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
+
+@dataclass(unsafe_hash=True)
+class OperationById:
+    """API operation identified by operationId."""
+
+    value: str
+    method: str
+    path: str
+
+    __slots__ = ("value", "method", "path")
+
+    def to_link_base(self) -> dict[str, Any]:
+        return {"operationId": self.value, SCHEMATHESIS_LINK_EXTENSION: {"is_inferred": True}}
+
+
+@dataclass(unsafe_hash=True)
+class OperationByRef:
+    """API operation identified by JSON reference path."""
+
+    value: str
+    method: str
+    path: str
+
+    __slots__ = ("value", "method", "path")
+
+    def to_link_base(self) -> dict[str, Any]:
+        return {"operationRef": self.value, SCHEMATHESIS_LINK_EXTENSION: {"is_inferred": True}}
+
+
+OperationReference = Union[OperationById, OperationByRef]
+# Method, path, response code, sorted path parameter names
+SeenLinkKey = tuple[str, str, int, tuple[str, ...]]
+
+
+@dataclass
+class MatchList:
+    """Results of matching a location path against API operation."""
+
+    exact: OperationReference
+    inexact: list[OperationReference]
+    parameters: Mapping[str, Any]
+
+    __slots__ = ("exact", "inexact", "parameters")
+
+
+@dataclass
+class LinkInferencer:
+    """Infer OpenAPI links from Location headers for stateful testing."""
+
+    _adapter: MapAdapter
+    # All API operations for prefix matching
+    _operations: list[OperationReference]
+    _base_url: str | None
+    _base_path: str
+    _links_keyword: str
+
+    __slots__ = ("_adapter", "_operations", "_base_url", "_base_path", "_links_keyword")
+
+    @classmethod
+    def from_schema(cls, schema: BaseOpenAPISchema) -> LinkInferencer:
+        # NOTE: Use `matchit` for routing in the future
+        rules = []
+        operations = []
+        for method, path, definition in schema._operation_iter():
+            operation_id = definition.get("operationId")
+            operation: OperationById | OperationByRef
+            if operation_id:
+                operation = OperationById(operation_id, method=method, path=path)
+            else:
+                encoded_path = encode_pointer(path)
+                operation = OperationByRef(f"#/paths/{encoded_path}/{method}", method=method, path=path)
+
+            operations.append(operation)
+
+            # Replace `{parameter}` with `<parameter>` as angle brackets are used for parameters in werkzeug
+            path = re.sub(r"\{([^}]+)\}", r"<\1>", path)
+            rules.append(Rule(path, endpoint=operation, methods=[method.upper()]))
+
+        return cls(
+            _adapter=Map(rules).bind("", ""),
+            _operations=operations,
+            _base_url=schema.config.base_url,
+            _base_path=schema.base_path,
+            _links_keyword=schema.adapter.links_keyword,
+        )
+
+    def match(self, path: str) -> tuple[OperationReference, Mapping[str, str]] | None:
+        """Match path to API operation and extract path parameters."""
+        try:
+            return self._adapter.match(path)
+        except (NotFound, MethodNotAllowed):
+            return None
+
+    def _build_links_from_matches(self, matches: MatchList) -> list[dict]:
+        """Build links from already-found matches."""
+        exact = self._build_link_from_match(matches.exact, matches.parameters)
+        parameters = exact["parameters"]
+        links = [exact]
+        for inexact in matches.inexact:
+            link = inexact.to_link_base()
+            # Parameter extraction is the same, only operations are different
+            link["parameters"] = parameters
+            links.append(link)
+        return links
+
+    def _find_matches_from_normalized_location(self, normalized_location: str) -> MatchList | None:
+        """Find matches from an already-normalized location."""
+        match = self.match(normalized_location)
+        if not match:
+            # It may happen that there is no match, but it is unlikely as the API assumed to return a valid Location
+            # that points to an existing API operation. In such cases, if they appear in practice the logic here could be extended
+            # to support partial matches
+            return None
+        exact, parameters = match
+        if not parameters:
+            # Links without parameters don't make sense
+            return None
+        matches = MatchList(exact=exact, inexact=[], parameters=parameters)
+
+        # Find prefix matches, excluding the exact match
+        # For example:
+        #
+        #  Location: /users/123 -> /users/{user_id} (exact match)
+        #  /users/{user_id}/posts , /users/{user_id}/posts/{post_id} (partial matches)
+        #
+        for candidate in self._operations:
+            if candidate == exact:
+                continue
+            if candidate.path.startswith(exact.path):
+                matches.inexact.append(candidate)
+
+        return matches
+
+    def _build_link_from_match(
+        self, operation: OperationById | OperationByRef, path_parameters: Mapping[str, Any]
+    ) -> dict:
+        link = operation.to_link_base()
+
+        # Build regex expressions to extract path parameters
+        parameters = {}
+        for name in path_parameters:
+            # Replace the target parameter with capture group and others with non-slash matcher
+            pattern = operation.path
+            for candidate in path_parameters:
+                if candidate == name:
+                    pattern = pattern.replace(f"{{{candidate}}}", "(.+)")
+                else:
+                    pattern = pattern.replace(f"{{{candidate}}}", "[^/]+")
+
+            parameters[name] = f"$response.header.Location#regex:{pattern}"
+
+        link["parameters"] = parameters
+
+        return link
+
+    def _normalize_location(self, location: str) -> str | None:
+        """Normalize location header, handling both relative and absolute URLs."""
+        location = location.strip()
+        if not location:
+            return None
+
+        # Check if it's an absolute URL
+        if location.startswith(("http://", "https://")):
+            if not self._base_url:
+                # Can't validate absolute URLs without base_url
+                return None
+
+            parsed = urlsplit(location)
+            base_parsed = urlsplit(self._base_url)
+
+            # Must match scheme, netloc, and start with the base path
+            if parsed.scheme != base_parsed.scheme or parsed.netloc != base_parsed.netloc:
+                return None
+
+            return self._strip_base_path_from_location(parsed.path)
+
+        # Relative URL - strip base path if present, otherwise use as-is
+        stripped = self._strip_base_path_from_location(location)
+        return stripped if stripped is not None else location
+
+    def _strip_base_path_from_location(self, path: str) -> str | None:
+        """Strip base path from location path if it starts with base path."""
+        base_path = self._base_path.rstrip("/")
+        if not path.startswith(base_path):
+            return None
+
+        # Strip the base path to get relative path
+        relative_path = path[len(base_path) :]
+        return relative_path if relative_path.startswith("/") else "/" + relative_path
+
+    def inject_links(self, responses: ResponsesContainer, entries: list[LocationHeaderEntry]) -> int:
+        # To avoid unnecessary work, we need to skip entries that we know will produce already inferred links
+        seen: set[SeenLinkKey] = set()
+        injected = 0
+
+        for entry in entries:
+            location = self._normalize_location(entry.value)
+            if location is None:
+                # Skip invalid/empty locations or absolute URLs that don't match base_url
+                continue
+
+            matches = self._find_matches_from_normalized_location(location)
+            if matches is None:
+                # Skip locations that don't match any API apiration
+                continue
+
+            key = (matches.exact.method, matches.exact.path, entry.status_code, tuple(sorted(matches.parameters)))
+            if key in seen:
+                # Skip duplicate link generation for same operation/status/parameters combination
+                continue
+            seen.add(key)
+            # Find the right bucket for the response status or create a new one
+            response = responses.find_by_status_code(entry.status_code)
+            links: dict[str, dict[str, dict]]
+            if response is None:
+                links = {}
+                responses.add(str(entry.status_code), {self._links_keyword: links})
+            else:
+                links = response.definition.setdefault(self._links_keyword, {})
+
+            for idx, link in enumerate(self._build_links_from_matches(matches)):
+                links[f"X-Inferred-Link-{idx}"] = link
+                injected += 1
+        return injected