pytest-httpchain 0.1.0__py3-none-any.whl

pytest_httpchain/carrier.py

@@ -0,0 +1,139 @@
+"""Test carrier class for HTTP chain test execution.
+
+The Carrier class manages the test lifecycle and infrastructure:
+- HTTP session initialization and cleanup
+- Global context state management
+- Test flow control (abort handling)
+- Integration with pytest (skip, fail)
+
+The actual HTTP execution and data processing is delegated to stage_executor.
+"""
+
+import logging
+from typing import Any, ClassVar
+
+import pytest
+import pytest_httpchain_templates.substitution
+import requests
+from pydantic import ValidationError
+from pytest_httpchain_models.entities import Scenario, Stage
+from pytest_httpchain_templates.exceptions import TemplatesError
+from pytest_httpchain_userfunc.auth import call_auth_function
+
+from . import stage_executor
+from .exceptions import StageExecutionError
+from .helpers import call_user_function
+
+logger = logging.getLogger(__name__)
+
+
+class Carrier:
+    """Test carrier class that integrates HTTP chain test execution.
+
+    This base class is subclassed dynamically by carrier_factory to create
+    test classes with scenario-specific test methods. It manages the shared
+    state and execution flow for all stages in a test scenario.
+
+    Attributes:
+        _scenario: The test scenario configuration
+        _session: Shared HTTP session for all stages
+        _data_context: Global context shared across all stages
+        _aborted: Flag indicating if test flow should be aborted
+    """
+
+    _scenario: ClassVar[Scenario]
+    _session: ClassVar[requests.Session | None] = None
+    _data_context: ClassVar[dict[str, Any]] = {}
+    _aborted: ClassVar[bool] = False
+
+    @classmethod
+    def setup_class(cls) -> None:
+        """Initialize the HTTP session and data context.
+
+        Called once before any test methods in the class are executed.
+        Sets up:
+        - Empty data context for variable storage
+        - HTTP session with SSL and authentication configuration
+
+        Note:
+            Authentication can be configured at scenario level and will
+            be applied to all requests unless overridden at stage level.
+        """
+        cls._data_context = {}
+        cls._session = requests.Session()
+
+        # Configure SSL settings
+        cls._session.verify = cls._scenario.ssl.verify
+        if cls._scenario.ssl.cert is not None:
+            cls._session.cert = cls._scenario.ssl.cert
+
+        # Configure authentication
+        if cls._scenario.auth:
+            resolved_auth = pytest_httpchain_templates.substitution.walk(cls._scenario.auth, cls._data_context)
+            auth_instance = call_user_function(resolved_auth, call_auth_function)
+            cls._session.auth = auth_instance
+
+    @classmethod
+    def teardown_class(cls) -> None:
+        """Clean up the HTTP session and reset state.
+
+        Called once after all test methods in the class have been executed.
+        Ensures proper cleanup of resources and state reset for next test class.
+        """
+        if cls._session:
+            cls._session.close()
+            cls._session = None
+        cls._data_context.clear()
+        cls._aborted = False
+
+    @classmethod
+    def execute_stage(cls, stage_template: Stage, fixture_kwargs: dict[str, Any]) -> None:
+        """Execute a test stage with abort handling and error management.
+
+        This method is called for each stage in the scenario. It handles:
+        - Checking abort status and skipping if needed
+        - Executing the stage via stage_executor
+        - Updating global context with saved variables
+        - Setting abort flag on errors
+
+        Args:
+            stage_template: The stage configuration containing request/response definitions
+            fixture_kwargs: Dictionary of pytest fixture values injected for this stage
+
+        Raises:
+            pytest.skip: If flow is aborted and stage doesn't have always_run=True
+            pytest.fail: If stage execution fails with an error
+
+        Note:
+            Sets cls._aborted to True on failure, causing subsequent stages
+            to be skipped unless they have always_run=True.
+        """
+        try:
+            # Check abort status
+            if cls._aborted and not stage_template.always_run:
+                pytest.skip(reason="Flow aborted")
+
+            # Verify session is initialized
+            if cls._session is None:
+                raise RuntimeError("Session not initialized - setup_class was not called")
+
+            # Execute stage and get variables to save globally
+            context_updates = stage_executor.execute_stage(
+                stage_template=stage_template,
+                scenario=cls._scenario,
+                session=cls._session,
+                global_context=cls._data_context,  # Pass current global state
+                fixture_kwargs=fixture_kwargs,
+            )
+
+            # Merge returned updates into global context for next stages
+            cls._data_context.update(context_updates)
+
+        except (
+            TemplatesError,
+            StageExecutionError,
+            ValidationError,
+        ) as e:
+            logger.exception(str(e))
+            cls._aborted = True
+            pytest.fail(reason=str(e), pytrace=False)

pytest_httpchain/carrier_factory.py

@@ -0,0 +1,92 @@
+"""Factory for creating dynamic test classes.
+
+This module provides functionality to dynamically generate pytest test classes
+from JSON scenario definitions. Each scenario becomes a test class with one
+test method per stage.
+"""
+
+import inspect
+import logging
+from typing import Any
+
+import pytest
+from pytest_httpchain_models.entities import Scenario, Stage
+from simpleeval import EvalWithCompoundTypes
+
+from .carrier import Carrier
+
+logger = logging.getLogger(__name__)
+
+
+def create_test_class(scenario: Scenario, class_name: str) -> type[Carrier]:
+    """Create a dynamic test class for the given scenario.
+
+    This factory function generates a pytest test class with:
+    - One test method per stage in the scenario
+    - Automatic fixture injection based on stage requirements
+    - Marker application (order, skip, xfail, etc.)
+    - Shared session and context management
+
+    The generated class structure:
+    - Inherits from Carrier base class
+    - Has test_0_<stage_name>, test_1_<stage_name>, etc. methods
+    - Each method requests fixtures defined in stage and scenario
+    - Methods are ordered using pytest-order plugin
+
+    Args:
+        scenario: Validated scenario configuration containing stages
+        class_name: Name for the generated test class
+
+    Returns:
+        A Carrier subclass with test methods for each stage
+
+    Example:
+        >>> scenario = Scenario.model_validate(test_data)
+        >>> TestClass = create_test_class(scenario, Path("test.json"), "TestAPI")
+        >>> # TestClass will have methods: test_0_stage1, test_1_stage2, etc.
+    """
+    # Create custom Carrier class with scenario bound
+    CustomCarrier = type(
+        class_name,
+        (Carrier,),
+        {
+            "_scenario": scenario,
+            "_session": None,
+            "_data_context": {},
+            "_aborted": False,
+        },
+    )
+
+    # Add stage methods dynamically
+    for i, stage in enumerate(scenario.stages):
+        # Create stage method - using default argument to capture stage
+        def stage_method(self, *, _stage: Stage = stage, **fixture_kwargs: dict[str, Any]) -> None:
+            """Execute a single stage of the test scenario.
+
+            Auto-generated method that executes one stage of the HTTP chain test.
+
+            Args:
+                **fixture_kwargs: Pytest fixtures requested by this stage
+            """
+            CustomCarrier.execute_stage(_stage, fixture_kwargs)
+
+        # Set up method signature with fixtures
+        all_fixtures: list[str] = ["self"] + stage.fixtures + scenario.fixtures
+        stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures])
+
+        # Apply markers
+        all_marks: list[str] = [f"order({i})"] + stage.marks
+        evaluator = EvalWithCompoundTypes(names={"pytest": pytest})
+        for mark_str in all_marks:
+            try:
+                marker = evaluator.eval(f"pytest.mark.{mark_str}")
+                if marker:
+                    stage_method = marker(stage_method)
+            except Exception as e:
+                logger.warning(f"Failed to create marker '{mark_str}': {e}")
+
+        # Add method to class with descriptive name
+        method_name = f"test_{i}_{stage.name}"
+        setattr(CustomCarrier, method_name, stage_method)
+
+    return CustomCarrier

pytest_httpchain/constants.py

@@ -0,0 +1,10 @@
+"""Constants for pytest-httpchain plugin."""
+
+from enum import StrEnum
+
+
+class ConfigOptions(StrEnum):
+    """Configuration option names for the pytest-httpchain plugin."""
+
+    SUFFIX = "suffix"
+    REF_PARENT_TRAVERSAL_DEPTH = "ref_parent_traversal_depth"

pytest_httpchain/context.py

@@ -0,0 +1,77 @@
+"""Context management for HTTP chain test execution.
+
+This module handles the preparation and management of execution contexts,
+maintaining the separation between global and local state.
+"""
+
+from collections import ChainMap
+from typing import Any
+
+import pytest_httpchain_templates.substitution
+from pytest_httpchain_models.entities import Scenario, Stage
+
+
+def prepare_data_context(
+    scenario: Scenario,
+    stage_template: Stage,
+    global_context: dict[str, Any],
+    fixture_kwargs: dict[str, Any],
+) -> ChainMap[str, Any]:
+    """Prepare the complete data context for stage execution.
+
+    Uses ChainMap for efficient layered context management with lazy evaluation.
+    No copying occurs - all layers share references to original data.
+
+    Merges contexts in order of precedence (later overrides earlier):
+    1. Global context (shared across all stages) - base layer
+    2. Fixture values (from pytest fixtures)
+    3. Scenario variables (from scenario.vars)
+    4. Stage variables (from stage.vars) - top layer
+
+    Each level can reference variables from previous levels in templates.
+
+    Args:
+        scenario: The scenario configuration
+        stage_template: The stage being executed
+        global_context: Shared context from previous stages
+        fixture_kwargs: Pytest fixture values for this stage
+
+    Returns:
+        ChainMap with layered context for efficient lookups
+
+    Note:
+        Returns a ChainMap for full performance benefits:
+        - No data copying
+        - Lazy evaluation (only accesses what's needed)
+        - Memory efficient (shares references)
+        - O(1) for most lookups
+    """
+    # Build layers incrementally - each layer can reference previous ones
+    # Template substitution now works directly with ChainMap
+
+    # Layer 1: Base context (global + fixtures)
+    base_context = ChainMap(fixture_kwargs, global_context)
+
+    # Layer 2: Scenario variables (can reference base)
+    scenario_vars = {}
+    if scenario.vars:
+        scenario_vars = pytest_httpchain_templates.substitution.walk(
+            scenario.vars,
+            base_context,  # Pass ChainMap directly
+        )
+
+    # Layer 3: Stage variables (can reference base + scenario)
+    # Process stage vars incrementally so they can reference each other
+    stage_vars = {}
+    if stage_template.vars:
+        context_with_scenario = ChainMap({}, scenario_vars, fixture_kwargs, global_context)
+        for key, value in stage_template.vars.items():
+            resolved_value = pytest_httpchain_templates.substitution.walk(value, context_with_scenario)
+            stage_vars[key] = resolved_value
+            # Add resolved var to context so next vars can reference it
+            context_with_scenario.maps[0][key] = resolved_value
+
+    # Create final context with proper precedence order
+    # Stage vars override scenario vars, which override fixtures, which override global
+    # Returns ChainMap for full performance benefits
+    return ChainMap(stage_vars, scenario_vars, fixture_kwargs, global_context)

pytest_httpchain/exceptions.py

@@ -0,0 +1,46 @@
+"""Exception classes for HTTP chain test execution.
+
+This module defines the exception hierarchy used throughout the
+pytest-httpchain test execution flow.
+"""
+
+
+class StageExecutionError(Exception):
+    """Base exception for all stage execution errors.
+
+    This is the base class for all exceptions that can occur during
+    stage execution. Catching this will catch all stage-related errors.
+    """
+
+
+class RequestError(StageExecutionError):
+    """Error during HTTP request preparation or execution.
+
+    Raised when:
+    - Request preparation fails (auth, file opening, etc.)
+    - HTTP request times out
+    - Connection errors occur
+    - Other request-related issues
+    """
+
+
+class SaveError(StageExecutionError):
+    """Error during response processing (save operations).
+
+    Raised when:
+    - JMESPath expression fails
+    - User save function fails
+    - Variable extraction fails
+    """
+
+
+class VerificationError(StageExecutionError):
+    """Error during response verification.
+
+    Raised when:
+    - Status code doesn't match expected
+    - Headers don't match expected
+    - Response body validation fails
+    - User verify function returns False
+    - JSON schema validation fails
+    """

pytest_httpchain/helpers.py

@@ -0,0 +1,43 @@
+"""Helper functions for common patterns in pytest-httpchain."""
+
+from collections.abc import Callable
+from typing import Any
+
+from pytest_httpchain_models.entities import UserFunctionCall, UserFunctionKwargs
+
+
+def call_user_function(
+    model: UserFunctionCall,
+    call_function: Callable,
+    *args: Any,
+    **extra_kwargs: Any,
+) -> Any:
+    """Generic helper to call user functions from UserFunctionCall model.
+
+    This helper eliminates the repeated pattern of checking whether a UserFunctionCall
+    is a UserFunctionName or UserFunctionKwargs and calling the appropriate function.
+
+    Args:
+        model: Either UserFunctionName or UserFunctionKwargs
+        call_function: The specific function caller (call_save_function, call_verify_function, etc.)
+        *args: Positional arguments to pass to call_function (e.g., response object)
+        **extra_kwargs: Additional keyword arguments for call_function
+
+    Returns:
+        Result from the called function
+
+    Example:
+        # Instead of:
+        if isinstance(func_item, UserFunctionKwargs):
+            result = call_save_function(func_item.function.root, response, **func_item.kwargs)
+        else:
+            result = call_save_function(func_item.root, response)
+
+        # Use:
+        result = call_user_function(func_item, call_save_function, response)
+    """
+    if isinstance(model, UserFunctionKwargs):
+        kwargs = {**extra_kwargs, **model.kwargs}
+        return call_function(model.function.root, *args, **kwargs)
+    else:  # UserFunctionName
+        return call_function(model.root, *args, **extra_kwargs)

pytest_httpchain/plugin.py

@@ -0,0 +1,192 @@
+"""Pytest plugin for HTTP chain testing.
+
+This module provides the pytest plugin hooks and collection logic for
+discovering and executing HTTP chain tests from JSON files.
+"""
+
+import logging
+import re
+import types
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import pytest
+import pytest_httpchain_jsonref.loader
+from _pytest import config, nodes, python, reports, runner
+from _pytest.config import argparsing
+from pydantic import ValidationError
+from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+from pytest_httpchain_models.entities import Scenario
+from simpleeval import EvalWithCompoundTypes
+
+from pytest_httpchain.constants import ConfigOptions
+
+from .carrier_factory import create_test_class
+
+logger = logging.getLogger(__name__)
+
+
+class JsonModule(python.Module):
+    """JSON test module that collects and executes HTTP chain tests.
+
+    This class extends pytest's Module to handle JSON test files containing
+    HTTP chain test scenarios. It loads, validates, and converts JSON test
+    definitions into executable pytest test classes.
+    """
+
+    def collect(self) -> Iterable[nodes.Item | nodes.Collector]:
+        """Collect test items from a JSON module.
+
+        This method:
+        1. Loads the JSON file with reference resolution
+        2. Validates the test scenario against the schema
+        3. Creates a dynamic test class using the factory
+        4. Yields the test class for pytest to execute
+
+        Yields:
+            python.Class: A pytest Class node containing test methods
+
+        Raises:
+            Collector.CollectError: If JSON loading or validation fails
+        """
+        # Load and validate the test scenario from JSON
+        ref_parent_traversal_depth = int(self.config.getini(ConfigOptions.REF_PARENT_TRAVERSAL_DEPTH))
+
+        try:
+            test_data = pytest_httpchain_jsonref.loader.load_json(
+                self.path,
+                max_parent_traversal_depth=ref_parent_traversal_depth,
+            )
+        except ReferenceResolverError as e:
+            raise nodes.Collector.CollectError("Cannot load JSON file") from e
+
+        try:
+            scenario = Scenario.model_validate(test_data)
+        except ValidationError as e:
+            raise nodes.Collector.CollectError("Cannot parse test scenario") from e
+
+        # Create test class using factory
+        CarrierClass = create_test_class(scenario, self.name)
+
+        # Create pytest Class node
+        dummy_module = types.ModuleType("generated")
+        setattr(dummy_module, self.name, CarrierClass)
+        self._getobj = lambda: dummy_module
+
+        json_class = python.Class.from_parent(
+            self,
+            path=self.path,
+            name=self.name,
+            obj=CarrierClass,
+        )
+
+        # Apply scenario-level markers
+        evaluator = EvalWithCompoundTypes(names={"pytest": pytest})
+        for mark_str in scenario.marks:
+            try:
+                marker = evaluator.eval(f"pytest.mark.{mark_str}")
+                if marker:
+                    json_class.add_marker(marker)
+            except Exception as e:
+                logger.warning(f"Failed to create marker '{mark_str}': {e}")
+
+        yield json_class
+
+
+def pytest_addoption(parser: argparsing.Parser) -> None:
+    """Add command-line options for the plugin.
+
+    Registers configuration options that can be set in pytest.ini:
+    - httpchain_suffix: File suffix for test files (default: "http")
+    - httpchain_ref_parent_traversal_depth: Max parent directory traversals in $ref paths
+
+    Args:
+        parser: Pytest's argument parser to add options to
+    """
+    parser.addini(
+        name=ConfigOptions.SUFFIX,
+        help="File suffix for HTTP test files.",
+        type="string",
+        default="http",
+    )
+    parser.addini(
+        name=ConfigOptions.REF_PARENT_TRAVERSAL_DEPTH,
+        help="Maximum number of parent directory traversals allowed in $ref paths.",
+        type="string",
+        default="3",
+    )
+
+
+def pytest_configure(config: config.Config) -> None:
+    """Validate configuration settings.
+
+    Ensures that configuration values are valid:
+    - Suffix must be alphanumeric with underscores/hyphens, max 32 chars
+    - Reference traversal depth must be non-negative
+
+    Args:
+        config: Pytest configuration object
+
+    Raises:
+        ValueError: If configuration values are invalid
+    """
+    suffix = str(config.getini(ConfigOptions.SUFFIX))
+    if not re.match(r"^[a-zA-Z0-9_-]{1,32}$", suffix):
+        raise ValueError("suffix must contain only alphanumeric characters, underscores, hyphens, and be ≤32 chars")
+
+    ref_parent_traversal_depth = int(config.getini(ConfigOptions.REF_PARENT_TRAVERSAL_DEPTH))
+    if ref_parent_traversal_depth < 0:
+        raise ValueError("Maximum number of parent directory traversals must be non-negative")
+
+
+def pytest_collect_file(file_path: Path, parent: nodes.Collector) -> nodes.Collector | None:
+    """Collect JSON test files matching the configured pattern.
+
+    This hook is called by pytest for each file in the test directory.
+    It checks if the file matches the pattern: test_<name>.<suffix>.json
+    where suffix is configurable (default: "http").
+
+    Args:
+        file_path: Path to the file being considered for collection
+        parent: The parent collector node
+
+    Returns:
+        JsonModule collector if file matches pattern, None otherwise
+
+    Example:
+        For suffix="http", these files would be collected:
+        - test_api.http.json
+        - test_user_flow.http.json
+
+    Configuration:
+        The suffix can be configured in pytest.ini:
+        [tool.pytest.ini_options]
+        httpchain_suffix = "api"  # Changes pattern to test_*.api.json
+    """
+    suffix: str = parent.config.getini(ConfigOptions.SUFFIX)
+    pattern = re.compile(rf"^test_(?P<name>.+)\.{re.escape(suffix)}\.json$")
+    file_match = pattern.match(file_path.name)
+    if file_match:
+        return JsonModule.from_parent(parent, path=file_path, name=file_match.group("name"))
+    return None
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item: nodes.Item, call: runner.CallInfo[Any]) -> Any:
+    """Add custom sections to test reports.
+
+    This hook adds additional information to test reports that can be
+    displayed in pytest output or used by other plugins.
+
+    Args:
+        item: The test item being reported on
+        call: Information about the test call
+
+    Yields:
+        The report with additional sections added
+    """
+    outcome = yield
+    report: reports.TestReport = outcome.get_result()
+    if call.when == "call":
+        report.sections.append(("call_title", "call_value"))

pytest_httpchain/request.py

@@ -0,0 +1,102 @@
+"""HTTP request preparation and execution for chain tests.
+
+This module handles the preparation of HTTP requests from test configurations
+and their execution using the requests library.
+"""
+
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any
+
+import requests
+from pytest_httpchain_models.entities import (
+    FilesBody,
+    FormBody,
+    JsonBody,
+    RawBody,
+    XmlBody,
+)
+from pytest_httpchain_models.entities import (
+    Request as RequestModel,
+)
+from pytest_httpchain_userfunc.auth import call_auth_function
+
+from .exceptions import RequestError
+from .helpers import call_user_function
+
+
+def prepare_and_execute(
+    session: requests.Session,
+    request_model: RequestModel,
+) -> requests.Response:
+    """Prepare and execute an HTTP request.
+
+    This function combines preparation and execution to avoid unnecessary
+    complexity. It handles authentication, different body types, and file
+    uploads with proper resource management.
+
+    Args:
+        session: HTTP session to use for the request
+        request_model: Validated request model
+
+    Returns:
+        HTTP response object
+
+    Raises:
+        RequestError: If request preparation or execution fails
+    """
+
+    # Base request kwargs
+    kwargs: dict[str, Any] = {
+        "method": request_model.method.value,
+        "url": str(request_model.url),
+        "headers": request_model.headers,
+        "params": request_model.params,
+        "timeout": request_model.timeout,
+        "allow_redirects": request_model.allow_redirects,
+        "verify": request_model.ssl.verify,
+    }
+
+    # Add SSL cert if present
+    if request_model.ssl.cert:
+        kwargs["cert"] = request_model.ssl.cert
+
+    # Configure auth if present
+    if request_model.auth:
+        try:
+            kwargs["auth"] = call_user_function(request_model.auth, call_auth_function)
+        except Exception as e:
+            raise RequestError("Failed to configure authentication") from e
+
+    # Handle different body types
+    match request_model.body:
+        case None:
+            pass
+        case JsonBody(json=data):
+            kwargs["json"] = data
+        case FormBody(form=data) | XmlBody(xml=data) | RawBody(raw=data):
+            kwargs["data"] = data
+        case FilesBody(files=file_paths):
+            # Handle file uploads with context manager
+            with ExitStack() as stack:
+                try:
+                    files_dict = {}
+                    for field_name, file_path in file_paths.items():
+                        file_handle = stack.enter_context(open(file_path, "rb"))
+                        files_dict[field_name] = (Path(file_path).name, file_handle)
+                    kwargs["files"] = files_dict
+
+                    return session.request(**kwargs)
+                except FileNotFoundError as e:
+                    raise RequestError("File not found for upload") from e
+
+    try:
+        return session.request(**kwargs)
+    except requests.Timeout as e:
+        raise RequestError("HTTP request timed out") from e
+    except requests.ConnectionError as e:
+        raise RequestError("HTTP connection error") from e
+    except requests.RequestException as e:
+        raise RequestError("HTTP request failed") from e
+    except Exception as e:
+        raise RequestError("Unexpected error") from e

pytest_httpchain/response.py

@@ -0,0 +1,165 @@
+"""Response processing and verification for HTTP chain tests.
+
+This module handles the processing of HTTP responses including data extraction
+(save operations) and verification of response content.
+"""
+
+import json
+import re
+from collections import ChainMap
+from pathlib import Path
+from typing import Any
+
+import jmespath
+import jsonschema
+import requests
+from pytest_httpchain_models.entities import Save, Verify
+from pytest_httpchain_models.types import check_json_schema
+from pytest_httpchain_userfunc.save import call_save_function
+from pytest_httpchain_userfunc.verify import call_verify_function
+
+from .exceptions import SaveError, VerificationError
+from .helpers import call_user_function
+
+
+def process_save_step(
+    save_model: Save,
+    response: requests.Response,
+) -> dict[str, Any]:
+    """Process a save step and return variables to be saved to global context.
+
+    Extracts data from the response using:
+    - JMESPath expressions for JSON responses
+    - User-defined save functions for custom extraction
+
+    Args:
+        save_model: Validated Save model
+        response: HTTP response object
+
+    Returns:
+        Dictionary of variables to add to global context
+
+    Raises:
+        ResponseError: If variable extraction fails
+
+    Note:
+        Save functions must conform to the SaveFunction protocol,
+        accepting a response and returning a dict[str, Any].
+    """
+    result: dict[str, Any] = {}
+
+    # Extract JSON only if we need it for JMESPath expressions
+    if len(save_model.vars) > 0:
+        try:
+            response_json = response.json()
+        except (requests.JSONDecodeError, UnicodeDecodeError) as e:
+            raise SaveError("Cannot extract variables: response is not valid JSON") from e
+
+        for var_name, jmespath_expr in save_model.vars.items():
+            try:
+                saved_value = jmespath.search(jmespath_expr, response_json)
+                result[var_name] = saved_value
+            except jmespath.exceptions.JMESPathError as e:
+                raise SaveError(f"Error saving variable {var_name}") from e
+
+    for func_item in save_model.functions:
+        try:
+            func_result = call_user_function(func_item, call_save_function, response)
+            result.update(func_result)
+        except Exception as e:
+            raise SaveError(f"Error calling user function {func_item}") from e
+
+    return result
+
+
+def process_verify_step(
+    verify_model: Verify,
+    local_context: ChainMap[str, Any],
+    response: requests.Response,
+) -> None:
+    """Process a verify step and raise errors if verification fails.
+
+    Performs various verifications on the response:
+    - Status code matching
+    - Header value matching
+    - Variable value matching
+    - JSON schema validation
+    - Body content checks (contains/not_contains/matches/not_matches)
+    - User-defined verify functions
+
+    Args:
+        verify_model: Validated Verify model
+        local_context: Current execution context
+        response: HTTP response object
+
+    Raises:
+        VerificationError: If any verification fails
+
+    Note:
+        Verify functions must conform to the VerifyFunction protocol,
+        accepting a response and returning a bool.
+    """
+
+    if verify_model.status and response.status_code != verify_model.status.value:
+        raise VerificationError(f"Status code doesn't match: expected {verify_model.status.value}, got {response.status_code}")
+
+    for header_name, expected_value in verify_model.headers.items():
+        if response.headers.get(header_name) != expected_value:
+            raise VerificationError(f"Header '{header_name}' doesn't match: expected {expected_value}, got {response.headers.get(header_name)}")
+
+    for var_name, expected_value in verify_model.vars.items():
+        if var_name not in local_context:
+            raise VerificationError(f"Var '{var_name}' not found in data context")
+        if local_context[var_name] != expected_value:
+            raise VerificationError(f"Var '{var_name}' verification failed: expected {expected_value}, got {local_context[var_name]}")
+
+    for func_item in verify_model.functions:
+        try:
+            result = call_user_function(func_item, call_verify_function, response)
+
+            if not result:
+                raise VerificationError(f"Function '{func_item}' verification failed")
+
+        except Exception as e:
+            raise VerificationError(f"Error calling user function '{func_item}'") from e
+
+    if verify_model.body.schema:
+        schema = verify_model.body.schema
+        if isinstance(schema, str | Path):
+            schema_path = Path(schema)
+            try:
+                schema = json.loads(schema_path.read_text())
+                check_json_schema(schema)
+            except (OSError, json.JSONDecodeError) as e:
+                raise VerificationError(f"Error reading body schema file '{schema_path}'") from e
+            except jsonschema.SchemaError as e:
+                raise VerificationError(f"Invalid JSON Schema in file '{schema_path}': {e.message}") from e
+
+        # Extract JSON for schema validation
+        try:
+            response_json = response.json()
+        except (requests.JSONDecodeError, UnicodeDecodeError) as e:
+            raise VerificationError("Cannot validate schema: response is not valid JSON") from e
+
+        try:
+            jsonschema.validate(instance=response_json, schema=schema)
+        except jsonschema.ValidationError as e:
+            raise VerificationError("Body schema validation failed") from e
+        except jsonschema.SchemaError as e:
+            raise VerificationError("Invalid body validation schema") from e
+
+    for substring in verify_model.body.contains:
+        if substring not in response.text:
+            raise VerificationError(f"Body doesn't contain '{substring}'")
+
+    for substring in verify_model.body.not_contains:
+        if substring in response.text:
+            raise VerificationError(f"Body contains '{substring}' while it shouldn't")
+
+    for pattern in verify_model.body.matches:
+        if not re.search(pattern, response.text):
+            raise VerificationError(f"Body doesn't match '{pattern}'")
+
+    for pattern in verify_model.body.not_matches:
+        if re.search(pattern, response.text):
+            raise VerificationError(f"Body matches '{pattern}' while it shouldn't")

pytest_httpchain/stage_executor.py

@@ -0,0 +1,111 @@
+"""Stage execution logic for HTTP chain tests.
+
+This module orchestrates the execution of individual test stages by coordinating
+between the specialized modules:
+
+- context.py: Handles context preparation and management
+- request.py: Manages HTTP request building and execution
+- response.py: Processes responses (save and verify operations)
+- exceptions.py: Defines the exception hierarchy
+
+The main responsibility of this module is to coordinate the flow:
+1. Build local context using context module
+2. Prepare and execute request using request module
+3. Process response using response module
+4. Return updates for global context
+"""
+
+import logging
+from typing import Any
+
+import pytest_httpchain_templates.substitution
+import requests
+from pytest_httpchain_models.entities import (
+    Request,
+    Response,
+    Save,
+    SaveStep,
+    Scenario,
+    Stage,
+    Verify,
+    VerifyStep,
+)
+
+from .context import prepare_data_context
+from .request import prepare_and_execute
+from .response import process_save_step, process_verify_step
+
+logger = logging.getLogger(__name__)
+
+
+def execute_stage(
+    stage_template: Stage,
+    scenario: Scenario,
+    session: requests.Session,
+    global_context: dict[str, Any],
+    fixture_kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    """Execute a single stage and return context updates.
+
+    This is the main entry point for stage execution. It orchestrates:
+    1. Context preparation (merge global + fixtures + variables)
+    2. Template substitution for all stage elements
+    3. HTTP request preparation and execution
+    4. Response processing (save and verify steps)
+    5. Return updates for global context
+
+    Args:
+        stage_template: The stage definition (with templates)
+        scenario: The scenario configuration
+        session: HTTP session for requests
+        global_context: Shared context from previous stages (read-only)
+        fixture_kwargs: Values from pytest fixtures
+
+    Returns:
+        Context updates to be merged into global context.
+        Only includes variables from SaveStep operations.
+
+    Raises:
+        RequestError: HTTP request preparation/execution failed
+        ResponseError: Response processing (save) failed
+        VerificationError: Response verification failed
+
+    Note:
+        The function maintains a clear separation between global and local
+        context. Only SaveStep results are returned for global updates.
+    """
+    # Build local context for this stage (global + fixtures + vars)
+    local_context = prepare_data_context(scenario=scenario, stage_template=stage_template, global_context=global_context, fixture_kwargs=fixture_kwargs)
+
+    # Resolve stage template with complete local context
+    stage = pytest_httpchain_templates.substitution.walk(stage_template, local_context)
+
+    # Prepare and execute request
+    request_dict = pytest_httpchain_templates.substitution.walk(stage.request, local_context)
+    request_model = Request.model_validate(request_dict)
+    response = prepare_and_execute(session, request_model)
+
+    # Process response
+    response_dict = pytest_httpchain_templates.substitution.walk(stage.response, local_context)
+    response_model = Response.model_validate(response_dict)
+
+    # Track what needs to be saved to global context
+    global_context_updates: dict[str, Any] = {}
+
+    for step in response_model:
+        match step:
+            case SaveStep():
+                save_dict = pytest_httpchain_templates.substitution.walk(step.save, local_context)
+                save_model = Save.model_validate(save_dict)
+                saved_vars = process_save_step(save_model, response)
+                # Add saved vars as a new layer in ChainMap for subsequent steps
+                local_context = local_context.new_child(saved_vars)
+                global_context_updates.update(saved_vars)
+
+            case VerifyStep():
+                verify_dict = pytest_httpchain_templates.substitution.walk(step.verify, local_context)
+                verify_model = Verify.model_validate(verify_dict)
+                process_verify_step(verify_model, local_context, response)
+
+    # Return only the updates that should persist globally
+    return global_context_updates

pytest_httpchain-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: pytest-httpchain
+Version: 0.1.0
+Summary: pytest plugin for HTTP testing using JSON files
+Keywords: testing,pytest,requests
+Author: Alexander Eresov
+Author-email: Alexander Eresov <aeresov@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pytest-httpchain-jsonref
+Requires-Dist: pytest-httpchain-models
+Requires-Dist: pytest-order>=1.3.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pytest-httpchain-mcp ; extra == 'mcp'
+Requires-Python: >=3.13, <4.0
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+[![image](https://img.shields.io/pypi/v/pytest-httpchain)](https://pypi.python.org/pypi/pytest-httpchain)
+[![image](https://img.shields.io/pypi/l/pytest-httpchain)](https://github.com/aeresov/pytest-httpchain/blob/main/LICENSE)
+[![image](https://img.shields.io/pypi/pyversions/pytest-httpchain)](https://pypi.python.org/pypi/pytest-httpchain)
+
+# pytest-httpchain
+
+A pytest plugin for testing HTTP endpoints.
+
+## Overview
+
+`pytest-httpchain` is an integration testing framework for HTTP APIs based on battle-hardened [requests](https://requests.readthedocs.io) lib.\
+It aims at helping with common HTTP API testing scenarios, where user needs to make several calls in specific order using data obtained along the way, like auth tokens or resource ids.
+
+## Installation
+
+Install normally via package manager of your choice from PyPi:
+
+```bash
+pip install pytest-httpchain
+```
+
+or directly from Github, in case you need a particular ref:
+
+```bash
+pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
+```
+
+### Optional dependencies
+
+The following optional dependencies are available:
+
+-   `mcp`: installs MCP server package and its starting script. Details in [MCP Server](#mcp-server).
+
+## Features
+
+### Pytest integration
+
+Most of pytest magic can be used: markers, fixtures, other plugins.\
+
+> NOTE: parametrization is not yet implemented, therefore `parametrize` marker won't have any effect.
+
+### Declarative format
+
+Test scenarios are written declaratively in JSON files.\
+`pytest-httpchain` supports JSONRef, so use can reuse arbitrary parts of your scenarios with `$ref` directive.\
+Properties are merged in a greedy way with type checking.
+
+### Multi-stage tests
+
+Each test scenario contains 1+ stages; each stage is a single HTTP call.\
+`pytest-httpchain` executes stages in the order they are listed in scenario file; one stage failure stops the execution chain.
+
+### Common data context and variable substitution
+
+`pytest-httpchain` maintains key-value data storage throughout the execution.\
+This storage ("common data context") is populated with declared variables, fixtures and data saved by stages. The data remains there throughout the scenario execution.\
+Writing scenarios, you can use Jinja-style expressions like `"{{ var }}"` for JSON values. `pytest-httpchain` does variable substitution dynamically right before executing a stage, and uses common data context keys as variables in these expressions.\
+Values from common data context also might be verified during verified/asserted.
+
+### User functions
+
+`pytest-httpchain` can import and call regular python functions:
+
+-   to extract data from HTTP response
+-   to verify HTTP response and values in common data context
+-   to provide [custom authentication for requests](https://requests.readthedocs.io/en/latest/user/advanced/#custom-authentication)
+
+### JMESPath support
+
+`pytest-httpchain` can extract values from JSON responses using JMESPath expressions directly.
+
+### JSON schema support
+
+`pytest-httpchain` can verify JSON reponses against user-defined JSON schema.
+
+## Quick Start
+
+Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix is `http`):
+
+```python
+# conftest.py
+import pytest
+from datetime import datetime
+
+@pytest.fixture
+def now_utc():
+    return datetime.now()
+```
+
+```json
+{
+    "vars": {
+        "user_id": 1
+    },
+    "stages": [
+        {
+            "name": "get_user",
+            "request": {
+                "url": "https://api.example.com/users/{{ user_id }}"
+            },
+            "response": [
+                {
+                    "verify": {
+                        "status": 200
+                    }
+                },
+                {
+                    "save": {
+                        "vars": {
+                            "user_name": "user.name"
+                        }
+                    }
+                }
+            ]
+        },
+        {
+            "name": "update_user",
+            "fixtures": ["now_utc"],
+            "request": {
+                "url": "https://api.example.com/users/{{ user_id }}",
+                "method": "PUT",
+                "body": {
+                    "json": {
+                        "user": {
+                            "name": "{{ user_name }}_updated",
+                            "timestamp": "{{ str(now_utc) }}"
+                        }
+                    }
+                }
+            },
+            "response": [
+                {
+                    "verify": {
+                        "status": 200
+                    }
+                }
+            ]
+        },
+        {
+            "name": "cleanup",
+            "always_run": true,
+            "request": {
+                "url": "https://api.example.com/cleanup",
+                "method": "POST"
+            }
+        }
+    ]
+}
+```
+
+Scenario we created:
+
+-   common data context is seeded with the first variable `user_id`
+-   **get_user**\
+    url is assembled using `user_id` variable from common data context\
+    HTTP GET call is made\
+    we verify the call returned code 200\
+    assuming JSON body is returned, we extract a value by JMESPath expression `user.name` and save it to common data context under `user_name` key
+-   **update_user**\
+    `now_utc` fixture value is injected into common data context\
+    url is assembled using `user_id` variable from common data context\
+    we create JSON body in place using values from common data context, note that `now_utc` is converted to string in place\
+    HTTP PUT call with body is made\
+    we verify the call returned code 200\
+-   **cleanup**\
+    finalizing call meant for graceful exit\
+    `always_run` parameter means this stage will be executed regardless of errors in previous stages
+
+For detailed examples see [USAGE.md](USAGE.md).
+
+## Configuration
+
+-   Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.\
+    The `suffix` is configurable as pytest ini option, default value is **http**.
+-   `$ref` instructions can point to other files; absolute and relative paths are supported.\
+    You can limit the depth of relative path traversal using `ref_parent_traversal_depth` ini option, default value is **3**.
+
+## MCP Server
+
+`pytest-httpchain` includes an MCP (Model Context Protocol) server to aid AI code assistants.
+
+### Installation
+
+The optional dependency `mcp` installs MCP server's package and `pytest-httpchain-mcp` script.\
+Use this script as call target for your MCP configuration.
+
+Claude Code `.mcp.json` example:
+
+```json
+{
+    "mcpServers": {
+        "pytest-httpchain": {
+            "type": "stdio",
+            "command": "uv",
+            "args": ["run", "pytest-httpchain-mcp"],
+            "env": {}
+        }
+    }
+}
+```
+
+### Features
+
+The MCP server provides:
+
+-   **Scenario validation** - validate test scenario and scan for possible problems
+
+## Documentation
+
+-   [Usage Examples](USAGE.md) - Practical code examples
+-   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete guide
+-   [Changelog](CHANGELOG.md) - Release notes
+
+## Thanks
+
+`pytest-httpchain` was heavily inspired by [Tavern](https://github.com/taverntesting/tavern) and [pytest-play](https://github.com/davidemoro/pytest-play).  
+[requests](https://requests.readthedocs.io) does the comms.  
+[Pydantic](https://docs.pydantic.dev) keeps the structure.  
+[pytest-order](https://github.com/pytest-dev/pytest-order) powers the chaining.  
+[pytest-datadir](https://github.com/gabrielcnr/pytest-datadir) saved me a lot of elbow grease.  

pytest_httpchain-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pytest_httpchain/__init__.py,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+pytest_httpchain/carrier.py,sha256=e696c8ea2e50e8c447816ea881bf4bb7cd4dc477e6f2b6f0d8e62dd107972b1b,5156
+pytest_httpchain/carrier_factory.py,sha256=4d2f64a6c0cdf81ee4c826d30412f71f7ae742a77c9482e97d9971534dcd917d,3363
+pytest_httpchain/constants.py,sha256=f7801ebd9317048468e1f4cc99858a3bd85dfafb6d475ab0f6bd344fa1814891,258
+pytest_httpchain/context.py,sha256=b082e8026db698e61821e0884fa1a3629b3bc3535c8a5ed6bcf074318f805d20,3035
+pytest_httpchain/exceptions.py,sha256=8cb12a71213596999b974064c0d89cc13c51fedfbf456ad5a6cbc8366f21772d,1209
+pytest_httpchain/helpers.py,sha256=ed12adcedc1bafe3060d168007f2052cc208552a0b1615ab7c58bdbc6e3f1bab,1597
+pytest_httpchain/plugin.py,sha256=522eaaa4a05f3b108c10c55867b28ee78167853f22ad9d4d092f75f880c0af1c,6701
+pytest_httpchain/request.py,sha256=d81ea9f90e0fc0ad9d3304da74abb7902e6827d2646a8a7c5d44272dc2a565f0,3327
+pytest_httpchain/response.py,sha256=9f023c48292fb7e87c57c00f37b5f782a23354a9f7c40a452397b9a746fa0007,6350
+pytest_httpchain/stage_executor.py,sha256=fb2c887cd4c77cd06f8911e1e2aa5d6d7196cff08bd8d17eb28ffd7fb44dfcb0,4209
+pytest_httpchain-0.1.0.dist-info/licenses/LICENSE,sha256=bcfbbc70256347518043fadc1e07484d958b8292c930f7745e6d083d583a35f5,1064
+pytest_httpchain-0.1.0.dist-info/WHEEL,sha256=ab6157bc637547491fb4567cd7ddf26b04d63382916ca16c29a5c8e94c9c9ef7,79
+pytest_httpchain-0.1.0.dist-info/entry_points.txt,sha256=7db8dc2819e062d7e780e1375205a8441e75757e09da2ace5eda7ae579f73616,55
+pytest_httpchain-0.1.0.dist-info/METADATA,sha256=14d4bd19c84e522a5f3650fc6332e3135908fff65251ce35e2095c546b84dbd9,8426
+pytest_httpchain-0.1.0.dist-info/RECORD,,

pytest_httpchain-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.7.22
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_httpchain-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+pytest_httpchain = pytest_httpchain.plugin
+

pytest_httpchain-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 aeresov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.