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

schemathesis/specs/openapi/_hypothesis.py

@@ -7,9 +7,11 @@ from typing import Any, Callable, Dict, Iterable, Optional, Union, cast
 from urllib.parse import quote_plus
 from weakref import WeakKeyDictionary
 
+import jsonschema.protocols
 from hypothesis import event, note, reject
 from hypothesis import strategies as st
 from hypothesis_jsonschema import from_schema
+from requests.structures import CaseInsensitiveDict
 
 from schemathesis.config import GenerationConfig
 from schemathesis.core import NOT_SET, NotSet, media_types
@@ -42,7 +44,9 @@ from .parameters import OpenAPIBody, OpenAPIParameter, parameters_to_json_schema
 from .utils import is_header_location
 
 SLASH = "/"
-StrategyFactory = Callable[[Dict[str, Any], str, str, Optional[str], GenerationConfig], st.SearchStrategy]
+StrategyFactory = Callable[
+    [Dict[str, Any], str, str, Optional[str], GenerationConfig, type[jsonschema.protocols.Validator]], st.SearchStrategy
+]
 
 
 @st.composite  # type: ignore
@@ -52,7 +56,7 @@ def openapi_cases(
     operation: APIOperation,
     hooks: HookDispatcher | None = None,
     auth_storage: auths.AuthStorage | None = None,
-    generation_mode: GenerationMode = GenerationMode.default(),
+    generation_mode: GenerationMode = GenerationMode.POSITIVE,
     path_parameters: NotSet | dict[str, Any] = NOT_SET,
     headers: NotSet | dict[str, Any] = NOT_SET,
     cookies: NotSet | dict[str, Any] = NOT_SET,
@@ -80,18 +84,14 @@ def openapi_cases(
     phase_name = "stateful" if __is_stateful_phase else phase.value
     generation_config = operation.schema.config.generation_for(operation=operation, phase=phase_name)
 
-    context = HookContext(operation)
+    ctx = HookContext(operation=operation)
 
     path_parameters_ = generate_parameter(
-        "path", path_parameters, operation, draw, context, hooks, generation_mode, generation_config
+        "path", path_parameters, operation, draw, ctx, hooks, generation_mode, generation_config
     )
-    headers_ = generate_parameter(
-        "header", headers, operation, draw, context, hooks, generation_mode, generation_config
-    )
-    cookies_ = generate_parameter(
-        "cookie", cookies, operation, draw, context, hooks, generation_mode, generation_config
-    )
-    query_ = generate_parameter("query", query, operation, draw, context, hooks, generation_mode, generation_config)
+    headers_ = generate_parameter("header", headers, operation, draw, ctx, hooks, generation_mode, generation_config)
+    cookies_ = generate_parameter("cookie", cookies, operation, draw, ctx, hooks, generation_mode, generation_config)
+    query_ = generate_parameter("query", query, operation, draw, ctx, hooks, generation_mode, generation_config)
 
     if body is NOT_SET:
         if operation.body:
@@ -108,7 +108,7 @@ def openapi_cases(
                 candidates = operation.body.items
             parameter = draw(st.sampled_from(candidates))
             strategy = _get_body_strategy(parameter, strategy_factory, operation, generation_config)
-            strategy = apply_hooks(operation, context, hooks, strategy, "body")
+            strategy = apply_hooks(operation, ctx, hooks, strategy, "body")
             # Parameter may have a wildcard media type. In this case, choose any supported one
             possible_media_types = sorted(
                 operation.schema.transport.get_matching_media_types(parameter.media_type), key=lambda x: x[0]
@@ -158,12 +158,12 @@ def openapi_cases(
 
     instance = operation.Case(
         media_type=media_type,
-        path_parameters=path_parameters_.value,
-        headers=headers_.value,
-        cookies=cookies_.value,
-        query=query_.value,
+        path_parameters=path_parameters_.value or {},
+        headers=headers_.value or CaseInsensitiveDict(),
+        cookies=cookies_.value or {},
+        query=query_.value or {},
         body=body_.value,
-        meta=CaseMetadata(
+        _meta=CaseMetadata(
             generation=GenerationInfo(
                 time=time.monotonic() - start,
                 mode=generation_mode,
@@ -199,6 +199,8 @@ def _get_body_strategy(
     operation: APIOperation,
     generation_config: GenerationConfig,
 ) -> st.SearchStrategy:
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
     if parameter.media_type in MEDIA_TYPES:
         return MEDIA_TYPES[parameter.media_type]
     # The cache key relies on object ids, which means that the parameter should not be mutated
@@ -207,7 +209,10 @@ def _get_body_strategy(
         return _BODY_STRATEGIES_CACHE[parameter][strategy_factory]
     schema = parameter.as_json_schema(operation)
     schema = operation.schema.prepare_schema(schema)
-    strategy = strategy_factory(schema, operation.label, "body", parameter.media_type, generation_config)
+    assert isinstance(operation.schema, BaseOpenAPISchema)
+    strategy = strategy_factory(
+        schema, operation.label, "body", parameter.media_type, generation_config, operation.schema.validator_cls
+    )
     if not parameter.is_required:
         strategy |= st.just(NOT_SET)
     _BODY_STRATEGIES_CACHE.setdefault(parameter, {})[strategy_factory] = strategy
@@ -219,7 +224,7 @@ def get_parameters_value(
     location: str,
     draw: Callable,
     operation: APIOperation,
-    context: HookContext,
+    ctx: HookContext,
     hooks: HookDispatcher | None,
     strategy_factory: StrategyFactory,
     generation_config: GenerationConfig,
@@ -231,10 +236,10 @@ def get_parameters_value(
     """
     if isinstance(value, NotSet) or not value:
         strategy = get_parameters_strategy(operation, strategy_factory, location, generation_config)
-        strategy = apply_hooks(operation, context, hooks, strategy, location)
+        strategy = apply_hooks(operation, ctx, hooks, strategy, location)
         return draw(strategy)
     strategy = get_parameters_strategy(operation, strategy_factory, location, generation_config, exclude=value.keys())
-    strategy = apply_hooks(operation, context, hooks, strategy, location)
+    strategy = apply_hooks(operation, ctx, hooks, strategy, location)
     new = draw(strategy)
     if new is not None:
         copied = deepclone(value)
@@ -272,7 +277,7 @@ def generate_parameter(
     explicit: NotSet | dict[str, Any],
     operation: APIOperation,
     draw: Callable,
-    context: HookContext,
+    ctx: HookContext,
     hooks: HookDispatcher | None,
     generator: GenerationMode,
     generation_config: GenerationConfig,
@@ -291,9 +296,7 @@ def generate_parameter(
         generator = GenerationMode.POSITIVE
     else:
         strategy_factory = GENERATOR_MODE_TO_STRATEGY_FACTORY[generator]
-    value = get_parameters_value(
-        explicit, location, draw, operation, context, hooks, strategy_factory, generation_config
-    )
+    value = get_parameters_value(explicit, location, draw, operation, ctx, hooks, strategy_factory, generation_config)
     used_generator: GenerationMode | None = generator
     if value == explicit:
         # When we pass `explicit`, then its parts are excluded from generation of the final value
@@ -343,6 +346,8 @@ def get_parameters_strategy(
     exclude: Iterable[str] = (),
 ) -> st.SearchStrategy:
     """Create a new strategy for the case's component from the API operation parameters."""
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
     parameters = getattr(operation, LOCATION_TO_CONTAINER[location])
     if parameters:
         # The cache key relies on object ids, which means that the parameter should not be mutated
@@ -350,17 +355,28 @@ def get_parameters_strategy(
         if operation in _PARAMETER_STRATEGIES_CACHE and nested_cache_key in _PARAMETER_STRATEGIES_CACHE[operation]:
             return _PARAMETER_STRATEGIES_CACHE[operation][nested_cache_key]
         schema = get_schema_for_location(operation, location, parameters)
-        for name in exclude:
-            # Values from `exclude` are not necessarily valid for the schema - they come from user-defined examples
-            # that may be invalid
-            schema["properties"].pop(name, None)
-            with suppress(ValueError):
-                schema["required"].remove(name)
+        if location == "header" and exclude:
+            # Remove excluded headers case-insensitively
+            exclude_lower = {name.lower() for name in exclude}
+            schema["properties"] = {
+                key: value for key, value in schema["properties"].items() if key.lower() not in exclude_lower
+            }
+            if "required" in schema:
+                schema["required"] = [key for key in schema["required"] if key.lower() not in exclude_lower]
+        elif exclude:
+            # Non-header locations: remove by exact name
+            for name in exclude:
+                schema["properties"].pop(name, None)
+                with suppress(ValueError):
+                    schema["required"].remove(name)
         if not schema["properties"] and strategy_factory is make_negative_strategy:
             # Nothing to negate - all properties were excluded
             strategy = st.none()
         else:
-            strategy = strategy_factory(schema, operation.label, location, None, generation_config)
+            assert isinstance(operation.schema, BaseOpenAPISchema)
+            strategy = strategy_factory(
+                schema, operation.label, location, None, generation_config, operation.schema.validator_cls
+            )
             serialize = operation.get_parameter_serializer(location)
             if serialize is not None:
                 strategy = strategy.map(serialize)
@@ -424,6 +440,7 @@ def make_positive_strategy(
     location: str,
     media_type: str | None,
     generation_config: GenerationConfig,
+    validator_cls: type[jsonschema.protocols.Validator],
     custom_formats: dict[str, st.SearchStrategy] | None = None,
 ) -> st.SearchStrategy:
     """Strategy for generating values that fit the schema."""
@@ -454,6 +471,7 @@ def make_negative_strategy(
     location: str,
     media_type: str | None,
     generation_config: GenerationConfig,
+    validator_cls: type[jsonschema.protocols.Validator],
     custom_formats: dict[str, st.SearchStrategy] | None = None,
 ) -> st.SearchStrategy:
     custom_formats = _build_custom_formats(custom_formats, generation_config)
@@ -464,6 +482,7 @@ def make_negative_strategy(
         media_type=media_type,
         custom_formats=custom_formats,
         generation_config=generation_config,
+        validator_cls=validator_cls,
     )
 
 
@@ -494,11 +513,11 @@ def quote_all(parameters: dict[str, Any]) -> dict[str, Any]:
 
 def apply_hooks(
     operation: APIOperation,
-    context: HookContext,
+    ctx: HookContext,
     hooks: HookDispatcher | None,
     strategy: st.SearchStrategy,
     location: str,
 ) -> st.SearchStrategy:
     """Apply all hooks related to the given location."""
     container = LOCATION_TO_CONTAINER[location]
-    return apply_to_all_dispatchers(operation, context, hooks, strategy, container)
+    return apply_to_all_dispatchers(operation, ctx, hooks, strategy, container)

schemathesis/specs/openapi/checks.py

@@ -21,10 +21,12 @@ from schemathesis.openapi.checks import (
     JsonSchemaError,
     MalformedMediaType,
     MissingContentType,
+    MissingHeaderNotRejected,
     MissingHeaders,
     RejectedPositiveData,
     UndefinedContentType,
     UndefinedStatusCode,
+    UnsupportedMethodResponse,
     UseAfterFree,
 )
 from schemathesis.specs.openapi.constants import LOCATION_TO_CONTAINER
@@ -33,9 +35,7 @@ from schemathesis.transport.prepare import prepare_path
 from .utils import expand_status_code, expand_status_codes
 
 if TYPE_CHECKING:
-    from requests import PreparedRequest
-
-    from ...schemas import APIOperation
+    from schemathesis.schemas import APIOperation
 
 
 def is_unexpected_http_status_case(case: Case) -> bool:
@@ -289,8 +289,14 @@ def missing_required_header(ctx: CheckContext, response: Response, case: Case) -
             config = ctx.config.missing_required_header
             expected_statuses = expand_status_codes(config.expected_statuses or [])
         if response.status_code not in expected_statuses:
-            allowed = f"Allowed statuses: {', '.join(map(str, expected_statuses))}"
-            raise AssertionError(f"Unexpected response status for a missing header: {response.status_code}\n{allowed}")
+            allowed = ", ".join(map(str, expected_statuses))
+            raise MissingHeaderNotRejected(
+                operation=f"{case.method} {case.path}",
+                header_name=data.parameter,
+                status_code=response.status_code,
+                expected_statuses=list(expected_statuses),
+                message=f"Missing header not rejected (got {response.status_code}, expected {allowed})",
+            )
     return None
 
 
@@ -302,13 +308,24 @@ def unsupported_method(ctx: CheckContext, response: Response, case: Case) -> boo
     data = meta.phase.data
     if data.description and data.description.startswith("Unspecified HTTP method:"):
         if response.status_code != 405:
-            raise AssertionError(
-                f"Unexpected response status for unspecified HTTP method: {response.status_code}\nExpected: 405"
+            raise UnsupportedMethodResponse(
+                operation=case.operation.label,
+                method=cast(str, response.request.method),
+                status_code=response.status_code,
+                failure_reason="wrong_status",
+                message=f"Wrong status for unsupported method {response.request.method} (got {response.status_code}, expected 405)",
             )
 
         allow_header = response.headers.get("allow")
         if not allow_header:
-            raise AssertionError("Missing 'Allow' header in 405 Method Not Allowed response")
+            raise UnsupportedMethodResponse(
+                operation=case.operation.label,
+                method=cast(str, response.request.method),
+                status_code=response.status_code,
+                allow_header_present=False,
+                failure_reason="missing_allow_header",
+                message=f"Missing Allow header for unsupported method {response.request.method}",
+            )
     return None
 
 
@@ -352,12 +369,12 @@ def use_after_free(ctx: CheckContext, response: Response, case: Case) -> bool |
     if response.status_code == 404 or response.status_code >= 500:
         return None
 
-    for related_case in ctx.find_related(case_id=case.id):
-        parent = ctx.find_parent(case_id=related_case.id)
+    for related_case in ctx._find_related(case_id=case.id):
+        parent = ctx._find_parent(case_id=related_case.id)
         if not parent:
             continue
 
-        parent_response = ctx.find_response(case_id=parent.id)
+        parent_response = ctx._find_response(case_id=parent.id)
 
         if (
             related_case.operation.method.lower() == "delete"
@@ -395,10 +412,10 @@ def ensure_resource_availability(ctx: CheckContext, response: Response, case: Ca
     if not (400 <= response.status_code < 500):
         return None
 
-    parent = ctx.find_parent(case_id=case.id)
+    parent = ctx._find_parent(case_id=case.id)
     if parent is None:
         return None
-    parent_response = ctx.find_response(case_id=parent.id)
+    parent_response = ctx._find_response(case_id=parent.id)
     if parent_response is None:
         return None
 
@@ -424,8 +441,8 @@ def ensure_resource_availability(ctx: CheckContext, response: Response, case: Ca
         return None
 
     # Look for any successful DELETE operations on this resource
-    for related_case in ctx.find_related(case_id=case.id):
-        related_response = ctx.find_response(case_id=related_case.id)
+    for related_case in ctx._find_related(case_id=case.id):
+        related_response = ctx._find_response(case_id=related_case.id)
         if (
             related_case.operation.method.upper() == "DELETE"
             and related_response is not None
@@ -458,6 +475,12 @@ def ensure_resource_availability(ctx: CheckContext, response: Response, case: Ca
     )
 
 
+class AuthScenario(str, enum.Enum):
+    NO_AUTH = "no_auth"
+    INVALID_AUTH = "invalid_auth"
+    GENERATED_AUTH = "generated_auth"
+
+
 class AuthKind(str, enum.Enum):
     EXPLICIT = "explicit"
     GENERATED = "generated"
@@ -473,47 +496,68 @@ def ignored_auth(ctx: CheckContext, response: Response, case: Case) -> bool | No
     security_parameters = _get_security_parameters(case.operation)
     # Authentication is required for this API operation and response is successful
     if security_parameters and 200 <= response.status_code < 300:
-        auth = _contains_auth(ctx, case, response.request, security_parameters)
+        auth = _contains_auth(ctx, case, response, security_parameters)
         if auth == AuthKind.EXPLICIT:
             # Auth is explicitly set, it is expected to be valid
             # Check if invalid auth will give an error
             no_auth_case = remove_auth(case, security_parameters)
-            kwargs = ctx.transport_kwargs or {}
+            kwargs = ctx._transport_kwargs or {}
             kwargs.copy()
-            if "headers" in kwargs:
-                headers = kwargs["headers"].copy()
-                _remove_auth_from_explicit_headers(headers, security_parameters)
-                kwargs["headers"] = headers
+            for location, container_name in (
+                ("header", "headers"),
+                ("cookie", "cookies"),
+                ("query", "query"),
+            ):
+                if container_name in kwargs:
+                    container = kwargs[container_name].copy()
+                    _remove_auth_from_container(container, security_parameters, location=location)
+                    kwargs[container_name] = container
             kwargs.pop("session", None)
-            ctx.record_case(parent_id=case.id, case=no_auth_case)
+            ctx._record_case(parent_id=case.id, case=no_auth_case)
             no_auth_response = case.operation.schema.transport.send(no_auth_case, **kwargs)
-            ctx.record_response(case_id=no_auth_case.id, response=no_auth_response)
+            ctx._record_response(case_id=no_auth_case.id, response=no_auth_response)
             if no_auth_response.status_code != 401:
-                _raise_no_auth_error(no_auth_response, no_auth_case, "that requires authentication")
+                _raise_no_auth_error(no_auth_response, no_auth_case, AuthScenario.NO_AUTH)
             # Try to set invalid auth and check if it succeeds
             for parameter in security_parameters:
                 invalid_auth_case = remove_auth(case, security_parameters)
                 _set_auth_for_case(invalid_auth_case, parameter)
-                ctx.record_case(parent_id=case.id, case=invalid_auth_case)
+                ctx._record_case(parent_id=case.id, case=invalid_auth_case)
                 invalid_auth_response = case.operation.schema.transport.send(invalid_auth_case, **kwargs)
-                ctx.record_response(case_id=invalid_auth_case.id, response=invalid_auth_response)
+                ctx._record_response(case_id=invalid_auth_case.id, response=invalid_auth_response)
                 if invalid_auth_response.status_code != 401:
-                    _raise_no_auth_error(invalid_auth_response, invalid_auth_case, "with any auth")
+                    _raise_no_auth_error(invalid_auth_response, invalid_auth_case, AuthScenario.INVALID_AUTH)
         elif auth == AuthKind.GENERATED:
             # If this auth is generated which means it is likely invalid, then
             # this request should have been an error
-            _raise_no_auth_error(response, case, "with invalid auth")
+            _raise_no_auth_error(response, case, AuthScenario.GENERATED_AUTH)
         else:
             # Successful response when there is no auth
-            _raise_no_auth_error(response, case, "that requires authentication")
+            _raise_no_auth_error(response, case, AuthScenario.NO_AUTH)
     return None
 
 
-def _raise_no_auth_error(response: Response, case: Case, suffix: str) -> NoReturn:
+def _raise_no_auth_error(response: Response, case: Case, auth: AuthScenario) -> NoReturn:
     reason = http.client.responses.get(response.status_code, "Unknown")
+
+    if auth == AuthScenario.NO_AUTH:
+        title = "API accepts requests without authentication"
+        detail = None
+    elif auth == AuthScenario.INVALID_AUTH:
+        title = "API accepts invalid authentication"
+        detail = "invalid credentials provided"
+    else:
+        title = "API accepts invalid authentication"
+        detail = "generated auth likely invalid"
+
+    message = f"Expected 401, got `{response.status_code} {reason}` for `{case.operation.label}`"
+    if detail is not None:
+        message = f"{message} ({detail})"
+
     raise IgnoredAuth(
         operation=case.operation.label,
-        message=f"The API returned `{response.status_code} {reason}` for `{case.operation.label}` {suffix}.",
+        message=message,
+        title=title,
         case_id=case.id,
     )
 
@@ -534,14 +578,15 @@ def _get_security_parameters(operation: APIOperation) -> list[SecurityParameter]
 
 
 def _contains_auth(
-    ctx: CheckContext, case: Case, request: PreparedRequest, security_parameters: list[SecurityParameter]
+    ctx: CheckContext, case: Case, response: Response, security_parameters: list[SecurityParameter]
 ) -> AuthKind | None:
     """Whether a request has authentication declared in the schema."""
     from requests.cookies import RequestsCookieJar
 
     # If auth comes from explicit `auth` option or a custom auth, it is always explicit
-    if ctx.auth is not None or case._has_explicit_auth:
+    if ctx._auth is not None or case._has_explicit_auth:
         return AuthKind.EXPLICIT
+    request = response.request
     parsed = urlparse(request.url)
     query = parse_qs(parsed.query)  # type: ignore
     # Load the `Cookie` header separately, because it is possible that `request._cookies` and the header are out of sync
@@ -563,19 +608,35 @@ def _contains_auth(
     for parameter in security_parameters:
         name = parameter["name"]
         if has_header(parameter):
-            if (ctx.headers is not None and name in ctx.headers) or (ctx.override and name in ctx.override.headers):
+            if (
+                # Explicit CLI headers
+                (ctx._headers is not None and name in ctx._headers)
+                # Other kinds of overrides
+                or (ctx._override and name in ctx._override.headers)
+                or (response._override and name in response._override.headers)
+            ):
                 return AuthKind.EXPLICIT
             return AuthKind.GENERATED
         if has_cookie(parameter):
-            if ctx.headers is not None and "Cookie" in ctx.headers:
-                cookies = cast(RequestsCookieJar, ctx.headers["Cookie"])  # type: ignore
-                if name in cookies:
-                    return AuthKind.EXPLICIT
-            if ctx.override and name in ctx.override.cookies:
+            for headers in [
+                ctx._headers,
+                (ctx._override.headers if ctx._override else None),
+                (response._override.headers if response._override else None),
+            ]:
+                if headers is not None and "Cookie" in headers:
+                    jar = cast(RequestsCookieJar, headers["Cookie"])
+                    if name in jar:
+                        return AuthKind.EXPLICIT
+
+            if (ctx._override and name in ctx._override.cookies) or (
+                response._override and name in response._override.cookies
+            ):
                 return AuthKind.EXPLICIT
             return AuthKind.GENERATED
         if has_query(parameter):
-            if ctx.override and name in ctx.override.query:
+            if (ctx._override and name in ctx._override.query) or (
+                response._override and name in response._override.query
+            ):
                 return AuthKind.EXPLICIT
             return AuthKind.GENERATED
 
@@ -587,9 +648,9 @@ def remove_auth(case: Case, security_parameters: list[SecurityParameter]) -> Cas
 
     It mutates `case` in place.
     """
-    headers = case.headers.copy() if case.headers else None
-    query = case.query.copy() if case.query else None
-    cookies = case.cookies.copy() if case.cookies else None
+    headers = case.headers.copy()
+    query = case.query.copy()
+    cookies = case.cookies.copy()
     for parameter in security_parameters:
         name = parameter["name"]
         if parameter["in"] == "header" and headers:
@@ -602,7 +663,7 @@ def remove_auth(case: Case, security_parameters: list[SecurityParameter]) -> Cas
         operation=case.operation,
         method=case.method,
         path=case.path,
-        path_parameters=case.path_parameters.copy() if case.path_parameters else None,
+        path_parameters=case.path_parameters.copy(),
         headers=headers,
         cookies=cookies,
         query=query,
@@ -612,11 +673,11 @@ def remove_auth(case: Case, security_parameters: list[SecurityParameter]) -> Cas
     )
 
 
-def _remove_auth_from_explicit_headers(headers: dict, security_parameters: list[SecurityParameter]) -> None:
+def _remove_auth_from_container(container: dict, security_parameters: list[SecurityParameter], location: str) -> None:
     for parameter in security_parameters:
         name = parameter["name"]
-        if parameter["in"] == "header":
-            headers.pop(name, None)
+        if parameter["in"] == location:
+            container.pop(name, None)
 
 
 def _set_auth_for_case(case: Case, parameter: SecurityParameter) -> None:
@@ -628,6 +689,9 @@ def _set_auth_for_case(case: Case, parameter: SecurityParameter) -> None:
     ):
         if parameter["in"] == location:
             container = getattr(case, attr_name, {})
+            # Could happen in the negative testing mode
+            if not isinstance(container, dict):
+                container = {}
             container[name] = "SCHEMATHESIS-INVALID-VALUE"
             setattr(case, attr_name, container)
 

schemathesis/specs/openapi/expressions/nodes.py

@@ -87,7 +87,7 @@ class NonBodyRequest(Node):
     extractor: Extractor | None = None
 
     def evaluate(self, output: StepOutput) -> str | Unresolvable:
-        container: dict | CaseInsensitiveDict = {
+        container = {
             "query": output.case.query,
             "path": output.case.path_parameters,
             "header": output.case.headers,

schemathesis/specs/openapi/formats.py

@@ -15,10 +15,37 @@ STRING_FORMATS: dict[str, st.SearchStrategy] = {}
 
 
 def register_string_format(name: str, strategy: st.SearchStrategy) -> None:
-    """Register a new strategy for generating data for specific string "format".
+    r"""Register a custom Hypothesis strategy for generating string format data.
+
+    Args:
+        name: String format name that matches the "format" keyword in your API schema
+        strategy: Hypothesis strategy to generate values for this format
+
+    Example:
+        ```python
+        import schemathesis
+        from hypothesis import strategies as st
+
+        # Register phone number format
+        phone_strategy = st.from_regex(r"\+1-\d{3}-\d{3}-\d{4}")
+        schemathesis.openapi.format("phone", phone_strategy)
+
+        # Register email with specific domain
+        email_strategy = st.from_regex(r"[a-z]+@company\.com")
+        schemathesis.openapi.format("company-email", email_strategy)
+        ```
+
+    Schema usage:
+        ```yaml
+        properties:
+          phone:
+            type: string
+            format: phone          # Uses your phone_strategy
+          contact_email:
+            type: string
+            format: company-email  # Uses your email_strategy
+        ```
 
-    :param str name: Format name. It should correspond the one used in the API schema as the "format" keyword value.
-    :param strategy: Hypothesis strategy you'd like to use to generate values for this format.
     """
     from hypothesis.strategies import SearchStrategy
 

schemathesis/specs/openapi/media_types.py

@@ -15,7 +15,50 @@ MEDIA_TYPES: dict[str, st.SearchStrategy[bytes]] = {}
 
 
 def register_media_type(name: str, strategy: st.SearchStrategy[bytes], *, aliases: Collection[str] = ()) -> None:
-    """Register a strategy for the given media type."""
+    r"""Register a custom Hypothesis strategy for generating media type content.
+
+    Args:
+        name: Media type name that matches your OpenAPI requestBody content type
+        strategy: Hypothesis strategy that generates bytes for this media type
+        aliases: Additional media type names that use the same strategy
+
+    Example:
+        ```python
+        import schemathesis
+        from hypothesis import strategies as st
+
+        # Register PDF file strategy
+        pdf_strategy = st.sampled_from([
+            b"%PDF-1.4\n1 0 obj\n<<\n/Type /Catalog\n>>\nendobj\n%%EOF",
+            b"%PDF-1.5\n%\xe2\xe3\xcf\xd3\n1 0 obj\n<<\n/Type /Catalog\n>>\nendobj\n%%EOF"
+        ])
+        schemathesis.openapi.media_type("application/pdf", pdf_strategy)
+
+        # Dynamic content generation
+        @st.composite
+        def xml_content(draw):
+            tag = draw(st.text(min_size=3, max_size=10))
+            content = draw(st.text(min_size=1, max_size=50))
+            return f"<?xml version='1.0'?><{tag}>{content}</{tag}>".encode()
+
+        schemathesis.openapi.media_type("application/xml", xml_content())
+        ```
+
+    Schema usage:
+        ```yaml
+        requestBody:
+          content:
+            application/pdf:        # Uses your PDF strategy
+              schema:
+                type: string
+                format: binary
+            application/xml:        # Uses your XML strategy
+              schema:
+                type: string
+                format: binary
+        ```
+
+    """
 
     @REQUESTS_TRANSPORT.serializer(name, *aliases)
     @ASGI_TRANSPORT.serializer(name, *aliases)