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

schemathesis/graphql/loaders.py

@@ -19,6 +19,24 @@ if TYPE_CHECKING:
 
 
 def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> GraphQLSchema:
+    """Load GraphQL schema from an ASGI application via introspection.
+
+    Args:
+        path: Relative URL path to the GraphQL endpoint (e.g., "/graphql")
+        app: ASGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the ASGI test client.
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        import schemathesis
+
+        app = FastAPI()
+        schema = schemathesis.graphql.from_asgi("/graphql", app)
+        ```
+
+    """
     require_relative_url(path)
     kwargs.setdefault("json", {"query": get_introspection_query()})
     client = asgi.get_client(app)
@@ -28,6 +46,24 @@ def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None,
 
 
 def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> GraphQLSchema:
+    """Load GraphQL schema from a WSGI application via introspection.
+
+    Args:
+        path: Relative URL path to the GraphQL endpoint (e.g., "/graphql")
+        app: WSGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the WSGI test client.
+
+    Example:
+        ```python
+        from flask import Flask
+        import schemathesis
+
+        app = Flask(__name__)
+        schema = schemathesis.graphql.from_wsgi("/graphql", app)
+        ```
+
+    """
     require_relative_url(path)
     prepare_request_kwargs(kwargs)
     kwargs.setdefault("json", {"query": get_introspection_query()})
@@ -41,7 +77,31 @@ def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None,
 def from_url(
     url: str, *, config: SchemathesisConfig | None = None, wait_for_schema: float | None = None, **kwargs: Any
 ) -> GraphQLSchema:
-    """Load from URL."""
+    """Load GraphQL schema from a URL via introspection query.
+
+    Args:
+        url: Full URL to the GraphQL endpoint
+        config: Custom configuration. If `None`, uses auto-discovered config
+        wait_for_schema: Maximum time in seconds to wait for schema availability
+        **kwargs: Additional parameters passed to `requests.post()` (headers, timeout, auth, etc.).
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Basic usage
+        schema = schemathesis.graphql.from_url("https://api.example.com/graphql")
+
+        # With authentication and timeout
+        schema = schemathesis.graphql.from_url(
+            "https://api.example.com/graphql",
+            headers={"Authorization": "Bearer token"},
+            timeout=30,
+            wait_for_schema=10.0
+        )
+        ```
+
+    """
     import requests
 
     kwargs.setdefault("json", {"query": get_introspection_query()})
@@ -53,13 +113,55 @@ def from_url(
 def from_path(
     path: PathLike | str, *, config: SchemathesisConfig | None = None, encoding: str = "utf-8"
 ) -> GraphQLSchema:
-    """Load from a filesystem path."""
+    """Load GraphQL schema from a filesystem path.
+
+    Args:
+        path: File path to the GraphQL schema file (.graphql, .gql)
+        config: Custom configuration. If `None`, uses auto-discovered config
+        encoding: Text encoding for reading the file
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Load from GraphQL SDL file
+        schema = schemathesis.graphql.from_path("./schema.graphql")
+        ```
+
+    """
     with open(path, encoding=encoding) as file:
         return from_file(file=file, config=config).configure(location=Path(path).absolute().as_uri())
 
 
 def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None) -> GraphQLSchema:
-    """Load from file-like object or string."""
+    """Load GraphQL schema from a file-like object or string.
+
+    Args:
+        file: File-like object or raw string containing GraphQL SDL
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
+
+        # From GraphQL SDL string
+        schema_sdl = '''
+            type Query {
+                user(id: ID!): User
+            }
+            type User {
+                id: ID!
+                name: String!
+            }
+        '''
+        schema = schemathesis.graphql.from_file(schema_sdl)
+
+        # From file object
+        with open("schema.graphql") as f:
+            schema = schemathesis.graphql.from_file(f)
+        ```
+
+    """
     import graphql
 
     if isinstance(file, str):
@@ -87,7 +189,39 @@ def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None)
 
 
 def from_dict(schema: dict[str, Any], *, config: SchemathesisConfig | None = None) -> GraphQLSchema:
-    """Base loader that others build upon."""
+    """Load GraphQL schema from a dictionary containing introspection result.
+
+    Args:
+        schema: Dictionary containing GraphQL introspection result or wrapped in 'data' key
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
+
+        # From introspection result
+        introspection = {
+            "__schema": {
+                "types": [...],
+                "queryType": {"name": "Query"},
+                # ... rest of introspection result
+            }
+        }
+        schema = schemathesis.graphql.from_dict(introspection)
+
+        # From GraphQL response format (with 'data' wrapper)
+        response_data = {
+            "data": {
+                "__schema": {
+                    "types": [...],
+                    "queryType": {"name": "Query"}
+                }
+            }
+        }
+        schema = schemathesis.graphql.from_dict(response_data)
+        ```
+
+    """
     from schemathesis.specs.graphql.schemas import GraphQLSchema
 
     if "data" in schema:

schemathesis/hooks.py

@@ -37,13 +37,15 @@ class RegisteredHook:
 
 @dataclass
 class HookContext:
-    """A context that is passed to some hook functions.
+    """A context that is passed to some hook functions."""
 
-    :ivar Optional[APIOperation] operation: API operation that is currently being processed.
-                                            Might be absent in some cases.
-    """
+    operation: APIOperation | None
+    """API operation that is currently being processed."""
+
+    __slots__ = ("operation",)
 
-    operation: APIOperation | None = None
+    def __init__(self, *, operation: APIOperation | None = None) -> None:
+        self.operation = operation
 
 
 def to_filterable_hook(dispatcher: HookDispatcher) -> Callable:
@@ -110,48 +112,29 @@ class HookDispatcher:
     _specs: ClassVar[dict[str, RegisteredHook]] = {}
 
     def __post_init__(self) -> None:
-        self.register = to_filterable_hook(self)  # type: ignore[method-assign]
-
-    def register(self, hook: str | Callable) -> Callable:
-        """Register a new hook.
-
-        :param hook: Either a hook function or a string.
-
-        Can be used as a decorator in two forms.
-        Without arguments for registering hooks and autodetecting their names:
-
-        .. code-block:: python
-
-            @schemathesis.hook
-            def before_generate_query(context, strategy):
-                ...
-
-        With a hook name as the first argument:
-
-        .. code-block:: python
+        self.hook = to_filterable_hook(self)  # type: ignore[method-assign]
 
-            @schemathesis.hook("before_generate_query")
-            def hook(context, strategy):
-                ...
-        """
+    def hook(self, hook: str | Callable) -> Callable:
         raise NotImplementedError
 
     def apply(self, hook: Callable, *, name: str | None = None) -> Callable[[Callable], Callable]:
         """Register hook to run only on one test function.
 
-        :param hook: A hook function.
-        :param Optional[str] name: A hook name.
-
-        .. code-block:: python
+        Args:
+            hook: A hook function.
+            name: A hook name.
 
-            def before_generate_query(context, strategy):
+        Example:
+            ```python
+            def filter_query(ctx, value):
                 ...
 
 
-            @schema.hooks.apply(before_generate_query)
+            @schema.hooks.apply(filter_query)
             @schema.parametrize()
             def test_api(case):
                 ...
+            ```
 
         """
         if name is None:
@@ -391,6 +374,50 @@ def after_call(context: HookContext, case: Case, response: Response) -> None:
 GLOBAL_HOOK_DISPATCHER = HookDispatcher(scope=HookScope.GLOBAL)
 dispatch = GLOBAL_HOOK_DISPATCHER.dispatch
 get_all_by_name = GLOBAL_HOOK_DISPATCHER.get_all_by_name
-register = GLOBAL_HOOK_DISPATCHER.register
 unregister = GLOBAL_HOOK_DISPATCHER.unregister
 unregister_all = GLOBAL_HOOK_DISPATCHER.unregister_all
+
+
+def hook(hook: str | Callable) -> Callable:
+    """Register a new hook.
+
+    Args:
+        hook: Either a hook function (autodetecting its name) or a string matching one of the supported hook names.
+
+    Example:
+        Can be used as a decorator in two ways:
+
+        1. Without arguments (auto-detect the hook name from the function name):
+
+            ```python
+            @schemathesis.hook
+            def filter_query(ctx, query):
+                \"\"\"Skip cases where query is None or invalid\"\"\"
+                return query and "user_id" in query
+
+            @schemathesis.hook
+            def before_call(ctx, case):
+                \"\"\"Modify headers before sending each request\"\"\"
+                if case.headers is None:
+                    case.headers = {}
+                case.headers["X-Test-Mode"] = "true"
+                return None
+            ```
+
+        2. With an explicit hook name as the first argument:
+
+            ```python
+            @schemathesis.hook("map_headers")
+            def add_custom_header(ctx, headers):
+                \"\"\"Inject a test header into every request\"\"\"
+                if headers is None:
+                    headers = {}
+                headers["X-Custom"] = "value"
+                return headers
+            ```
+
+    """
+    return GLOBAL_HOOK_DISPATCHER.hook(hook)
+
+
+hook.__dict__ = GLOBAL_HOOK_DISPATCHER.hook.__dict__

schemathesis/openapi/loaders.py

@@ -20,6 +20,24 @@ if TYPE_CHECKING:
 
 
 def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from an ASGI application.
+
+    Args:
+        path: Relative URL path to the OpenAPI schema endpoint (e.g., "/openapi.json")
+        app: ASGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the ASGI test client
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        import schemathesis
+
+        app = FastAPI()
+        schema = schemathesis.openapi.from_asgi("/openapi.json", app)
+        ```
+
+    """
     require_relative_url(path)
     client = asgi.get_client(app)
     response = load_from_url(client.get, url=path, **kwargs)
@@ -29,6 +47,24 @@ def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None,
 
 
 def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from a WSGI application.
+
+    Args:
+        path: Relative URL path to the OpenAPI schema endpoint (e.g., "/openapi.json")
+        app: WSGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the WSGI test client
+
+    Example:
+        ```python
+        from flask import Flask
+        import schemathesis
+
+        app = Flask(__name__)
+        schema = schemathesis.openapi.from_wsgi("/openapi.json", app)
+        ```
+
+    """
     require_relative_url(path)
     prepare_request_kwargs(kwargs)
     client = wsgi.get_client(app)
@@ -42,7 +78,31 @@ def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None,
 def from_url(
     url: str, *, config: SchemathesisConfig | None = None, wait_for_schema: float | None = None, **kwargs: Any
 ) -> BaseOpenAPISchema:
-    """Load from URL."""
+    """Load OpenAPI schema from a URL.
+
+    Args:
+        url: Full URL to the OpenAPI schema
+        config: Custom configuration. If `None`, uses auto-discovered config
+        wait_for_schema: Maximum time in seconds to wait for schema availability
+        **kwargs: Additional parameters passed to `requests.get()` (headers, timeout, auth, etc.)
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Basic usage
+        schema = schemathesis.openapi.from_url("https://api.example.com/openapi.json")
+
+        # With authentication and timeout
+        schema = schemathesis.openapi.from_url(
+            "https://api.example.com/openapi.json",
+            headers={"Authorization": "Bearer token"},
+            timeout=30,
+            wait_for_schema=10.0
+        )
+        ```
+
+    """
     import requests
 
     response = load_from_url(requests.get, url=url, wait_for_schema=wait_for_schema, **kwargs)
@@ -54,7 +114,25 @@ def from_url(
 def from_path(
     path: PathLike | str, *, config: SchemathesisConfig | None = None, encoding: str = "utf-8"
 ) -> BaseOpenAPISchema:
-    """Load from a filesystem path."""
+    """Load OpenAPI schema from a filesystem path.
+
+    Args:
+        path: File path to the OpenAPI schema (supports JSON / YAML)
+        config: Custom configuration. If `None`, uses auto-discovered config
+        encoding: Text encoding for reading the file
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Load from file
+        schema = schemathesis.openapi.from_path("./specs/openapi.yaml")
+
+        # With custom encoding
+        schema = schemathesis.openapi.from_path("./specs/openapi.json", encoding="cp1252")
+        ```
+
+    """
     with open(path, encoding=encoding) as file:
         content_type = detect_content_type(headers=None, path=str(path))
         schema = load_content(file.read(), content_type)
@@ -62,7 +140,26 @@ def from_path(
 
 
 def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None) -> BaseOpenAPISchema:
-    """Load from file-like object or string."""
+    """Load OpenAPI schema from a file-like object or string.
+
+    Args:
+        file: File-like object or raw string containing the OpenAPI schema
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
+
+        # From string
+        schema_content = '{"openapi": "3.0.0", "info": {"title": "API"}}'
+        schema = schemathesis.openapi.from_file(schema_content)
+
+        # From file object
+        with open("openapi.yaml") as f:
+            schema = schemathesis.openapi.from_file(f)
+        ```
+
+    """
     if isinstance(file, str):
         data = file
     else:
@@ -75,7 +172,26 @@ def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None)
 
 
 def from_dict(schema: dict[str, Any], *, config: SchemathesisConfig | None = None) -> BaseOpenAPISchema:
-    """Base loader that others build upon."""
+    """Load OpenAPI schema from a dictionary.
+
+    Args:
+        schema: Dictionary containing the parsed OpenAPI schema
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
+
+        schema_dict = {
+            "openapi": "3.0.0",
+            "info": {"title": "My API", "version": "1.0.0"},
+            "paths": {"/users": {"get": {"responses": {"200": {"description": "OK"}}}}}
+        }
+
+        schema = schemathesis.openapi.from_dict(schema_dict)
+        ```
+
+    """
     from schemathesis.specs.openapi.schemas import OpenApi30, SwaggerV20
 
     if not isinstance(schema, dict):

schemathesis/pytest/loaders.py

@@ -7,6 +7,30 @@ if TYPE_CHECKING:
 
 
 def from_fixture(name: str) -> LazySchema:
+    """Create a lazy schema loader that resolves a pytest fixture at test runtime.
+
+    Args:
+        name: Name of the pytest fixture that returns a schema object
+
+    Example:
+        ```python
+        import pytest
+        import schemathesis
+
+        @pytest.fixture
+        def api_schema():
+            return schemathesis.openapi.from_url("https://api.example.com/openapi.json")
+
+        # Create lazy schema from fixture
+        schema = schemathesis.pytest.from_fixture("api_schema")
+
+        # Use with parametrize to generate tests
+        @schema.parametrize()
+        def test_api(case):
+            case.call_and_validate()
+        ```
+
+    """
     from schemathesis.pytest.lazy import LazySchema
 
     return LazySchema(name)

schemathesis/pytest/plugin.py

@@ -21,7 +21,9 @@ from schemathesis.core.errors import (
     InvalidRegexPattern,
     InvalidSchema,
     SerializationNotPossible,
+    format_exception,
 )
+from schemathesis.core.failures import FailureGroup
 from schemathesis.core.marks import Mark
 from schemathesis.core.result import Ok, Result
 from schemathesis.generation.hypothesis.given import (
@@ -247,6 +249,26 @@ def pytest_pycollect_makeitem(collector: nodes.Collector, name: str, obj: Any) -
         outcome.get_result()
 
 
+@pytest.hookimpl(tryfirst=True)  # type: ignore[misc]
+def pytest_exception_interact(node: Function, call: pytest.CallInfo, report: pytest.TestReport) -> None:
+    if call.excinfo and call.excinfo.type is FailureGroup:
+        tb_entries = list(call.excinfo.traceback)
+        total_frames = len(tb_entries)
+
+        # Keep internal Schemathesis frames + one extra one from the caller
+        keep_from_index = 0
+        for i in range(total_frames - 1, -1, -1):
+            entry = tb_entries[i]
+
+            if "validate_response" in str(entry):
+                keep_from_index = max(0, i - 1)
+                break
+
+        skip_frames = keep_from_index
+
+        report.longrepr = "".join(format_exception(call.excinfo.value, with_traceback=True, skip_frames=skip_frames))
+
+
 @hookimpl(wrapper=True)
 def pytest_pyfunc_call(pyfuncitem):  # type:ignore
     """It is possible to have a Hypothesis exception in runtime.

schemathesis/schemas.py

@@ -211,7 +211,7 @@ class BaseSchema(Mapping):
         return self.statistic.operations.total
 
     def hook(self, hook: str | Callable) -> Callable:
-        return self.hooks.register(hook)
+        return self.hooks.hook(hook)
 
     def get_full_path(self, path: str) -> str:
         """Compute full path for the given path."""
@@ -368,7 +368,7 @@ class BaseSchema(Mapping):
         operation: APIOperation,
         hooks: HookDispatcher | None = None,
         auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
         raise NotImplementedError
@@ -396,7 +396,7 @@ class BaseSchema(Mapping):
         self,
         hooks: HookDispatcher | None = None,
         auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
         """Build a strategy for generating test cases for all defined API operations."""
@@ -424,6 +424,9 @@ class BaseSchema(Mapping):
             self.app = app
         return self
 
+    def find_operation_by_label(self, label: str) -> APIOperation | None:
+        raise NotImplementedError
+
 
 @dataclass
 class APIOperationMap(Mapping):
@@ -443,7 +446,7 @@ class APIOperationMap(Mapping):
         self,
         hooks: HookDispatcher | None = None,
         auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
         """Build a strategy for generating test cases for all API operations defined in this subset."""
@@ -643,14 +646,14 @@ class APIOperation(Generic[P]):
         self,
         hooks: HookDispatcher | None = None,
         auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy[Case]:
         """Turn this API operation into a Hypothesis strategy."""
         strategy = self.schema.get_case_strategy(self, hooks, auth_storage, generation_mode, **kwargs)
 
         def _apply_hooks(dispatcher: HookDispatcher, _strategy: SearchStrategy[Case]) -> SearchStrategy[Case]:
-            context = HookContext(self)
+            context = HookContext(operation=self)
             for hook in dispatcher.get_all_by_name("before_generate_case"):
                 _strategy = hook(context, _strategy)
             for hook in dispatcher.get_all_by_name("filter_case"):

schemathesis/specs/graphql/scalars.py

@@ -13,10 +13,44 @@ CUSTOM_SCALARS: dict[str, st.SearchStrategy[graphql.ValueNode]] = {}
 
 
 def scalar(name: str, strategy: st.SearchStrategy[graphql.ValueNode]) -> None:
-    """Register a new strategy for generating custom scalars.
+    r"""Register a custom Hypothesis strategy for generating GraphQL scalar values.
+
+    Args:
+        name: Scalar name that matches your GraphQL schema scalar definition
+        strategy: Hypothesis strategy that generates GraphQL AST ValueNode objects
+
+    Example:
+        ```python
+        import schemathesis
+        from hypothesis import strategies as st
+        from schemathesis.graphql import nodes
+
+        # Register email scalar
+        schemathesis.graphql.scalar("Email", st.emails().map(nodes.String))
+
+        # Register positive integer scalar
+        schemathesis.graphql.scalar(
+            "PositiveInt",
+            st.integers(min_value=1).map(nodes.Int)
+        )
+
+        # Register phone number scalar
+        schemathesis.graphql.scalar(
+            "Phone",
+            st.from_regex(r"\+1-\d{3}-\d{3}-\d{4}").map(nodes.String)
+        )
+        ```
+
+    Schema usage:
+        ```graphql
+        scalar Email
+        scalar PositiveInt
+
+        type Query {
+          getUser(email: Email!, rating: PositiveInt!): User
+        }
+        ```
 
-    :param str name: Scalar name. It should correspond the one used in the schema.
-    :param strategy: Hypothesis strategy you'd like to use to generate values for this scalar.
     """
     from hypothesis.strategies import SearchStrategy