schemathesis 3.39.15__py3-none-any.whl → 4.0.0__py3-none-any.whl

schemathesis/generation/{_hypothesis.py → hypothesis/examples.py}

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
 import os
-from functools import lru_cache, reduce
-from operator import or_
+from functools import lru_cache
 from typing import TYPE_CHECKING, TypeVar
 
 if TYPE_CHECKING:
@@ -29,7 +28,7 @@ def default_settings() -> settings:
 T = TypeVar("T")
 
 
-def get_single_example(strategy: st.SearchStrategy[T]) -> T:  # type: ignore[type-var]
+def generate_one(strategy: st.SearchStrategy[T]) -> T:  # type: ignore[type-var]
     examples: list[T] = []
     add_single_example(strategy, examples)
     return examples[0]
@@ -49,11 +48,3 @@ def add_single_example(strategy: st.SearchStrategy[T], examples: list[T]) -> Non
         example_generating_inner_function = seed(SCHEMATHESIS_BENCHMARK_SEED)(example_generating_inner_function)
 
     example_generating_inner_function()
-
-
-def combine_strategies(strategies: list[st.SearchStrategy] | tuple[st.SearchStrategy]) -> st.SearchStrategy:
-    """Combine a list of strategies into a single one.
-
-    If the input is `[a, b, c]`, then the result is equivalent to `a | b | c`.
-    """
-    return reduce(or_, strategies[1:], strategies[0])

schemathesis/generation/hypothesis/given.py

@@ -0,0 +1,66 @@
+"""Integrating `hypothesis.given` into Schemathesis."""
+
+from __future__ import annotations
+
+from inspect import getfullargspec
+from typing import TYPE_CHECKING, Any, Callable, NoReturn, Union
+
+from schemathesis.core.errors import IncorrectUsage
+from schemathesis.core.marks import Mark
+
+if TYPE_CHECKING:
+    from hypothesis.strategies import SearchStrategy
+
+
+__all__ = ["is_given_applied", "given_proxy", "merge_given_args", "GivenInput", "GivenArgsMark", "GivenKwargsMark"]
+
+EllipsisType = type(...)
+GivenInput = Union["SearchStrategy", EllipsisType]  # type: ignore[valid-type]
+
+GivenArgsMark = Mark[tuple](attr_name="given_args", default=())
+GivenKwargsMark = Mark[dict[str, Any]](attr_name="given_kwargs", default=dict)
+
+
+def is_given_applied(func: Callable) -> bool:
+    return GivenArgsMark.is_set(func) or GivenKwargsMark.is_set(func)
+
+
+def given_proxy(*args: GivenInput, **kwargs: GivenInput) -> Callable[[Callable], Callable]:
+    """Proxy Hypothesis strategies to ``hypothesis.given``."""
+
+    def wrapper(func: Callable) -> Callable:
+        if is_given_applied(func):
+
+            def wrapped_test(*_: Any, **__: Any) -> NoReturn:
+                raise IncorrectUsage(
+                    f"You have applied `given` to the `{func.__name__}` test more than once, which "
+                    "overrides the previous decorator. You need to pass all arguments to the same `given` call."
+                )
+
+            return wrapped_test
+
+        GivenArgsMark.set(func, args)
+        GivenKwargsMark.set(func, kwargs)
+        return func
+
+    return wrapper
+
+
+def merge_given_args(func: Callable, args: tuple, kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Merge positional arguments to ``@schema.given`` into a dictionary with keyword arguments.
+
+    Kwargs are modified inplace.
+    """
+    if args:
+        argspec = getfullargspec(func)
+        for name, strategy in zip(reversed([arg for arg in argspec.args if arg != "case"]), reversed(args)):
+            kwargs[name] = strategy
+    return kwargs
+
+
+def validate_given_args(func: Callable, args: tuple, kwargs: dict[str, Any]) -> Callable | None:
+    from hypothesis.core import is_invalid_test
+    from hypothesis.internal.reflection import get_signature
+
+    signature = get_signature(func)
+    return is_invalid_test(func, signature, args, kwargs)  # type: ignore

schemathesis/generation/hypothesis/reporting.py

@@ -0,0 +1,14 @@
+from contextlib import contextmanager
+from typing import Generator
+
+from hypothesis.reporting import with_reporter
+
+
+def ignore(_: str) -> None:
+    pass
+
+
+@contextmanager
+def ignore_hypothesis_output() -> Generator:
+    with with_reporter(ignore):  # type: ignore
+        yield

schemathesis/generation/hypothesis/strategies.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from functools import reduce
+from operator import or_
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from hypothesis import strategies as st
+
+
+def combine(strategies: list[st.SearchStrategy] | tuple[st.SearchStrategy]) -> st.SearchStrategy:
+    """Combine a list of strategies into a single one.
+
+    If the input is `[a, b, c]`, then the result is equivalent to `a | b | c`.
+    """
+    return reduce(or_, strategies[1:], strategies[0])

schemathesis/generation/meta.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from schemathesis.generation import GenerationMode
+
+
+class TestPhase(str, Enum):
+    __test__ = False
+
+    EXAMPLES = "examples"
+    COVERAGE = "coverage"
+    FUZZING = "fuzzing"
+
+
+class ComponentKind(str, Enum):
+    """Components that can be generated."""
+
+    QUERY = "query"
+    PATH_PARAMETERS = "path_parameters"
+    HEADERS = "headers"
+    COOKIES = "cookies"
+    BODY = "body"
+
+
+@dataclass
+class ComponentInfo:
+    """Information about how a specific component was generated."""
+
+    mode: GenerationMode
+
+    __slots__ = ("mode",)
+
+
+@dataclass
+class GeneratePhaseData:
+    """Metadata specific to generate phase."""
+
+
+@dataclass
+class ExplicitPhaseData:
+    """Metadata specific to explicit phase."""
+
+
+@dataclass
+class CoveragePhaseData:
+    """Metadata specific to coverage phase."""
+
+    description: str
+    location: str | None
+    parameter: str | None
+    parameter_location: str | None
+
+    __slots__ = ("description", "location", "parameter", "parameter_location")
+
+
+@dataclass
+class PhaseInfo:
+    """Phase-specific information."""
+
+    name: TestPhase
+    data: CoveragePhaseData | ExplicitPhaseData | GeneratePhaseData
+
+    __slots__ = ("name", "data")
+
+    @classmethod
+    def coverage(
+        cls,
+        description: str,
+        location: str | None = None,
+        parameter: str | None = None,
+        parameter_location: str | None = None,
+    ) -> PhaseInfo:
+        return cls(
+            name=TestPhase.COVERAGE,
+            data=CoveragePhaseData(
+                description=description, location=location, parameter=parameter, parameter_location=parameter_location
+            ),
+        )
+
+    @classmethod
+    def generate(cls) -> PhaseInfo:
+        return cls(name=TestPhase.FUZZING, data=GeneratePhaseData())
+
+
+@dataclass
+class GenerationInfo:
+    """Information about test case generation."""
+
+    time: float
+    mode: GenerationMode
+
+    __slots__ = ("time", "mode")
+
+
+@dataclass
+class CaseMetadata:
+    """Complete metadata for generated cases."""
+
+    generation: GenerationInfo
+    components: dict[ComponentKind, ComponentInfo]
+    phase: PhaseInfo
+
+    __slots__ = ("generation", "components", "phase")
+
+    def __init__(
+        self,
+        generation: GenerationInfo,
+        components: dict[ComponentKind, ComponentInfo],
+        phase: PhaseInfo,
+    ) -> None:
+        self.generation = generation
+        self.components = components
+        self.phase = phase

schemathesis/generation/metrics.py

@@ -0,0 +1,93 @@
+"""Support for Targeted Property-Based Testing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+from schemathesis.core.registries import Registry
+from schemathesis.core.transport import Response
+from schemathesis.generation.case import Case
+
+
+@dataclass
+class MetricContext:
+    """Context for evaluating a metric on a single test execution.
+
+    This object bundles together the test `case` that was sent and
+    the corresponding HTTP `response`. Metric functions receive an
+    instance of `MetricContext` to compute a numeric score.
+    """
+
+    case: Case
+    """Generated test case."""
+    response: Response
+    """The HTTP response returned by the server for this test case."""
+
+    __slots__ = ("case", "response")
+
+
+MetricFunction = Callable[[MetricContext], float]
+
+METRICS = Registry[MetricFunction]()
+
+
+def metric(func: MetricFunction) -> MetricFunction:
+    """Decorator to register a custom metric for targeted property-based testing.
+
+    Example:
+        ```python
+        import schemathesis
+
+        @schemathesis.metric
+        def response_size(ctx: schemathesis.MetricContext) -> float:
+            return float(len(ctx.response.content))
+        ```
+
+    """
+    return METRICS.register(func)
+
+
+@metric
+def response_time(ctx: MetricContext) -> float:
+    """Response time as a metric to maximize."""
+    return ctx.response.elapsed
+
+
+class MetricCollector:
+    """Collect multiple observations for metrics."""
+
+    __slots__ = ("metrics", "observations")
+
+    def __init__(self, metrics: list[MetricFunction] | None = None) -> None:
+        self.metrics = metrics or []
+        self.observations: dict[str, list[float]] = {metric.__name__: [] for metric in self.metrics}
+
+    def reset(self) -> None:
+        """Reset all collected observations."""
+        for metric in self.metrics:
+            self.observations[metric.__name__].clear()
+
+    def store(self, case: Case, response: Response) -> None:
+        """Calculate metrics & store them."""
+        ctx = MetricContext(case=case, response=response)
+        for metric in self.metrics:
+            self.observations[metric.__name__].append(metric(ctx))
+
+    def maximize(self) -> None:
+        """Give feedback to the Hypothesis engine, so it maximizes the aggregated metrics."""
+        import hypothesis
+
+        for metric in self.metrics:
+            # Currently aggregation is just a sum
+            value = sum(self.observations[metric.__name__])
+            hypothesis.target(value, label=metric.__name__)
+
+
+def maximize(metrics: Sequence[MetricFunction], case: Case, response: Response) -> None:
+    import hypothesis
+
+    ctx = MetricContext(case=case, response=response)
+    for metric in metrics:
+        value = metric(ctx)
+        hypothesis.target(value, label=metric.__name__)

schemathesis/generation/modes.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class GenerationMode(str, Enum):
+    """Defines what data Schemathesis generates for tests."""
+
+    # Generate data, that fits the API schema
+    POSITIVE = "positive"
+    # Doesn't fit the API schema
+    NEGATIVE = "negative"
+
+    @property
+    def is_positive(self) -> bool:
+        return self == GenerationMode.POSITIVE
+
+    @property
+    def is_negative(self) -> bool:
+        return self == GenerationMode.NEGATIVE

schemathesis/generation/overrides.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Iterator
+
+from schemathesis.config import ProjectConfig
+from schemathesis.core.transforms import diff
+from schemathesis.generation.meta import ComponentKind
+
+if TYPE_CHECKING:
+    from schemathesis.generation.case import Case
+    from schemathesis.schemas import APIOperation, Parameter
+
+
+@dataclass
+class Override:
+    """Overrides for various parts of a test case."""
+
+    query: dict[str, str]
+    headers: dict[str, str]
+    cookies: dict[str, str]
+    path_parameters: dict[str, str]
+
+    def items(self) -> Iterator[tuple[str, dict[str, str]]]:
+        for key, value in (
+            ("query", self.query),
+            ("headers", self.headers),
+            ("cookies", self.cookies),
+            ("path_parameters", self.path_parameters),
+        ):
+            if value:
+                yield key, value
+
+    @classmethod
+    def from_components(cls, components: dict[ComponentKind, StoredValue], case: Case) -> Override:
+        return Override(
+            **{
+                kind.value: get_component_diff(stored=stored, current=getattr(case, kind.value))
+                for kind, stored in components.items()
+            }
+        )
+
+
+def for_operation(config: ProjectConfig, *, operation: APIOperation) -> Override:
+    operation_config = config.operations.get_for_operation(operation)
+
+    output = Override(query={}, headers={}, cookies={}, path_parameters={})
+    groups = [
+        (output.query, operation.query),
+        (output.headers, operation.headers),
+        (output.cookies, operation.cookies),
+        (output.path_parameters, operation.path_parameters),
+    ]
+    for container, params in groups:
+        for param in params:
+            # Attempt to get the override from the operation-specific configuration.
+            value = None
+            if operation_config:
+                value = _get_override_value(param, operation_config.parameters)
+            # Fallback to the global project configuration.
+            if value is None:
+                value = _get_override_value(param, config.parameters)
+            if value is not None:
+                container[param.name] = value
+
+    return output
+
+
+def _get_override_value(param: Parameter, parameters: dict[str, Any]) -> Any:
+    key = param.name
+    full_key = f"{param.location}.{param.name}"
+    if key in parameters:
+        return parameters[key]
+    elif full_key in parameters:
+        return parameters[full_key]
+    return None
+
+
+@dataclass
+class StoredValue:
+    value: dict[str, Any] | None
+    is_generated: bool
+
+    __slots__ = ("value", "is_generated")
+
+
+def store_original_state(value: dict[str, Any] | None) -> dict[str, Any] | None:
+    if isinstance(value, Mapping):
+        return value.copy()
+    return value
+
+
+def get_component_diff(stored: StoredValue, current: dict[str, Any] | None) -> dict[str, Any]:
+    """Calculate difference between stored and current components."""
+    if not (current and stored.value):
+        return {}
+    if stored.is_generated:
+        return diff(stored.value, current)
+    return current
+
+
+def store_components(case: Case) -> dict[ComponentKind, StoredValue]:
+    """Store original component states for a test case."""
+    return {
+        kind: StoredValue(
+            value=store_original_state(getattr(case, kind.value)),
+            is_generated=bool(case.meta and kind in case.meta.components),
+        )
+        for kind in [
+            ComponentKind.QUERY,
+            ComponentKind.HEADERS,
+            ComponentKind.COOKIES,
+            ComponentKind.PATH_PARAMETERS,
+        ]
+    }

schemathesis/generation/stateful/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import hypothesis
+
+    from schemathesis.generation.stateful.state_machine import APIStateMachine
+
+__all__ = [
+    "APIStateMachine",
+]
+
+
+def __getattr__(name: str) -> type[APIStateMachine]:
+    if name == "APIStateMachine":
+        from schemathesis.generation.stateful.state_machine import APIStateMachine
+
+        return APIStateMachine
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+STATEFUL_TESTS_LABEL = "Stateful tests"
+
+
+def run_state_machine_as_test(
+    state_machine_factory: type[APIStateMachine], *, settings: hypothesis.settings | None = None
+) -> None:
+    """Run a state machine as a test.
+
+    It automatically adds the `_min_steps` argument if ``Hypothesis`` is recent enough.
+    """
+    from hypothesis.stateful import run_state_machine_as_test as _run_state_machine_as_test
+
+    __tracebackhide__ = True
+
+    return _run_state_machine_as_test(state_machine_factory, settings=settings, _min_steps=2)