schemathesis 4.0.0a11__py3-none-any.whl → 4.0.0a12__py3-none-any.whl

schemathesis/__init__.py

@@ -1,44 +1,47 @@
 from __future__ import annotations
 
-from schemathesis import auths, contrib, engine, errors, graphql, hooks, openapi, pytest, python
+from schemathesis import errors, graphql, openapi, pytest
+from schemathesis.auths import AuthContext, auth
 from schemathesis.checks import CheckContext, CheckFunction, check
-from schemathesis.core.output import sanitization
 from schemathesis.core.transport import Response
 from schemathesis.core.version import SCHEMATHESIS_VERSION
 from schemathesis.generation import GenerationMode
 from schemathesis.generation.case import Case
-from schemathesis.generation.targets import TargetContext, TargetFunction, target
-from schemathesis.hooks import HookContext
+from schemathesis.generation.metrics import MetricContext, MetricFunction, metric
+from schemathesis.hooks import HookContext, hook
 from schemathesis.schemas import BaseSchema
+from schemathesis.transport import SerializationContext, serializer
 
 __version__ = SCHEMATHESIS_VERSION
 
-# Public API
-auth = auths.GLOBAL_AUTH_STORAGE
-hook = hooks.register
-
 __all__ = [
+    "__version__",
+    # Core data structures
     "Case",
-    "CheckContext",
-    "CheckFunction",
-    "GenerationMode",
     "Response",
-    "TargetContext",
-    "TargetFunction",
-    "HookContext",
+    "GenerationMode",
     "BaseSchema",
-    "__version__",
-    "auth",
-    "check",
-    "contrib",
-    "engine",
+    # Public errors
     "errors",
-    "graphql",
-    "hook",
-    "hooks",
+    # Spec or usage specific namespaces
     "openapi",
+    "graphql",
     "pytest",
-    "python",
-    "sanitization",
-    "target",
+    # Hooks
+    "hook",
+    "HookContext",
+    # Checks
+    "check",
+    "CheckContext",
+    "CheckFunction",
+    # Auth
+    "auth",
+    "AuthContext",
+    # Targeted Property-based Testing
+    "metric",
+    "MetricContext",
+    "MetricFunction",
+    # Serialization
+    "serializer",
+    "SerializationContext",
 ]

schemathesis/auths.py

@@ -34,14 +34,34 @@ Auth = TypeVar("Auth")
 
 @dataclass
 class AuthContext:
-    """Holds state relevant for the authentication process.
+    """Runtime context passed to authentication providers during token generation.
+
+    Provides access to the current API operation and application instance when
+    auth providers need operation-specific tokens or application state.
+
+    Example:
+        ```python
+        @schemathesis.auth()
+        class ContextAwareAuth:
+            def get(self, case, context):
+                # Access operation details
+                if "/admin/" in context.operation.path:
+                    return self.get_admin_token()
+                else:
+                    return self.get_user_token()
+
+            def set(self, case, data, context):
+                case.headers = {"Authorization": f"Bearer {data}"}
+        ```
 
-    :ivar APIOperation operation: API operation that is currently being processed.
-    :ivar app: Optional Python application if the WSGI / ASGI integration is used.
     """
 
     operation: APIOperation
+    """API operation currently being processed for authentication."""
     app: Any | None
+    """Python application instance (ASGI/WSGI app) when using app integration, `None` otherwise."""
+
+    __slots__ = ("operation", "app")
 
 
 CacheKeyFunction = Callable[["Case", "AuthContext"], Union[str, int]]
@@ -289,7 +309,7 @@ class AuthStorage(Generic[Auth]):
     ) -> FilterableRegisterAuth | FilterableApplyAuth:
         if provider_class is not None:
             return self.apply(provider_class, refresh_interval=refresh_interval, cache_by_key=cache_by_key)
-        return self.register(refresh_interval=refresh_interval, cache_by_key=cache_by_key)
+        return self.auth(refresh_interval=refresh_interval, cache_by_key=cache_by_key)
 
     def set_from_requests(self, auth: requests.auth.AuthBase) -> FilterableRequestsAuth:
         """Use `requests` auth instance as an auth provider."""
@@ -333,30 +353,12 @@ class AuthStorage(Generic[Auth]):
             provider = SelectiveAuthProvider(provider, filter_set)
         self.providers.append(provider)
 
-    def register(
+    def auth(
         self,
         *,
         refresh_interval: int | None = DEFAULT_REFRESH_INTERVAL,
         cache_by_key: CacheKeyFunction | None = None,
     ) -> FilterableRegisterAuth:
-        """Register a new auth provider.
-
-        .. code-block:: python
-
-            @schemathesis.auth()
-            class TokenAuth:
-                def get(self, context):
-                    response = requests.post(
-                        "https://example.schemathesis.io/api/token/",
-                        json={"username": "demo", "password": "test"},
-                    )
-                    data = response.json()
-                    return data["access_token"]
-
-                def set(self, case, data, context):
-                    # Modify `case` the way you need
-                    case.headers = {"Authorization": f"Bearer {data}"}
-        """
         filter_set = FilterSet()
 
         def wrapper(provider_class: type[AuthProvider]) -> type[AuthProvider]:
@@ -451,5 +453,44 @@ def set_on_case(case: Case, context: AuthContext, auth_storage: AuthStorage | No
 
 # Global auth API
 GLOBAL_AUTH_STORAGE: AuthStorage = AuthStorage()
-register = GLOBAL_AUTH_STORAGE.register
 unregister = GLOBAL_AUTH_STORAGE.unregister
+
+
+def auth(
+    *,
+    refresh_interval: int | None = DEFAULT_REFRESH_INTERVAL,
+    cache_by_key: CacheKeyFunction | None = None,
+) -> FilterableRegisterAuth:
+    """Register a dynamic authentication provider for APIs with expiring tokens.
+
+    Args:
+        refresh_interval: Seconds between token refreshes. Default is `300`. Use `None` to disable caching
+        cache_by_key: Function to generate cache keys for different auth contexts (e.g., OAuth scopes)
+
+    Example:
+        ```python
+        import schemathesis
+        import requests
+
+        @schemathesis.auth()
+        class TokenAuth:
+            def get(self, case, context):
+                \"\"\"Fetch fresh authentication token\"\"\"
+                response = requests.post(
+                    "http://localhost:8000/auth/token",
+                    json={"username": "demo", "password": "test"}
+                )
+                return response.json()["access_token"]
+
+            def set(self, case, data, context):
+                \"\"\"Apply token to test case headers\"\"\"
+                case.headers = case.headers or {}
+                case.headers["Authorization"] = f"Bearer {data}"
+        ```
+
+    """
+    return GLOBAL_AUTH_STORAGE.auth(refresh_interval=refresh_interval, cache_by_key=cache_by_key)
+
+
+auth.__dict__ = GLOBAL_AUTH_STORAGE.auth.__dict__
+auth.set_from_requests = GLOBAL_AUTH_STORAGE.set_from_requests  # type: ignore[attr-defined]

schemathesis/checks.py

@@ -26,20 +26,21 @@ CheckFunction = Callable[["CheckContext", "Response", "Case"], Optional[bool]]
 
 
 class CheckContext:
-    """Context for Schemathesis checks.
+    """Runtime context passed to validation check functions during API testing.
 
-    Provides access to broader test execution data beyond individual test cases.
+    Provides access to configuration for currently checked endpoint.
     """
 
-    override: Override | None
-    auth: tuple[str, str] | None
-    headers: CaseInsensitiveDict | None
+    _override: Override | None
+    _auth: tuple[str, str] | None
+    _headers: CaseInsensitiveDict | None
     config: ChecksConfig
-    transport_kwargs: dict[str, Any] | None
-    recorder: ScenarioRecorder | None
-    checks: list[CheckFunction]
+    """Configuration settings for validation checks."""
+    _transport_kwargs: dict[str, Any] | None
+    _recorder: ScenarioRecorder | None
+    _checks: list[CheckFunction]
 
-    __slots__ = ("override", "auth", "headers", "config", "transport_kwargs", "recorder", "checks")
+    __slots__ = ("_override", "_auth", "_headers", "config", "_transport_kwargs", "_recorder", "_checks")
 
     def __init__(
         self,
@@ -50,55 +51,78 @@ class CheckContext:
         transport_kwargs: dict[str, Any] | None,
         recorder: ScenarioRecorder | None = None,
     ) -> None:
-        self.override = override
-        self.auth = auth
-        self.headers = headers
+        self._override = override
+        self._auth = auth
+        self._headers = headers
         self.config = config
-        self.transport_kwargs = transport_kwargs
-        self.recorder = recorder
-        self.checks = []
+        self._transport_kwargs = transport_kwargs
+        self._recorder = recorder
+        self._checks = []
         for check in CHECKS.get_all():
             name = check.__name__
             if self.config.get_by_name(name=name).enabled:
-                self.checks.append(check)
+                self._checks.append(check)
         if self.config.max_response_time.enabled:
-            self.checks.append(max_response_time)
+            self._checks.append(max_response_time)
 
-    def find_parent(self, *, case_id: str) -> Case | None:
-        if self.recorder is not None:
-            return self.recorder.find_parent(case_id=case_id)
+    def _find_parent(self, *, case_id: str) -> Case | None:
+        if self._recorder is not None:
+            return self._recorder.find_parent(case_id=case_id)
         return None
 
-    def find_related(self, *, case_id: str) -> Iterator[Case]:
-        if self.recorder is not None:
-            yield from self.recorder.find_related(case_id=case_id)
+    def _find_related(self, *, case_id: str) -> Iterator[Case]:
+        if self._recorder is not None:
+            yield from self._recorder.find_related(case_id=case_id)
 
-    def find_response(self, *, case_id: str) -> Response | None:
-        if self.recorder is not None:
-            return self.recorder.find_response(case_id=case_id)
+    def _find_response(self, *, case_id: str) -> Response | None:
+        if self._recorder is not None:
+            return self._recorder.find_response(case_id=case_id)
         return None
 
-    def record_case(self, *, parent_id: str, case: Case) -> None:
-        if self.recorder is not None:
-            self.recorder.record_case(parent_id=parent_id, transition=None, case=case)
+    def _record_case(self, *, parent_id: str, case: Case) -> None:
+        if self._recorder is not None:
+            self._recorder.record_case(parent_id=parent_id, transition=None, case=case)
 
-    def record_response(self, *, case_id: str, response: Response) -> None:
-        if self.recorder is not None:
-            self.recorder.record_response(case_id=case_id, response=response)
+    def _record_response(self, *, case_id: str, response: Response) -> None:
+        if self._recorder is not None:
+            self._recorder.record_response(case_id=case_id, response=response)
 
 
 CHECKS = Registry[CheckFunction]()
-check = CHECKS.register
+
+
+def check(func: CheckFunction) -> CheckFunction:
+    """Register a custom validation check to run against API responses.
+
+    Args:
+        func: Function that takes `(ctx: CheckContext, response: Response, case: Case)` and raises `AssertionError` on validation failure
+
+    Example:
+        ```python
+        import schemathesis
+
+        @schemathesis.check
+        def check_cors_headers(ctx, response, case):
+            \"\"\"Verify CORS headers are present\"\"\"
+            if "Access-Control-Allow-Origin" not in response.headers:
+                raise AssertionError("Missing CORS headers")
+        ```
+
+    """
+    return CHECKS.register(func)
 
 
 @check
 def not_a_server_error(ctx: CheckContext, response: Response, case: Case) -> bool | None:
     """A check to verify that the response is not a server-side error."""
-    from .specs.graphql.schemas import GraphQLSchema
-    from .specs.graphql.validation import validate_graphql_response
+    from schemathesis.specs.graphql.schemas import GraphQLSchema
+    from schemathesis.specs.graphql.validation import validate_graphql_response
+    from schemathesis.specs.openapi.utils import expand_status_codes
+
+    expected_statuses = expand_status_codes(ctx.config.not_a_server_error.expected_statuses or [])
 
     status_code = response.status_code
-    if status_code >= 500:
+    if status_code not in expected_statuses:
         raise ServerError(operation=case.operation.label, status_code=status_code)
     if isinstance(case.operation.schema, GraphQLSchema):
         try:

schemathesis/cli/commands/run/__init__.py

@@ -6,7 +6,6 @@ from typing import Any, Callable
 import click
 from click.utils import LazyFile
 
-from schemathesis import contrib
 from schemathesis.checks import CHECKS
 from schemathesis.cli.commands.run import executor, validation
 from schemathesis.cli.commands.run.filters import with_filters
@@ -19,11 +18,17 @@ from schemathesis.cli.ext.options import (
     CustomHelpMessageChoice,
     RegistryChoice,
 )
-from schemathesis.config import DEFAULT_REPORT_DIRECTORY, HealthCheck, ReportFormat, SchemathesisConfig
+from schemathesis.config import (
+    DEFAULT_REPORT_DIRECTORY,
+    HealthCheck,
+    ReportFormat,
+    SchemathesisConfig,
+    SchemathesisWarning,
+)
 from schemathesis.core import HYPOTHESIS_IN_MEMORY_DATABASE_IDENTIFIER
 from schemathesis.core.transport import DEFAULT_RESPONSE_TIMEOUT
-from schemathesis.generation import DEFAULT_GENERATOR_MODES, GenerationMode
-from schemathesis.generation.targets import TARGETS, TargetFunction
+from schemathesis.generation import GenerationMode
+from schemathesis.generation.metrics import METRICS, MetricFunction
 
 # NOTE: Need to explicitly import all registered checks
 from schemathesis.specs.openapi.checks import *  # noqa: F401, F403
@@ -83,6 +88,14 @@ DEFAULT_PHASES = ["examples", "coverage", "fuzzing", "stateful"]
     default=None,
     envvar="SCHEMATHESIS_WAIT_FOR_SCHEMA",
 )
+@grouped_option(
+    "--warnings",
+    help="Control warning display: 'off' to disable all, or comma-separated list of warning types to enable",
+    type=str,
+    default=None,
+    callback=validation.validate_warnings,
+    metavar="WARNINGS",
+)
 @group("API validation options")
 @grouped_option(
     "--checks",
@@ -296,7 +309,7 @@ DEFAULT_PHASES = ["examples", "coverage", "fuzzing", "stateful"]
     "generation_modes",
     help="Test data generation mode",
     type=click.Choice([item.value for item in GenerationMode] + ["all"]),
-    default=GenerationMode.default().value,
+    default="all",
     callback=validation.convert_generation_mode,
     show_default=True,
     metavar="",
@@ -349,7 +362,7 @@ DEFAULT_PHASES = ["examples", "coverage", "fuzzing", "stateful"]
     "generation_maximize",
     multiple=True,
     help="Guide input generation to values more likely to expose bugs via targeted property-based testing",
-    type=RegistryChoice(TARGETS),
+    type=RegistryChoice(METRICS),
     default=None,
     callback=validation.convert_maximize,
     show_default=True,
@@ -390,15 +403,6 @@ DEFAULT_PHASES = ["examples", "coverage", "fuzzing", "stateful"]
     show_default=True,
     metavar="BOOLEAN",
 )
-@grouped_option(
-    "--contrib-openapi-fill-missing-examples",
-    "contrib_openapi_fill_missing_examples",
-    help="Enable generation of random examples for API operations that do not have explicit examples",
-    is_flag=True,
-    default=False,
-    show_default=True,
-    metavar="BOOLEAN",
-)
 @group("Global options")
 @grouped_option("--no-color", help="Disable ANSI color escape codes", type=bool, is_flag=True)
 @grouped_option("--force-color", help="Explicitly tells to enable ANSI color escape codes", type=bool, is_flag=True)
@@ -442,6 +446,7 @@ def run(
     base_url: str | None,
     wait_for_schema: float | None = None,
     suppress_health_check: list[HealthCheck] | None,
+    warnings: bool | list[SchemathesisWarning] | None,
     rate_limit: str | None = None,
     request_timeout: int | None = None,
     request_tls_verify: bool = True,
@@ -456,11 +461,10 @@ def run(
     report_preserve_bytes: bool = False,
     output_sanitize: bool = True,
     output_truncate: bool = True,
-    contrib_openapi_fill_missing_examples: bool = False,
-    generation_modes: list[GenerationMode] = DEFAULT_GENERATOR_MODES,
+    generation_modes: list[GenerationMode],
     generation_seed: int | None = None,
     generation_max_examples: int | None = None,
-    generation_maximize: list[TargetFunction] | None,
+    generation_maximize: list[MetricFunction] | None,
     generation_deterministic: bool = False,
     generation_database: str | None = None,
     generation_unique_inputs: bool = False,
@@ -494,9 +498,6 @@ def run(
 
     validation.validate_auth_overlap(auth, headers)
 
-    if contrib_openapi_fill_missing_examples:
-        contrib.openapi.fill_missing_examples.install()
-
     # Then override the global config from CLI options
     config.update(
         color=color,
@@ -528,6 +529,7 @@ def run(
         request_cert=request_cert,
         request_cert_key=request_cert_key,
         proxy=request_proxy,
+        warnings=warnings,
     )
     # These are filters for what API operations should be tested
     filter_set = {

schemathesis/cli/commands/run/context.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Generator
+from typing import TYPE_CHECKING, Callable, Generator
 
+from schemathesis.cli.commands.run.events import LoadingFinished
 from schemathesis.config import ProjectConfig
 from schemathesis.core.failures import Failure
 from schemathesis.core.result import Err, Ok
@@ -11,6 +12,7 @@ from schemathesis.core.transport import Response
 from schemathesis.engine import Status, events
 from schemathesis.engine.recorder import CaseNode, ScenarioRecorder
 from schemathesis.generation.case import Case
+from schemathesis.schemas import APIOperation
 
 if TYPE_CHECKING:
     from schemathesis.generation.stateful.state_machine import ExtractionFailure
@@ -177,6 +179,7 @@ class ExecutionContext:
     """Storage for the current context of the execution."""
 
     config: ProjectConfig
+    find_operation_by_label: Callable[[str], APIOperation | None] | None = None
     statistic: Statistic = field(default_factory=Statistic)
     exit_code: int = 0
     initialization_lines: list[str | Generator[str, None, None]] = field(default_factory=list)
@@ -189,6 +192,8 @@ class ExecutionContext:
         self.summary_lines.append(line)
 
     def on_event(self, event: events.EngineEvent) -> None:
+        if isinstance(event, LoadingFinished):
+            self.find_operation_by_label = event.find_operation_by_label
         if isinstance(event, events.ScenarioFinished):
             self.statistic.on_scenario_finished(event.recorder)
         elif isinstance(event, events.NonFatalError) or (

schemathesis/cli/commands/run/events.py

@@ -1,10 +1,13 @@
+from __future__ import annotations
+
 import time
 import uuid
+from typing import Callable
 
 from schemathesis.config import ProjectConfig
 from schemathesis.core import Specification
 from schemathesis.engine import events
-from schemathesis.schemas import ApiStatistic
+from schemathesis.schemas import APIOperation, ApiStatistic
 
 
 class LoadingStarted(events.EngineEvent):
@@ -28,6 +31,7 @@ class LoadingFinished(events.EngineEvent):
         "statistic",
         "schema",
         "config",
+        "find_operation_by_label",
     )
 
     def __init__(
@@ -41,6 +45,7 @@ class LoadingFinished(events.EngineEvent):
         statistic: ApiStatistic,
         schema: dict,
         config: ProjectConfig,
+        find_operation_by_label: Callable[[str], APIOperation | None],
     ) -> None:
         self.id = uuid.uuid4()
         self.timestamp = time.time()
@@ -52,3 +57,4 @@ class LoadingFinished(events.EngineEvent):
         self.schema = schema
         self.base_path = base_path
         self.config = config
+        self.find_operation_by_label = find_operation_by_label

schemathesis/cli/commands/run/executor.py

@@ -76,6 +76,7 @@ def into_event_stream(*, location: str, config: ProjectConfig, filter_set: dict[
         schema=schema.raw_schema,
         config=schema.config,
         base_path=schema.base_path,
+        find_operation_by_label=schema.find_operation_by_label,
     )
 
     try:
@@ -121,17 +122,21 @@ def _execute(
     args: list[str],
     params: dict[str, Any],
 ) -> None:
-    handlers = initialize_handlers(config=config, args=args, params=params)
-    ctx = ExecutionContext(config=config)
+    handlers: list[EventHandler] = []
+    ctx: ExecutionContext | None = None
 
     def shutdown() -> None:
-        for _handler in handlers:
-            _handler.shutdown(ctx)
-
-    for handler in handlers:
-        handler.start(ctx)
+        if ctx is not None:
+            for _handler in handlers:
+                _handler.shutdown(ctx)
 
     try:
+        handlers = initialize_handlers(config=config, args=args, params=params)
+        ctx = ExecutionContext(config=config)
+
+        for handler in handlers:
+            handler.start(ctx)
+
         for event in event_stream:
             ctx.on_event(event)
             for handler in handlers: