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

schemathesis/engine/recorder.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import base64
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Iterator, cast
+
+from schemathesis.core.failures import Failure
+from schemathesis.core.transport import Response
+from schemathesis.engine import Status
+from schemathesis.generation.case import Case
+
+if TYPE_CHECKING:
+    import requests
+
+    from schemathesis.generation.stateful.state_machine import Transition
+
+
+@dataclass
+class ScenarioRecorder:
+    """Tracks and organizes all data related to a logical block of testing.
+
+    Records test cases, their hierarchy, API interactions, and results of checks performed during execution.
+    """
+
+    # Human-readable label
+    label: str
+
+    # Recorded test cases
+    cases: dict[str, CaseNode]
+    # Results of checks categorized by test case ID
+    checks: dict[str, list[CheckNode]]
+    # Network interactions by test case ID
+    interactions: dict[str, Interaction]
+    __slots__ = ("label", "status", "roots", "cases", "checks", "interactions")
+
+    def __init__(self, *, label: str) -> None:
+        self.label = label
+        self.cases = {}
+        self.checks = {}
+        self.interactions = {}
+
+    def record_case(
+        self, *, parent_id: str | None, case: Case, transition: Transition | None, is_transition_applied: bool
+    ) -> None:
+        """Record a test case and its relationship to a parent, if applicable."""
+        self.cases[case.id] = CaseNode(
+            value=case,
+            parent_id=parent_id,
+            transition=transition,
+            is_transition_applied=is_transition_applied,
+        )
+
+    def record_response(self, *, case_id: str, response: Response) -> None:
+        """Record the API response for a given test case."""
+        request = Request.from_prepared_request(response.request)
+        self.interactions[case_id] = Interaction(request=request, response=response)
+
+    def record_request(self, *, case_id: str, request: requests.PreparedRequest) -> None:
+        """Record a network-level error for a given test case."""
+        self.interactions[case_id] = Interaction(request=Request.from_prepared_request(request), response=None)
+
+    def record_check_failure(self, *, name: str, case_id: str, code_sample: str, failure: Failure) -> None:
+        """Record a failure of a check for a given test case."""
+        self.checks.setdefault(case_id, []).append(
+            CheckNode(
+                name=name,
+                status=Status.FAILURE,
+                failure_info=CheckFailureInfo(code_sample=code_sample, failure=failure),
+            )
+        )
+
+    def record_check_success(self, *, name: str, case_id: str) -> None:
+        """Record a successful pass of a check for a given test case."""
+        self.checks.setdefault(case_id, []).append(CheckNode(name=name, status=Status.SUCCESS, failure_info=None))
+
+    def find_failure_data(self, *, parent_id: str, failure: Failure) -> FailureData:
+        """Retrieve the relevant test case & interaction data for a failure.
+
+        It may happen that a failure comes from a different test case if a check generated some additional
+        test cases & interactions.
+        """
+        case_id = failure.case_id or parent_id
+        case = self.cases[case_id].value
+        request = self.interactions[case_id].request
+        response = self.interactions[case_id].response
+        assert isinstance(response, Response)
+        headers = {key: value[0] for key, value in request.headers.items()}
+        return FailureData(case=case, headers=headers, verify=response.verify)
+
+    def find_parent(self, *, case_id: str) -> Case | None:
+        """Find the parent case of a given test case, if it exists."""
+        case = self.cases.get(case_id)
+        if case is not None and case.parent_id is not None:
+            parent = self.cases.get(case.parent_id)
+            # The recorder state should always be consistent
+            assert parent is not None, "Parent does not exist"
+            return parent.value
+        return None
+
+    def find_related(self, *, case_id: str) -> Iterator[Case]:
+        """Iterate over all cases in the tree, starting from the root."""
+        seen = {case_id}
+
+        # First, find the root by going up
+        current_id = case_id
+        while True:
+            current_node = self.cases.get(current_id)
+            if current_node is None or current_node.parent_id is None:
+                root_id = current_id
+                break
+            current_id = current_node.parent_id
+
+        # Then traverse the whole tree from root
+        def traverse(node_id: str) -> Iterator[Case]:
+            # Get all children
+            for case_id, node in self.cases.items():
+                if node.parent_id == node_id and case_id not in seen:
+                    seen.add(case_id)
+                    yield node.value
+                    # Recurse into children
+                    yield from traverse(case_id)
+
+        # Start traversal from root
+        root_node = self.cases.get(root_id)
+        if root_node and root_id not in seen:
+            seen.add(root_id)
+            yield root_node.value
+        yield from traverse(root_id)
+
+    def find_response(self, *, case_id: str) -> Response | None:
+        """Retrieve the API response for a given test case, if available."""
+        interaction = self.interactions.get(case_id)
+        if interaction is None or interaction.response is None:
+            return None
+        return interaction.response
+
+
+@dataclass
+class CaseNode:
+    """Represents a test case and its parent-child relationship."""
+
+    value: Case
+    parent_id: str | None
+    # Transition may be absent if `parent_id` is present for cases when a case is derived inside a check
+    # and outside of the implemented transition logic (e.g. Open API links)
+    transition: Transition | None
+    is_transition_applied: bool
+
+    __slots__ = ("value", "parent_id", "transition", "is_transition_applied")
+
+
+@dataclass
+class CheckNode:
+    name: str
+    status: Status
+    failure_info: CheckFailureInfo | None
+
+    __slots__ = ("name", "status", "failure_info")
+
+
+@dataclass
+class CheckFailureInfo:
+    code_sample: str
+    failure: Failure
+
+    __slots__ = ("code_sample", "failure")
+
+
+def serialize_payload(payload: bytes) -> str:
+    return base64.b64encode(payload).decode()
+
+
+@dataclass(repr=False)
+class Request:
+    """Request data extracted from `Case`."""
+
+    method: str
+    uri: str
+    body: bytes | None
+    body_size: int | None
+    headers: dict[str, list[str]]
+
+    __slots__ = ("method", "uri", "body", "body_size", "headers", "_encoded_body_cache")
+
+    def __init__(
+        self,
+        method: str,
+        uri: str,
+        body: bytes | None,
+        body_size: int | None,
+        headers: dict[str, list[str]],
+    ):
+        self.method = method
+        self.uri = uri
+        self.body = body
+        self.body_size = body_size
+        self.headers = headers
+        self._encoded_body_cache: str | None = None
+
+    @classmethod
+    def from_prepared_request(cls, prepared: requests.PreparedRequest) -> Request:
+        """A prepared request version is already stored in `requests.Response`."""
+        body = prepared.body
+
+        if isinstance(body, str):
+            # can be a string for `application/x-www-form-urlencoded`
+            body = body.encode("utf-8")
+
+        # these values have `str` type at this point
+        uri = cast(str, prepared.url)
+        method = cast(str, prepared.method)
+        return cls(
+            uri=uri,
+            method=method,
+            headers={key: [value] for (key, value) in prepared.headers.items()},
+            body=body,
+            body_size=len(body) if body is not None else None,
+        )
+
+    @property
+    def encoded_body(self) -> str | None:
+        if self.body is not None:
+            if self._encoded_body_cache is None:
+                self._encoded_body_cache = serialize_payload(self.body)
+            return self._encoded_body_cache
+        return None
+
+
+@dataclass
+class Interaction:
+    """Represents a single interaction with the tested application."""
+
+    request: Request
+    response: Response | None
+    timestamp: float
+
+    __slots__ = ("request", "response", "timestamp")
+
+    def __init__(self, request: Request, response: Response | None) -> None:
+        self.request = request
+        self.response = response
+        self.timestamp = time.time()
+
+
+@dataclass
+class FailureData:
+    """Details about a test failure, including the case and its context."""
+
+    case: Case
+    headers: dict[str, str]
+    verify: bool
+
+    __slots__ = ("case", "headers", "verify")

schemathesis/errors.py

@@ -0,0 +1,47 @@
+"""Public Schemathesis errors."""
+
+from schemathesis.core.errors import (
+    HookError,
+    IncorrectUsage,
+    InfiniteRecursiveReference,
+    InternalError,
+    InvalidHeadersExample,
+    InvalidRateLimit,
+    InvalidRegexPattern,
+    InvalidRegexType,
+    InvalidSchema,
+    InvalidStateMachine,
+    InvalidTransition,
+    LoaderError,
+    NoLinksFound,
+    OperationNotFound,
+    SchemathesisError,
+    SerializationError,
+    SerializationNotPossible,
+    TransitionValidationError,
+    UnboundPrefix,
+    UnresolvableReference,
+)
+
+__all__ = [
+    "HookError",
+    "IncorrectUsage",
+    "InfiniteRecursiveReference",
+    "InternalError",
+    "InvalidHeadersExample",
+    "InvalidRateLimit",
+    "InvalidRegexPattern",
+    "InvalidRegexType",
+    "InvalidSchema",
+    "InvalidStateMachine",
+    "InvalidTransition",
+    "LoaderError",
+    "OperationNotFound",
+    "NoLinksFound",
+    "SchemathesisError",
+    "SerializationError",
+    "SerializationNotPossible",
+    "TransitionValidationError",
+    "UnboundPrefix",
+    "UnresolvableReference",
+]

schemathesis/filters.py

@@ -0,0 +1,395 @@
+"""Filtering system that allows users to filter API operations based on certain criteria."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from functools import partial
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any, Callable, List, Protocol, Union
+
+from schemathesis.core.errors import IncorrectUsage
+from schemathesis.core.transforms import resolve_pointer
+
+if TYPE_CHECKING:
+    from schemathesis.schemas import APIOperation
+
+
+class HasAPIOperation(Protocol):
+    operation: APIOperation
+
+
+MatcherFunc = Callable[[HasAPIOperation], bool]
+FilterValue = Union[str, List[str]]
+RegexValue = Union[str, re.Pattern]
+ERROR_EXPECTED_AND_REGEX = "Passing expected value and regex simultaneously is not allowed"
+ERROR_EMPTY_FILTER = "Filter can not be empty"
+ERROR_FILTER_EXISTS = "Filter already exists"
+
+
+@dataclass(repr=False, frozen=True)
+class Matcher:
+    """Encapsulates matching logic by various criteria."""
+
+    func: Callable[..., bool] = field(hash=False, compare=False)
+    # A short description of a matcher. Primarily exists for debugging purposes
+    label: str = field(hash=False, compare=False)
+    # Compare & hash matchers by a pre-computed hash value
+    _hash: int
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self.label}>"
+
+    @classmethod
+    def for_function(cls, func: MatcherFunc) -> Matcher:
+        """Matcher that uses the given function for matching operations."""
+        return cls(func, label=func.__name__, _hash=hash(func))
+
+    @classmethod
+    def for_value(cls, attribute: str, expected: FilterValue) -> Matcher:
+        """Matcher that checks whether the specified attribute has the expected value."""
+        if isinstance(expected, list):
+            func = partial(by_value_list, attribute=attribute, expected=expected)
+        else:
+            func = partial(by_value, attribute=attribute, expected=expected)
+        label = f"{attribute}={expected!r}"
+        return cls(func, label=label, _hash=hash(label))
+
+    @classmethod
+    def for_regex(cls, attribute: str, regex: RegexValue) -> Matcher:
+        """Matcher that checks whether the specified attribute has the provided regex."""
+        if isinstance(regex, str):
+            flags: re.RegexFlag | int
+            if attribute == "method":
+                flags = re.IGNORECASE
+            else:
+                flags = 0
+            regex = re.compile(regex, flags=flags)
+        func = partial(by_regex, attribute=attribute, regex=regex)
+        label = f"{attribute}_regex={regex!r}"
+        return cls(func, label=label, _hash=hash(label))
+
+    def match(self, ctx: HasAPIOperation) -> bool:
+        """Whether matcher matches the given operation."""
+        return self.func(ctx)
+
+
+def get_operation_attribute(operation: APIOperation, attribute: str) -> str | list[str] | None:
+    if attribute == "tag":
+        return operation.tags
+    if attribute == "operation_id":
+        return operation.definition.raw.get("operationId")
+    # Just uppercase `method`
+    value = getattr(operation, attribute)
+    if attribute == "method":
+        value = value.upper()
+    return value
+
+
+def by_value(ctx: HasAPIOperation, attribute: str, expected: str) -> bool:
+    value = get_operation_attribute(ctx.operation, attribute)
+    if value is None:
+        return False
+    if isinstance(value, list):
+        return any(entry == expected for entry in value)
+    return value == expected
+
+
+def by_value_list(ctx: HasAPIOperation, attribute: str, expected: list[str]) -> bool:
+    value = get_operation_attribute(ctx.operation, attribute)
+    if value is None:
+        return False
+    if isinstance(value, list):
+        return any(entry in expected for entry in value)
+    return value in expected
+
+
+def by_regex(ctx: HasAPIOperation, attribute: str, regex: re.Pattern) -> bool:
+    value = get_operation_attribute(ctx.operation, attribute)
+    if value is None:
+        return False
+    if isinstance(value, list):
+        return any(bool(regex.search(entry)) for entry in value)
+    return bool(regex.search(value))
+
+
+@dataclass(repr=False, frozen=True)
+class Filter:
+    """Match API operations against a list of matchers."""
+
+    matchers: tuple[Matcher, ...]
+
+    __slots__ = ("matchers",)
+
+    def __repr__(self) -> str:
+        inner = " && ".join(matcher.label for matcher in self.matchers)
+        return f"<{self.__class__.__name__}: [{inner}]>"
+
+    def match(self, ctx: HasAPIOperation) -> bool:
+        """Whether the operation matches the filter.
+
+        Returns `True` only if all matchers matched.
+        """
+        return all(matcher.match(ctx) for matcher in self.matchers)
+
+
+@dataclass
+class FilterSet:
+    """Combines multiple filters to apply inclusion and exclusion rules on API operations."""
+
+    _includes: set[Filter]
+    _excludes: set[Filter]
+
+    __slots__ = ("_includes", "_excludes")
+
+    def __init__(self, _includes: set[Filter] | None = None, _excludes: set[Filter] | None = None) -> None:
+        self._includes = _includes or set()
+        self._excludes = _excludes or set()
+
+    def clone(self) -> FilterSet:
+        return FilterSet(_includes=self._includes.copy(), _excludes=self._excludes.copy())
+
+    def applies_to(self, operation: APIOperation) -> bool:
+        return self.match(SimpleNamespace(operation=operation))
+
+    def match(self, ctx: HasAPIOperation) -> bool:
+        """Determines whether the given operation should be included based on the defined filters.
+
+        Returns True if the operation:
+          - matches at least one INCLUDE filter OR no INCLUDE filters defined;
+          - does not match any EXCLUDE filter;
+        False otherwise.
+        """
+        # Exclude early if the operation is excluded by at least one EXCLUDE filter
+        for filter_ in self._excludes:
+            if filter_.match(ctx):
+                return False
+        if not self._includes:
+            # No includes - nothing to filter out, include the operation
+            return True
+        # Otherwise check if the operation is included by at least one INCLUDE filter
+        return any(filter_.match(ctx) for filter_ in self._includes)
+
+    def is_empty(self) -> bool:
+        """Whether the filter set does not contain any filters."""
+        return not self._includes and not self._excludes
+
+    def clear(self) -> None:
+        self._includes.clear()
+        self._excludes.clear()
+
+    def include(
+        self,
+        func: MatcherFunc | None = None,
+        *,
+        name: FilterValue | None = None,
+        name_regex: RegexValue | None = None,
+        method: FilterValue | None = None,
+        method_regex: RegexValue | None = None,
+        path: FilterValue | None = None,
+        path_regex: RegexValue | None = None,
+        tag: FilterValue | None = None,
+        tag_regex: RegexValue | None = None,
+        operation_id: FilterValue | None = None,
+        operation_id_regex: RegexValue | None = None,
+    ) -> None:
+        """Add a new INCLUDE filter."""
+        self._add_filter(
+            True,
+            func=func,
+            name=name,
+            name_regex=name_regex,
+            method=method,
+            method_regex=method_regex,
+            path=path,
+            path_regex=path_regex,
+            tag=tag,
+            tag_regex=tag_regex,
+            operation_id=operation_id,
+            operation_id_regex=operation_id_regex,
+        )
+
+    def exclude(
+        self,
+        func: MatcherFunc | None = None,
+        *,
+        name: FilterValue | None = None,
+        name_regex: RegexValue | None = None,
+        method: FilterValue | None = None,
+        method_regex: RegexValue | None = None,
+        path: FilterValue | None = None,
+        path_regex: RegexValue | None = None,
+        tag: FilterValue | None = None,
+        tag_regex: RegexValue | None = None,
+        operation_id: FilterValue | None = None,
+        operation_id_regex: RegexValue | None = None,
+    ) -> None:
+        """Add a new EXCLUDE filter."""
+        self._add_filter(
+            False,
+            func=func,
+            name=name,
+            name_regex=name_regex,
+            method=method,
+            method_regex=method_regex,
+            path=path,
+            path_regex=path_regex,
+            tag=tag,
+            tag_regex=tag_regex,
+            operation_id=operation_id,
+            operation_id_regex=operation_id_regex,
+        )
+
+    def _add_filter(
+        self,
+        include: bool,
+        *,
+        func: MatcherFunc | None = None,
+        name: FilterValue | None = None,
+        name_regex: RegexValue | None = None,
+        method: FilterValue | None = None,
+        method_regex: RegexValue | None = None,
+        path: FilterValue | None = None,
+        path_regex: RegexValue | None = None,
+        tag: FilterValue | None = None,
+        tag_regex: RegexValue | None = None,
+        operation_id: FilterValue | None = None,
+        operation_id_regex: RegexValue | None = None,
+    ) -> None:
+        matchers = []
+        if func is not None:
+            matchers.append(Matcher.for_function(func))
+        for attribute, expected, regex in (
+            ("label", name, name_regex),
+            ("method", method, method_regex),
+            ("path", path, path_regex),
+            ("tag", tag, tag_regex),
+            ("operation_id", operation_id, operation_id_regex),
+        ):
+            if expected is not None and regex is not None:
+                # To match anything the regex should match the expected value, hence passing them together is useless
+                raise IncorrectUsage(ERROR_EXPECTED_AND_REGEX)
+            if expected is not None:
+                if attribute == "method":
+                    expected = _normalize_method(expected)
+                matchers.append(Matcher.for_value(attribute, expected))
+            if regex is not None:
+                matchers.append(Matcher.for_regex(attribute, regex))
+
+        if not matchers:
+            raise IncorrectUsage(ERROR_EMPTY_FILTER)
+        filter_ = Filter(matchers=tuple(matchers))
+        if filter_ in self._includes or filter_ in self._excludes:
+            raise IncorrectUsage(ERROR_FILTER_EXISTS)
+        if include:
+            self._includes.add(filter_)
+        else:
+            self._excludes.add(filter_)
+
+
+def _normalize_method(value: FilterValue) -> FilterValue:
+    if isinstance(value, list):
+        return [item.upper() for item in value]
+    return value.upper()
+
+
+def attach_filter_chain(
+    target: Callable,
+    attribute: str,
+    filter_func: Callable[..., None],
+) -> None:
+    """Attach a filtering function to an object, which allows chaining of filter criteria.
+
+    For example:
+
+    >>> def auth(): ...
+    >>> filter_set = FilterSet()
+    >>> attach_filter_chain(auth, "apply_to", filter_set.include)
+    >>> auth.apply_to(method="GET", path="/users/")
+
+    This will add a new `apply_to` method to `auth` that matches only the `GET /users/` operation.
+    """
+
+    def proxy(
+        func: MatcherFunc | None = None,
+        *,
+        name: FilterValue | None = None,
+        name_regex: str | None = None,
+        method: FilterValue | None = None,
+        method_regex: str | None = None,
+        tag: FilterValue | None = None,
+        tag_regex: RegexValue | None = None,
+        path: FilterValue | None = None,
+        path_regex: str | None = None,
+        operation_id: FilterValue | None = None,
+        operation_id_regex: RegexValue | None = None,
+    ) -> Callable:
+        __tracebackhide__ = True
+        filter_func(
+            func=func,
+            name=name,
+            name_regex=name_regex,
+            method=method,
+            method_regex=method_regex,
+            tag=tag,
+            tag_regex=tag_regex,
+            path=path,
+            path_regex=path_regex,
+            operation_id=operation_id,
+            operation_id_regex=operation_id_regex,
+        )
+        return target
+
+    proxy.__qualname__ = attribute
+    proxy.__name__ = attribute
+
+    setattr(target, attribute, proxy)
+
+
+def is_deprecated(ctx: HasAPIOperation) -> bool:
+    return ctx.operation.definition.raw.get("deprecated") is True
+
+
+def parse_expression(expression: str) -> tuple[str, str, Any]:
+    expression = expression.strip()
+
+    # Find the operator
+    for op in ("==", "!="):
+        try:
+            pointer, value = expression.split(op, 1)
+            break
+        except ValueError:
+            continue
+    else:
+        raise ValueError(f"Invalid expression: {expression}")
+
+    pointer = pointer.strip()
+    value = value.strip()
+    if not pointer or not value:
+        raise ValueError(f"Invalid expression: {expression}")
+    # Parse the JSON value
+    try:
+        return pointer, op, json.loads(value)
+    except json.JSONDecodeError:
+        # If it's not valid JSON, treat it as a string
+        return pointer, op, value
+
+
+def expression_to_filter_function(expression: str) -> Callable[[HasAPIOperation], bool]:
+    pointer, op, value = parse_expression(expression)
+
+    if op == "==":
+
+        def filter_function(ctx: HasAPIOperation) -> bool:
+            definition = ctx.operation.definition.raw
+            resolved = resolve_pointer(definition, pointer)
+            return resolved == value
+    else:
+
+        def filter_function(ctx: HasAPIOperation) -> bool:
+            definition = ctx.operation.definition.raw
+            resolved = resolve_pointer(definition, pointer)
+            return resolved != value
+
+    return filter_function