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

schemathesis/generation/stateful/__init__.py

@@ -7,6 +7,21 @@ if TYPE_CHECKING:
 
     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
@@ -17,4 +32,6 @@ def run_state_machine_as_test(
     """
     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)

schemathesis/generation/stateful/state_machine.py

@@ -129,9 +129,10 @@ def _normalize_name(name: str) -> str:
 
 
 class APIStateMachine(RuleBasedStateMachine):
-    """The base class for state machines generated from API schemas.
+    """State machine for executing API operation sequences based on OpenAPI links.
 
-    Exposes additional extension points in the testing process.
+    Automatically generates test scenarios by chaining API operations according
+    to their defined relationships in the schema.
     """
 
     # This is a convenience attribute, which happened to clash with `RuleBasedStateMachine` instance level attribute
@@ -193,16 +194,22 @@ class APIStateMachine(RuleBasedStateMachine):
 
     @classmethod
     def run(cls, *, settings: hypothesis.settings | None = None) -> None:
-        """Run state machine as a test."""
+        """Execute the state machine test scenarios.
+
+        Args:
+            settings: Hypothesis settings for test execution.
+
+        """
         from . import run_state_machine_as_test
 
+        __tracebackhide__ = True
         return run_state_machine_as_test(cls, settings=settings)
 
     def setup(self) -> None:
-        """Hook method that runs unconditionally in the beginning of each test scenario."""
+        """Called once at the beginning of each test scenario."""
 
     def teardown(self) -> None:
-        pass
+        """Called once at the end of each test scenario."""
 
     # To provide the return type in the rendered documentation
     teardown.__doc__ = RuleBasedStateMachine.teardown.__doc__
@@ -212,14 +219,6 @@ class APIStateMachine(RuleBasedStateMachine):
         return self.step(input)
 
     def step(self, input: StepInput) -> StepOutput:
-        """A single state machine step.
-
-        :param Case case: Generated test case data that should be sent in an API call to the tested API operation.
-        :param previous: Optional result from the previous step and the direction in which this step should be done.
-
-        Schemathesis prepares data, makes a call and validates the received response.
-        It is the most high-level point to extend the testing process. You probably don't need it in most cases.
-        """
         __tracebackhide__ = True
         self.before_call(input.case)
         kwargs = self.get_call_kwargs(input.case)
@@ -229,126 +228,51 @@ class APIStateMachine(RuleBasedStateMachine):
         return StepOutput(response, input.case)
 
     def before_call(self, case: Case) -> None:
-        """Hook method for modifying the case data before making a request.
-
-        :param Case case: Generated test case data that should be sent in an API call to the tested API operation.
+        """Called before each API operation in the scenario.
 
-        Use it if you want to inject static data, for example,
-        a query parameter that should always be used in API calls:
+        Args:
+            case: Test case data for the operation.
 
-        .. code-block:: python
-
-            class APIWorkflow(schema.as_state_machine()):
-                def before_call(self, case):
-                    case.query = case.query or {}
-                    case.query["test"] = "true"
-
-        You can also modify data only for some operations:
-
-        .. code-block:: python
-
-            class APIWorkflow(schema.as_state_machine()):
-                def before_call(self, case):
-                    if case.method == "PUT" and case.path == "/items":
-                        case.body["is_fake"] = True
         """
 
     def after_call(self, response: Response, case: Case) -> None:
-        """Hook method for additional actions with case or response instances.
-
-        :param response: Response from the application under test.
-        :param Case case: Generated test case data that should be sent in an API call to the tested API operation.
-
-        For example, you can log all response statuses by using this hook:
-
-        .. code-block:: python
-
-            import logging
+        """Called after each API operation in the scenario.
 
-            logger = logging.getLogger(__file__)
-            logger.setLevel(logging.INFO)
+        Args:
+            response: HTTP response from the operation.
+            case: Test case data that was executed.
 
-
-            class APIWorkflow(schema.as_state_machine()):
-                def after_call(self, response, case):
-                    logger.info(
-                        "%s %s -> %d",
-                        case.method,
-                        case.path,
-                        response.status_code,
-                    )
-
-
-            # POST /users/ -> 201
-            # GET /users/{user_id} -> 200
-            # PATCH /users/{user_id} -> 200
-            # GET /users/{user_id} -> 200
-            # PATCH /users/{user_id} -> 500
         """
 
     def call(self, case: Case, **kwargs: Any) -> Response:
-        """Make a request to the API.
-
-        :param Case case: Generated test case data that should be sent in an API call to the tested API operation.
-        :param kwargs: Keyword arguments that will be passed to the appropriate ``case.call_*`` method.
-        :return: Response from the application under test.
-
-        Note that WSGI/ASGI applications are detected automatically in this method. Depending on the result of this
-        detection the state machine will call the ``call`` method.
-
-        Usually, you don't need to override this method unless you are building a different state machine on top of this
-        one and want to customize the transport layer itself.
-        """
         return case.call(**kwargs)
 
     def get_call_kwargs(self, case: Case) -> dict[str, Any]:
-        """Create custom keyword arguments that will be passed to the :meth:`Case.call` method.
-
-        Mostly they are proxied to the :func:`requests.request` call.
+        """Returns keyword arguments for the API call.
 
-        :param Case case: Generated test case data that should be sent in an API call to the tested API operation.
+        Args:
+            case: Test case being executed.
 
-        .. code-block:: python
+        Returns:
+            Dictionary passed to the `case.call()` method.
 
-            class APIWorkflow(schema.as_state_machine()):
-                def get_call_kwargs(self, case):
-                    return {"verify": False}
-
-        The above example disables the server's TLS certificate verification.
         """
         return {}
 
     def validate_response(
         self, response: Response, case: Case, additional_checks: list[CheckFunction] | None = None, **kwargs: Any
     ) -> None:
-        """Validate an API response.
-
-        :param response: Response from the application under test.
-        :param Case case: Generated test case data that should be sent in an API call to the tested API operation.
-        :param additional_checks: A list of checks that will be run together with the default ones.
-        :raises FailureGroup: If any of the supplied checks failed.
-
-        If you need to change the default checks or provide custom validation rules, you can do it here.
-
-        .. code-block:: python
-
-            def my_check(response, case):
-                ...  # some assertions
-
-
-            class APIWorkflow(schema.as_state_machine()):
-                def validate_response(self, response, case):
-                    case.validate_response(response, checks=(my_check,))
+        """Validates the API response using configured checks.
 
-        The state machine from the example above will execute only the ``my_check`` check instead of all
-        available checks.
+        Args:
+            response: HTTP response to validate.
+            case: Test case that generated the response.
+            additional_checks: Extra validation functions to run.
+            kwargs: Transport-level keyword arguments.
 
-        Each check function should accept ``response`` as the first argument and ``case`` as the second one and raise
-        ``AssertionError`` if the check fails.
+        Raises:
+            FailureGroup: When validation checks fail.
 
-        **Note** that it is preferred to pass check functions as an argument to ``case.validate_response``.
-        In this case, all checks will be executed, and you'll receive a grouped exception that contains results from
-        all provided checks rather than only the first encountered exception.
         """
         __tracebackhide__ = True
         case.validate_response(response, additional_checks=additional_checks, transport_kwargs=kwargs)

schemathesis/graphql/loaders.py

@@ -19,15 +19,54 @@ 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)
     response = load_from_url(client.post, url=path, **kwargs)
     schema = extract_schema_from_response(response, lambda r: r.json())
-    return from_dict(schema=schema, config=config).configure(app=app, location=path)
+    loaded = from_dict(schema=schema, config=config)
+    loaded.app = app
+    loaded.location = path
+    return loaded
 
 
 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()})
@@ -35,31 +74,104 @@ def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None,
     response = client.post(path=path, **kwargs)
     raise_for_status(response)
     schema = extract_schema_from_response(response, lambda r: r.json)
-    return from_dict(schema=schema, config=config).configure(app=app, location=path)
+    loaded = from_dict(schema=schema, config=config)
+    loaded.app = app
+    loaded.location = path
+    return loaded
 
 
 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()})
     response = load_from_url(requests.post, url=url, wait_for_schema=wait_for_schema, **kwargs)
     schema = extract_schema_from_response(response, lambda r: r.json())
-    return from_dict(schema, config=config).configure(location=url)
+    loaded = from_dict(schema, config=config)
+    loaded.location = url
+    return loaded
 
 
 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())
+        loaded = from_file(file=file, config=config)
+    loaded.location = Path(path).absolute().as_uri()
+    return loaded
 
 
 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 +199,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.
+        self.hook = to_filterable_hook(self)  # type: ignore[method-assign]
 
-        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
-
-            @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:
@@ -248,10 +231,7 @@ class HookDispatcher:
             hook(context, *args, **kwargs)
 
     def unregister(self, hook: Callable) -> None:
-        """Unregister a specific hook.
-
-        :param hook: A hook function to unregister.
-        """
+        """Unregister a specific hook."""
         # It removes this function from all places
         for hooks in self._hooks.values():
             hooks[:] = [item for item in hooks if item is not hook]
@@ -391,6 +371,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__