pytest-httpchain 0.2.1__tar.gz → 0.2.4__tar.gz

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-httpchain
-Version: 0.2.1
+Version: 0.2.4
 Summary: pytest plugin for HTTP testing using JSON files
 Keywords: testing,pytest,requests
 Author: Alexander Eresov
@@ -18,11 +18,11 @@ Requires-Dist: httpx[http2]>=0.27.0
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pyrate-limiter>=3.0.0
 Requires-Dist: pytest-httpchain-jsonref
+Requires-Dist: pytest-httpchain-mcp
 Requires-Dist: pytest-httpchain-models
 Requires-Dist: pytest-order>=1.3.0
-Requires-Dist: pytest-httpchain-mcp ; extra == 'mcp'
+Requires-Dist: typer>=0.16.0
 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)
@@ -38,66 +38,44 @@ A pytest plugin for testing HTTP endpoints.
 `pytest-httpchain` is an integration testing framework for HTTP APIs based on [httpx](https://www.python-httpx.org) 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:
+## Why pytest-httpchain?
 
-```bash
-pip install pytest-httpchain
-```
+Testing HTTP APIs with plain pytest often leads to these pain points:
 
-or directly from Github, in case you need a particular ref:
+-   **Boilerplate accumulates** — Every test repeats the same setup: create client, set headers, make request, parse response, assert. The actual test intent gets buried.
+-   **Data threading is manual** — When one call returns a token or ID needed by the next, you end up with fragile helper functions passing state around.
+-   **Common patterns get copy-pasted** — Auth flows, base URLs, shared headers end up duplicated across test files. Fixtures might help, but they are not designed for that.
+-   **Code reviews are noisy** — The actual test logic is rarely clear because of all the boilerplate and helpers, following changes gets overwhelming quickly.
 
-```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).
+`pytest-httpchain` offers a more structured approach.
 
 ## Features
 
-### Pytest integration
-
-Most of pytest magic can be used: markers, fixtures, other plugins.
-
-### Declarative format
+### Declarative JSON 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.
+Test scenarios are JSON documents that describe _what_ to test, not _how_. No setup code to scroll through — the request and assertions are right there.
 
-### Multi-stage tests
+### `$ref` with deep merging
 
-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.
+Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type checking, so you can compose scenarios from shared fragments (auth flows, common headers, base URLs).
 
-### Common data context and variable substitution
+### Multi-stage execution
 
-`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.
+Each scenario contains 1+ stages executed in order. One stage failure stops the chain. Use `always_run` for cleanup stages that should execute regardless.
 
-### User functions
+### Common data context
 
-`pytest-httpchain` can import and call regular python functions:
+A key-value store persists throughout scenario execution. Variables, fixtures, and saved response data all live here. Use template expressions (`{{ var }}`) anywhere in your requests — substitution happens dynamically before each stage.
 
--   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)
--   to call in substitution expressions
+### Response processing
 
-### JMESPath support
+-   **JMESPath** — Extract values from JSON responses directly
+-   **JSON Schema** — Validate response structure against a schema
+-   **User functions** — Call Python functions for custom extraction, verification, or [authentication](https://requests.readthedocs.io/en/latest/user/advanced/#custom-authentication)
 
-`pytest-httpchain` can extract values from JSON responses using JMESPath expressions directly.
+### Full pytest integration
 
-### JSON schema support
-
-`pytest-httpchain` can verify JSON reponses against user-defined JSON schema.
+Markers, fixtures, parametrization, and other plugins work as expected. You're not locked into a separate ecosystem.
 
 ## Quick Start
 
@@ -122,9 +100,8 @@ def now_utc():
             }
         }
     ],
-    "stages": [
-        {
-            "name": "get_user",
+    "stages": {
+        "get_user": {
             "request": {
                 "url": "https://api.example.com/users/{{ user_id }}"
             },
@@ -143,8 +120,7 @@ def now_utc():
                 }
             ]
         },
-        {
-            "name": "update_user",
+        "update_user": {
             "fixtures": ["now_utc"],
             "request": {
                 "url": "https://api.example.com/users/{{ user_id }}",
@@ -166,15 +142,14 @@ def now_utc():
                 }
             ]
         },
-        {
-            "name": "cleanup",
+        "cleanup": {
             "always_run": true,
             "request": {
                 "url": "https://api.example.com/cleanup",
                 "method": "POST"
             }
         }
-    ]
+    }
 }
 ```
 
@@ -196,34 +171,51 @@ Scenario we created:
     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).
+For detailed usage guide see the [full documentation](https://aeresov.github.io/pytest-httpchain).
+
+## 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'
+```
 
 ## Configuration
 
--   Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.  
+-   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.  
+-   `$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**.
+-   Template expressions support list/dict comprehensions. You can limit the maximum comprehension length using `max_comprehension_length` ini option, default value is **50000**.
+-   Parallel stage iterations (repeat/foreach) have a safety limit configurable via `max_parallel_iterations` ini option, default value is **10000**.
 
 ## MCP Server
 
 `pytest-httpchain` includes an MCP (Model Context Protocol) server to aid AI code assistants.
 
-### Installation
+### Setup
 
-The optional dependency `mcp` installs MCP server's package and `pytest-httpchain-mcp` script.  
-Use this script as call target for your MCP configuration.
+Install the MCP server config and Claude Code skill into your project:
 
-Claude Code `.mcp.json` example:
+```bash
+uvx pytest-httpchain install --skill --mcp
+```
+
+Or configure manually in `.mcp.json`:
 
 ```json
 {
     "mcpServers": {
         "pytest-httpchain": {
-            "type": "stdio",
-            "command": "uv",
-            "args": ["run", "pytest-httpchain-mcp"],
-            "env": {}
+            "command": "uvx",
+            "args": ["pytest-httpchain", "mcp"]
         }
     }
 }
@@ -234,16 +226,17 @@ Claude Code `.mcp.json` example:
 The MCP server provides:
 
 -   **Scenario validation** - validate test scenario and scan for possible problems
+-   **Claude Code skill** - authoring guidance for writing test scenarios
 
 ## Documentation
 
--   [Usage Examples](USAGE.md) - Practical code examples
--   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete guide
+-   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete usage guide
 -   [Changelog](CHANGELOG.md) - Release notes
 
 ## Thanks
 
-`pytest-httpchain` was inspired by [Tavern](https://github.com/taverntesting/tavern) and [pytest-play](https://github.com/davidemoro/pytest-play).  
+This project was inspired by [Tavern](https://github.com/taverntesting/tavern) and [pytest-play](https://github.com/davidemoro/pytest-play).  
+
 [httpx](https://www.python-httpx.org) does comms.  
 [Pydantic](https://docs.pydantic.dev) keeps structure.  
 [simpleeval](https://github.com/danthedeckie/simpleeval) powers templates.  

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/README.md

@@ -11,66 +11,44 @@ A pytest plugin for testing HTTP endpoints.
 `pytest-httpchain` is an integration testing framework for HTTP APIs based on [httpx](https://www.python-httpx.org) 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:
+## Why pytest-httpchain?
 
-```bash
-pip install pytest-httpchain
-```
+Testing HTTP APIs with plain pytest often leads to these pain points:
 
-or directly from Github, in case you need a particular ref:
+-   **Boilerplate accumulates** — Every test repeats the same setup: create client, set headers, make request, parse response, assert. The actual test intent gets buried.
+-   **Data threading is manual** — When one call returns a token or ID needed by the next, you end up with fragile helper functions passing state around.
+-   **Common patterns get copy-pasted** — Auth flows, base URLs, shared headers end up duplicated across test files. Fixtures might help, but they are not designed for that.
+-   **Code reviews are noisy** — The actual test logic is rarely clear because of all the boilerplate and helpers, following changes gets overwhelming quickly.
 
-```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).
+`pytest-httpchain` offers a more structured approach.
 
 ## Features
 
-### Pytest integration
-
-Most of pytest magic can be used: markers, fixtures, other plugins.
-
-### Declarative format
+### Declarative JSON 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.
+Test scenarios are JSON documents that describe _what_ to test, not _how_. No setup code to scroll through — the request and assertions are right there.
 
-### Multi-stage tests
+### `$ref` with deep merging
 
-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.
+Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type checking, so you can compose scenarios from shared fragments (auth flows, common headers, base URLs).
 
-### Common data context and variable substitution
+### Multi-stage execution
 
-`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.
+Each scenario contains 1+ stages executed in order. One stage failure stops the chain. Use `always_run` for cleanup stages that should execute regardless.
 
-### User functions
+### Common data context
 
-`pytest-httpchain` can import and call regular python functions:
+A key-value store persists throughout scenario execution. Variables, fixtures, and saved response data all live here. Use template expressions (`{{ var }}`) anywhere in your requests — substitution happens dynamically before each stage.
 
--   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)
--   to call in substitution expressions
+### Response processing
 
-### JMESPath support
+-   **JMESPath** — Extract values from JSON responses directly
+-   **JSON Schema** — Validate response structure against a schema
+-   **User functions** — Call Python functions for custom extraction, verification, or [authentication](https://requests.readthedocs.io/en/latest/user/advanced/#custom-authentication)
 
-`pytest-httpchain` can extract values from JSON responses using JMESPath expressions directly.
+### Full pytest integration
 
-### JSON schema support
-
-`pytest-httpchain` can verify JSON reponses against user-defined JSON schema.
+Markers, fixtures, parametrization, and other plugins work as expected. You're not locked into a separate ecosystem.
 
 ## Quick Start
 
@@ -95,9 +73,8 @@ def now_utc():
             }
         }
     ],
-    "stages": [
-        {
-            "name": "get_user",
+    "stages": {
+        "get_user": {
             "request": {
                 "url": "https://api.example.com/users/{{ user_id }}"
             },
@@ -116,8 +93,7 @@ def now_utc():
                 }
             ]
         },
-        {
-            "name": "update_user",
+        "update_user": {
             "fixtures": ["now_utc"],
             "request": {
                 "url": "https://api.example.com/users/{{ user_id }}",
@@ -139,15 +115,14 @@ def now_utc():
                 }
             ]
         },
-        {
-            "name": "cleanup",
+        "cleanup": {
             "always_run": true,
             "request": {
                 "url": "https://api.example.com/cleanup",
                 "method": "POST"
             }
         }
-    ]
+    }
 }
 ```
 
@@ -169,34 +144,51 @@ Scenario we created:
     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).
+For detailed usage guide see the [full documentation](https://aeresov.github.io/pytest-httpchain).
+
+## 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'
+```
 
 ## Configuration
 
--   Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.  
+-   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.  
+-   `$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**.
+-   Template expressions support list/dict comprehensions. You can limit the maximum comprehension length using `max_comprehension_length` ini option, default value is **50000**.
+-   Parallel stage iterations (repeat/foreach) have a safety limit configurable via `max_parallel_iterations` ini option, default value is **10000**.
 
 ## MCP Server
 
 `pytest-httpchain` includes an MCP (Model Context Protocol) server to aid AI code assistants.
 
-### Installation
+### Setup
 
-The optional dependency `mcp` installs MCP server's package and `pytest-httpchain-mcp` script.  
-Use this script as call target for your MCP configuration.
+Install the MCP server config and Claude Code skill into your project:
 
-Claude Code `.mcp.json` example:
+```bash
+uvx pytest-httpchain install --skill --mcp
+```
+
+Or configure manually in `.mcp.json`:
 
 ```json
 {
     "mcpServers": {
         "pytest-httpchain": {
-            "type": "stdio",
-            "command": "uv",
-            "args": ["run", "pytest-httpchain-mcp"],
-            "env": {}
+            "command": "uvx",
+            "args": ["pytest-httpchain", "mcp"]
         }
     }
 }
@@ -207,16 +199,17 @@ Claude Code `.mcp.json` example:
 The MCP server provides:
 
 -   **Scenario validation** - validate test scenario and scan for possible problems
+-   **Claude Code skill** - authoring guidance for writing test scenarios
 
 ## Documentation
 
--   [Usage Examples](USAGE.md) - Practical code examples
--   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete guide
+-   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete usage guide
 -   [Changelog](CHANGELOG.md) - Release notes
 
 ## Thanks
 
-`pytest-httpchain` was inspired by [Tavern](https://github.com/taverntesting/tavern) and [pytest-play](https://github.com/davidemoro/pytest-play).  
+This project was inspired by [Tavern](https://github.com/taverntesting/tavern) and [pytest-play](https://github.com/davidemoro/pytest-play).  
+
 [httpx](https://www.python-httpx.org) does comms.  
 [Pydantic](https://docs.pydantic.dev) keeps structure.  
 [simpleeval](https://github.com/danthedeckie/simpleeval) powers templates.  

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-httpchain"
-version = "0.2.1"
+version = "0.2.4"
 description = "pytest plugin for HTTP testing using JSON files"
 readme = "README.md"
 requires-python = ">=3.13,<4.0"
@@ -10,8 +10,10 @@ dependencies = [
     "pydantic>=2.11.7",
     "pyrate-limiter>=3.0.0",
     "pytest-httpchain-jsonref",
+    "pytest-httpchain-mcp",
     "pytest-httpchain-models",
     "pytest-order>=1.3.0",
+    "typer>=0.16.0",
 ]
 keywords = ["testing", "pytest", "requests"]
 license = "MIT"
@@ -26,9 +28,6 @@ classifiers = [
     "Topic :: Software Development :: Testing",
 ]
 
-[project.optional-dependencies]
-mcp = ["pytest-httpchain-mcp"]
-
 [dependency-groups]
 dev = [
     "flask-httpauth>=4.8.0",
@@ -52,6 +51,7 @@ default-groups = ["dev", "docs"]
 members = ["packages/*"]
 
 [tool.uv.sources]
+pytest-httpchain-core = { workspace = true }
 pytest-httpchain-jsonref = { workspace = true }
 pytest-httpchain-templates = { workspace = true }
 pytest-httpchain-mcp = { workspace = true }
@@ -62,6 +62,9 @@ pytest-httpchain-userfunc = { workspace = true }
 requires = ["uv_build>=0.7.21,<0.8.0"]
 build-backend = "uv_build"
 
+[project.scripts]
+pytest-httpchain = "pytest_httpchain.cli:app"
+
 [project.entry-points.pytest11]
 pytest_httpchain = "pytest_httpchain.plugin"
 
@@ -97,6 +100,7 @@ pytester_example_dir = "tests/integration/examples"
 addopts = ["--log-disable=werkzeug", "--import-mode=importlib"]
 pythonpath = [
     ".",
+    "packages/pytest-httpchain-core/src",
     "packages/pytest-httpchain-jsonref/src",
     "packages/pytest-httpchain-templates/src",
     "packages/pytest-httpchain-mcp/src",
@@ -117,6 +121,7 @@ pythonPlatform = "Linux"
 [tool.coverage.run]
 source = [
     "src",
+    "packages/pytest-httpchain-core/src",
     "packages/pytest-httpchain-jsonref/src",
     "packages/pytest-httpchain-templates/src",
     "packages/pytest-httpchain-mcp/src",

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/src/pytest_httpchain/carrier.py

@@ -47,10 +47,9 @@ from pytest_httpchain_models import (
 )
 from pytest_httpchain_templates import TemplatesError, walk
 from pytest_httpchain_userfunc import UserFunctionError
-from simpleeval import EvalWithCompoundTypes
 
 from .exceptions import RequestError, SaveError, StageExecutionError, VerificationError
-from .utils import call_user_function, process_substitutions
+from .utils import call_user_function, make_marker, process_substitutions
 
 logger = logging.getLogger(__name__)
 
@@ -77,6 +76,7 @@ class Carrier:
     last_response: ClassVar[httpx.Response | None] = None
     global_context: ClassVar[ChainMap[str, Any]] = ChainMap()
     active_context_managers: ClassVar[list[AbstractContextManager]] = []
+    max_parallel_iterations: ClassVar[int] = 10_000
 
     @classmethod
     def execute_stage(cls, stage: Stage, fixture_kwargs: dict[str, Any]) -> None:
@@ -120,14 +120,21 @@ class Carrier:
                                 combos: list[dict[str, Any] | SimpleNamespace] = [vars(item) if isinstance(item, SimpleNamespace) else item for item in combinations]
                                 iteration_substitutions = [{**existing, **combo} for combo in combos for existing in iteration_substitutions]
 
+            if len(iteration_substitutions) > cls.max_parallel_iterations:
+                raise StageExecutionError(
+                    f"Parallel iteration count ({len(iteration_substitutions)}) exceeds maximum ({cls.max_parallel_iterations}). "
+                    f"Set 'max_parallel_iterations' in pytest.ini to increase the limit."
+                )
+
             # execute iterations
             max_concurrency = parallel_config.max_concurrency if parallel_config else 1
             calls_per_sec = parallel_config.calls_per_sec if parallel_config else None
+            max_rate_limit_delay = parallel_config.max_rate_limit_delay if parallel_config else 60
 
             total = len(iteration_substitutions)
             results: list[ParallelIterationResult | None] = [None] * total
             first_error: tuple[int, Exception] | None = None
-            limiter = Limiter(Rate(calls_per_sec, Duration.SECOND), max_delay=Duration.HOUR) if calls_per_sec else None
+            limiter = Limiter(Rate(calls_per_sec, Duration.SECOND), max_delay=Duration.SECOND * max_rate_limit_delay) if calls_per_sec else None
 
             if total == 1:
                 try:
@@ -438,7 +445,7 @@ class Carrier:
             cls.client = None
 
 
-def create_test_class(scenario: Scenario, class_name: str) -> type[Carrier]:
+def create_test_class(scenario: Scenario, class_name: str, max_parallel_iterations: int = 10_000) -> type[Carrier]:
     """Create a dynamic test class from a scenario definition."""
     scenario_context = process_substitutions(scenario.substitutions)
 
@@ -467,6 +474,7 @@ def create_test_class(scenario: Scenario, class_name: str) -> type[Carrier]:
             "last_response": None,
             "global_context": ChainMap(scenario_context),
             "active_context_managers": [],
+            "max_parallel_iterations": max_parallel_iterations,
         },
     )
 
@@ -519,12 +527,9 @@ def create_test_class(scenario: Scenario, class_name: str) -> type[Carrier]:
         stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures])  # type: ignore[assignment]
 
         all_marks = [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)
+                stage_method = make_marker(mark_str)(stage_method)
             except Exception as e:
                 logger.warning(f"Failed to create marker '{mark_str}': {e}")
 

pytest_httpchain-0.2.4/src/pytest_httpchain/cli.py

@@ -0,0 +1,67 @@
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+app = typer.Typer()
+
+SKILL_FILE = Path(__file__).parent / "skill.md"
+
+MCP_SERVER_CONFIG = {
+    "command": "uv",
+    "args": ["run", "pytest-httpchain", "mcp"],
+}
+
+
+@app.command()
+def mcp() -> None:
+    """Run the MCP server."""
+    from pytest_httpchain_mcp.server import mcp as server
+
+    server.run()
+
+
+@app.command()
+def install(
+    skill: bool = typer.Option(..., "--skill/--no-skill", "-s/-S", help="Install Claude Code skill"),
+    mcp_config: bool = typer.Option(..., "--mcp/--no-mcp", "-m/-M", help="Install MCP server config"),
+    global_: bool = typer.Option(False, "--global", "-g", help="Install to ~/.claude (personal scope) instead of project"),
+    project_dir: Annotated[Path, typer.Option(help="Project directory (ignored with --global)")] = Path("."),
+) -> None:
+    """Install MCP server config and/or Claude Code skill."""
+    if global_:
+        if skill:
+            _install_skill(Path.home() / ".claude" / "skills" / "pytest-httpchain")
+        if mcp_config:
+            typer.echo("To add the MCP server globally, run:")
+            typer.echo("  claude mcp add --scope user pytest-httpchain -- uv run pytest-httpchain mcp")
+    else:
+        project_dir = project_dir.resolve()
+        if skill:
+            _install_skill(project_dir / ".claude" / "skills" / "pytest-httpchain")
+        if mcp_config:
+            _install_mcp_config(project_dir / ".mcp.json")
+
+
+def _install_skill(skill_dir: Path) -> None:
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    dest = skill_dir / "SKILL.md"
+    dest.write_text(SKILL_FILE.read_text())
+    typer.echo(f"Installed skill to {dest}")
+
+
+def _install_mcp_config(mcp_file: Path) -> None:
+    if mcp_file.exists():
+        config = json.loads(mcp_file.read_text())
+    else:
+        config = {}
+
+    config.setdefault("mcpServers", {})
+    config["mcpServers"]["pytest-httpchain"] = MCP_SERVER_CONFIG
+    mcp_file.write_text(json.dumps(config, indent=2) + "\n")
+    typer.echo(f"Installed MCP server config to {mcp_file}")
+
+
+if __name__ == "__main__":
+    app()

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/src/pytest_httpchain/constants.py

@@ -19,8 +19,13 @@ class ConfigOptions(StrEnum):
             in $ref paths for security (default: "3").
         MAX_COMPREHENSION_LENGTH: Maximum length for list/dict comprehensions
             in template expressions (default: "50000").
+        MAX_PARALLEL_ITERATIONS: Maximum number of parallel iterations allowed
+            per stage (default: "10000").
+        OUTPUT_DIR: Directory path for test output files (HAR, etc).
     """
 
     SUFFIX = "suffix"
     REF_PARENT_TRAVERSAL_DEPTH = "ref_parent_traversal_depth"
     MAX_COMPREHENSION_LENGTH = "max_comprehension_length"
+    MAX_PARALLEL_ITERATIONS = "max_parallel_iterations"
+    OUTPUT_DIR = "output_dir"

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/src/pytest_httpchain/exceptions.py

@@ -1,7 +1,8 @@
 import httpx
+from pytest_httpchain_core import HttpChainError
 
 
-class StageExecutionError(Exception):
+class StageExecutionError(HttpChainError):
     """Base exception for stage execution errors.
 
     Optionally carries HTTP request/response for debugging failed stages.

pytest_httpchain-0.2.4/src/pytest_httpchain/har_writer.py

@@ -0,0 +1,244 @@
+"""HAR (HTTP Archive) format writer for pytest-httpchain.
+
+This module converts httpx Request/Response objects to HAR 1.2 format
+and writes them to files for external analysis.
+"""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+
+
+def _get_version() -> str:
+    """Get pytest-httpchain version for HAR creator info."""
+    try:
+        from importlib.metadata import version
+
+        return version("pytest-httpchain")
+    except Exception:
+        return "unknown"
+
+
+def _format_cookies(cookies: httpx.Cookies) -> list[dict[str, Any]]:
+    """Convert httpx Cookies to HAR cookie format."""
+    result = []
+    for name, value in cookies.items():
+        result.append({"name": name, "value": value})
+    return result
+
+
+def _parse_cookie_header(cookie_header: str) -> list[dict[str, str]]:
+    """Parse Cookie header string into HAR cookie format."""
+    if not cookie_header:
+        return []
+    result = []
+    for pair in cookie_header.split(";"):
+        pair = pair.strip()
+        if "=" in pair:
+            name, value = pair.split("=", 1)
+            result.append({"name": name.strip(), "value": value.strip()})
+    return result
+
+
+def _format_headers(headers: httpx.Headers) -> list[dict[str, str]]:
+    """Convert httpx Headers to HAR header format."""
+    return [{"name": name, "value": value} for name, value in headers.items()]
+
+
+def _format_query_string(url: httpx.URL) -> list[dict[str, str]]:
+    """Extract query string parameters from URL."""
+    parsed = urlparse(str(url))
+    params = parse_qs(parsed.query, keep_blank_values=True)
+    result = []
+    for name, values in params.items():
+        for value in values:
+            result.append({"name": name, "value": value})
+    return result
+
+
+def _format_post_data(request: httpx.Request) -> dict[str, Any] | None:
+    """Format request body as HAR postData."""
+    if not request.content:
+        return None
+
+    content_type = request.headers.get("content-type", "")
+    mime_type = content_type.split(";")[0].strip() if content_type else "application/octet-stream"
+
+    try:
+        text = request.content.decode("utf-8")
+    except UnicodeDecodeError:
+        import base64
+
+        text = base64.b64encode(request.content).decode("ascii")
+        return {
+            "mimeType": mime_type,
+            "text": text,
+            "encoding": "base64",
+        }
+
+    post_data: dict[str, Any] = {
+        "mimeType": mime_type,
+        "text": text,
+    }
+
+    if "application/x-www-form-urlencoded" in content_type:
+        params = parse_qs(text, keep_blank_values=True)
+        post_data["params"] = [{"name": k, "value": v[0] if len(v) == 1 else v} for k, v in params.items()]
+
+    return post_data
+
+
+def _format_response_content(response: httpx.Response) -> dict[str, Any]:
+    """Format response body as HAR content."""
+    content_type = response.headers.get("content-type", "")
+    mime_type = content_type.split(";")[0].strip() if content_type else "application/octet-stream"
+
+    content: dict[str, Any] = {
+        "size": len(response.content) if response.content else 0,
+        "mimeType": mime_type,
+    }
+
+    if response.content:
+        try:
+            content["text"] = response.content.decode("utf-8")
+        except UnicodeDecodeError:
+            import base64
+
+            content["text"] = base64.b64encode(response.content).decode("ascii")
+            content["encoding"] = "base64"
+
+    return content
+
+
+def _calculate_headers_size(headers: httpx.Headers) -> int:
+    """Calculate approximate size of headers in bytes."""
+    size = 0
+    for name, value in headers.items():
+        size += len(name) + len(value) + 4
+    return size
+
+
+def request_response_to_har_entry(
+    request: httpx.Request,
+    response: httpx.Response,
+    started_datetime: datetime | None = None,
+    elapsed_ms: float = 0,
+) -> dict[str, Any]:
+    """Convert an httpx Request/Response pair to a HAR entry.
+
+    Args:
+        request: The httpx Request object.
+        response: The httpx Response object.
+        started_datetime: When the request started (defaults to now).
+        elapsed_ms: Total elapsed time in milliseconds.
+
+    Returns:
+        A dictionary representing a HAR entry.
+    """
+    if started_datetime is None:
+        started_datetime = datetime.now(UTC)
+
+    entry: dict[str, Any] = {
+        "startedDateTime": started_datetime.isoformat(),
+        "time": elapsed_ms,
+        "request": {
+            "method": request.method,
+            "url": str(request.url),
+            "httpVersion": response.http_version or "HTTP/1.1",
+            "cookies": _parse_cookie_header(request.headers.get("cookie", "")),
+            "headers": _format_headers(request.headers),
+            "queryString": _format_query_string(request.url),
+            "headersSize": _calculate_headers_size(request.headers),
+            "bodySize": len(request.content) if request.content else 0,
+        },
+        "response": {
+            "status": response.status_code,
+            "statusText": response.reason_phrase or "",
+            "httpVersion": response.http_version or "HTTP/1.1",
+            "cookies": _format_cookies(response.cookies),
+            "headers": _format_headers(response.headers),
+            "content": _format_response_content(response),
+            "redirectURL": response.headers.get("location", ""),
+            "headersSize": _calculate_headers_size(response.headers),
+            "bodySize": len(response.content) if response.content else 0,
+        },
+        "cache": {},
+        "timings": {
+            "send": -1,
+            "wait": elapsed_ms if elapsed_ms > 0 else -1,
+            "receive": -1,
+        },
+    }
+
+    post_data = _format_post_data(request)
+    if post_data:
+        entry["request"]["postData"] = post_data
+
+    return entry
+
+
+def create_har_log(entries: list[dict[str, Any]], comment: str | None = None) -> dict[str, Any]:
+    """Create a complete HAR log structure.
+
+    Args:
+        entries: List of HAR entry dictionaries.
+        comment: Optional comment to include in the log.
+
+    Returns:
+        A complete HAR log dictionary.
+    """
+    har: dict[str, Any] = {
+        "log": {
+            "version": "1.2",
+            "creator": {
+                "name": "pytest-httpchain",
+                "version": _get_version(),
+            },
+            "entries": entries,
+        }
+    }
+
+    if comment:
+        har["log"]["comment"] = comment
+
+    return har
+
+
+def write_har_file(
+    output_dir: Path,
+    test_name: str,
+    request: httpx.Request,
+    response: httpx.Response,
+    started_datetime: datetime | None = None,
+    elapsed_ms: float = 0,
+) -> Path:
+    """Write a HAR file for a single test.
+
+    Args:
+        output_dir: Directory to write the HAR file to.
+        test_name: Name of the test (used for filename).
+        request: The httpx Request object.
+        response: The httpx Response object.
+        started_datetime: When the request started.
+        elapsed_ms: Total elapsed time in milliseconds.
+
+    Returns:
+        Path to the written HAR file.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    safe_name = test_name.replace("/", "_").replace("\\", "_").replace(":", "_")
+    filename = f"{safe_name}.har"
+    filepath = output_dir / filename
+
+    entry = request_response_to_har_entry(request, response, started_datetime, elapsed_ms)
+    har = create_har_log([entry], comment=f"Test: {test_name}")
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        json.dump(har, f, indent=2, ensure_ascii=False)
+
+    return filepath

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/src/pytest_httpchain/plugin.py

@@ -12,12 +12,13 @@ from _pytest import config, nodes, python, reports, runner
 from _pytest.config import argparsing
 from pydantic import ValidationError
 from pytest_httpchain_models.entities import Scenario
-from simpleeval import EvalWithCompoundTypes
 
 from pytest_httpchain.constants import ConfigOptions
 
 from .carrier import Carrier, create_test_class
+from .har_writer import write_har_file
 from .report_formatter import format_request, format_response
+from .utils import make_marker
 
 logger = logging.getLogger(__name__)
 
@@ -59,7 +60,8 @@ class JsonModule(python.Module):
             raise nodes.Collector.CollectError(full_error_msg) from None
 
         # generate python test class
-        CarrierClass = create_test_class(scenario, self.name)
+        max_parallel_iterations = int(self.config.getini(ConfigOptions.MAX_PARALLEL_ITERATIONS))
+        CarrierClass = create_test_class(scenario, self.name, max_parallel_iterations=max_parallel_iterations)
         dummy_module = types.ModuleType("generated")
         setattr(dummy_module, self.name, CarrierClass)
         self._getobj = lambda: dummy_module  # ty: ignore[invalid-assignment]
@@ -71,14 +73,11 @@ class JsonModule(python.Module):
         )
 
         # apply class-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)
+                json_class.add_marker(make_marker(mark_str))
             except Exception as e:
-                logger.warning(f"Failed to create marker '{mark_str}': {e}")
+                raise nodes.Collector.CollectError(f"Invalid marker '{mark_str}' in {self.path}: {e}") from None
 
         yield json_class
 
@@ -102,6 +101,18 @@ def pytest_addoption(parser: argparsing.Parser) -> None:
         type="string",
         default="50000",
     )
+    parser.addini(
+        name=ConfigOptions.MAX_PARALLEL_ITERATIONS,
+        help="Maximum number of parallel iterations allowed per stage.",
+        type="string",
+        default="10000",
+    )
+    parser.addoption(
+        "--output-dir",
+        dest="output_dir",
+        default=None,
+        help="Directory to write test output files (HAR format for HTTP communications).",
+    )
 
 
 def pytest_configure(config: config.Config) -> None:
@@ -118,7 +129,13 @@ def pytest_configure(config: config.Config) -> None:
         raise ValueError("Maximum comprehension length must be a positive integer")
     if max_comprehension_length > 1_000_000:
         raise ValueError("Maximum comprehension length must not exceed 1,000,000")
-    simpleeval.MAX_COMPREHENSION_LENGTH = max_comprehension_length  # type: ignore[misc]
+    simpleeval.MAX_COMPREHENSION_LENGTH = max_comprehension_length  # ty: ignore[invalid-assignment]
+
+    max_parallel_iterations = int(config.getini(ConfigOptions.MAX_PARALLEL_ITERATIONS))
+    if max_parallel_iterations < 1:
+        raise ValueError("Maximum parallel iterations must be a positive integer")
+    if max_parallel_iterations > 1_000_000:
+        raise ValueError("Maximum parallel iterations must not exceed 1,000,000")
 
 
 def pytest_collect_file(file_path: Path, parent: nodes.Collector) -> nodes.Collector | None:
@@ -150,3 +167,16 @@ def pytest_runtest_makereport(item: nodes.Item, call: runner.CallInfo[Any]) -> A
                     report.sections.append(("HTTP Response", format_response(carrier.last_response)))
                 except Exception as e:
                     report.sections.append(("HTTP Response", f"<Error formatting response: {e}>"))
+
+            output_dir = item.config.getoption("output_dir")
+            if output_dir and carrier.last_request is not None and carrier.last_response is not None:
+                try:
+                    har_path = write_har_file(
+                        output_dir=Path(output_dir),
+                        test_name=item.nodeid,
+                        request=carrier.last_request,
+                        response=carrier.last_response,
+                    )
+                    report.sections.append(("HAR File", str(har_path)))
+                except Exception as e:
+                    logger.warning(f"Failed to write HAR file for {item.nodeid}: {e}")

pytest_httpchain-0.2.4/src/pytest_httpchain/skill.md

@@ -0,0 +1,252 @@
+---
+name: pytest-httpchain
+description: Write and edit pytest-httpchain HTTP API test scenarios in JSON format
+---
+
+# pytest-httpchain test authoring
+
+pytest-httpchain is a pytest plugin for declarative HTTP API integration testing. Test scenarios are JSON files discovered by pattern `test_<name>.http.json`.
+
+## Scenario structure
+
+```json
+{
+  "description": "optional scenario description",
+  "marks": ["optional_pytest_markers"],
+  "substitutions": [],
+  "stages": []
+}
+```
+
+## Stage structure
+
+```json
+{
+  "name": "stage name",
+  "description": "optional",
+  "fixtures": ["fixture_name"],
+  "marks": ["skip", "xfail(reason='not ready')"],
+  "always_run": false,
+  "substitutions": [],
+  "parametrize": [],
+  "parallel": null,
+  "request": { ... },
+  "response": [ ... ]
+}
+```
+
+Stages run sequentially and share a global context. Values saved in one stage are available in subsequent stages.
+
+Stages can also be written as a dict (keys become stage names):
+
+```json
+{
+  "stages": {
+    "create user": { "request": { ... }, "response": [ ... ] },
+    "get user":    { "request": { ... }, "response": [ ... ] }
+  }
+}
+```
+
+## Request
+
+```json
+{
+  "url": "{{ server }}/api/users",
+  "method": "POST",
+  "headers": { "Authorization": "Bearer {{ token }}" },
+  "params": { "page": 1 },
+  "body": { "json": { "name": "Alice" } },
+  "timeout": 30.0,
+  "allow_redirects": true
+}
+```
+
+**Body types** (use exactly one key):
+- `{"json": { ... }}` - JSON body
+- `{"form": { ... }}` - URL-encoded form
+- `{"text": "..."}` - raw text
+- `{"xml": "<root/>"}` - XML
+- `{"base64": "..."}` - base64-encoded binary
+- `{"binary": "/path/to/file"}` - file upload
+- `{"files": {"field": "/path/to/file"}}` - multipart file upload
+- `{"graphql": {"query": "...", "variables": {}}}` - GraphQL
+
+## Response steps
+
+Response is a list of verify and save steps, executed in order:
+
+```json
+"response": [
+  {
+    "verify": {
+      "status": 200,
+      "headers": { "content-type": "application/json" },
+      "expressions": [
+        "{{ user_count > 0 }}",
+        "{{ 'error' not in body }}"
+      ],
+      "body": {
+        "schema": { "type": "object", "required": ["id"] },
+        "contains": ["expected text"],
+        "not_contains": ["error"],
+        "matches": ["\\d{4}-\\d{2}-\\d{2}"],
+        "not_matches": ["forbidden"]
+      }
+    }
+  },
+  {
+    "save": {
+      "jmespath": {
+        "user_id": "data.id",
+        "user_name": "data.name",
+        "total": "length(items)"
+      }
+    }
+  }
+]
+```
+
+**Save types:**
+- `{"jmespath": {...}}` - extract values from JSON response via JMESPath
+- `{"substitutions": [...]}` - compute values using template expressions
+- `{"user_functions": [...]}` - call Python functions to process response
+
+## Template expressions
+
+Use `{{ expr }}` syntax. Expressions are evaluated with Python semantics.
+
+**Available context:** all saved variables, fixture values, and substitution results.
+
+**Built-in functions:** `len`, `min`, `max`, `sum`, `abs`, `round`, `sorted`, `range`, `zip`, `enumerate`, `bool`, `int`, `float`, `str`, `dict`, `list`, `tuple`, `set`, `uuid4()`, `env(var, default)`, `get(var, default)`, `exists(var)`, `rand()`, `randint(a, b)`
+
+**JSON literals:** `true`, `false`, `null` map to Python `True`, `False`, `None`.
+
+## Substitutions
+
+Define variables before stages run:
+
+```json
+"substitutions": [
+  { "vars": { "base_url": "https://api.example.com", "count": "{{ 2 + 3 }}" } },
+  { "functions": { "generate_token": "mymodule:create_jwt" } }
+]
+```
+
+Substitutions can appear at scenario level (global) or stage level (local).
+
+## References ($include / $ref)
+
+Split scenarios across files using `$include` (preferred) or `$ref`:
+
+```json
+{
+  "request": {
+    "$include": "common.json#/requests/get_user"
+  }
+}
+```
+
+Sibling properties are deep-merged with the referenced content:
+
+```json
+{
+  "$include": "base_request.json",
+  "headers": { "X-Custom": "override" }
+}
+```
+
+## Parametrize
+
+Run a stage with different inputs:
+
+```json
+"parametrize": [
+  {
+    "individual": { "user_id": [1, 2, 3] },
+    "ids": ["user-one", "user-two", "user-three"]
+  }
+]
+```
+
+Or use combinations:
+
+```json
+"parametrize": [
+  {
+    "combinations": [
+      { "method": "GET", "expected": 200 },
+      { "method": "DELETE", "expected": 403 }
+    ]
+  }
+]
+```
+
+## Parallel execution
+
+Execute requests concurrently for load testing:
+
+```json
+"parallel": {
+  "repeat": 100,
+  "max_concurrency": 10,
+  "calls_per_sec": 50
+}
+```
+
+Or iterate over parameter sets in parallel:
+
+```json
+"parallel": {
+  "foreach": [{ "individual": { "id": [1, 2, 3, 4, 5] } }],
+  "max_concurrency": 5
+}
+```
+
+## Complete example: multi-stage API test
+
+```json
+{
+  "substitutions": [
+    { "vars": { "base": "{{ env('API_URL', 'http://localhost:8000') }}" } }
+  ],
+  "stages": [
+    {
+      "name": "create user",
+      "request": {
+        "url": "{{ base }}/users",
+        "method": "POST",
+        "body": { "json": { "name": "Alice", "email": "alice@example.com" } }
+      },
+      "response": [
+        { "verify": { "status": 201 } },
+        { "save": { "jmespath": { "user_id": "id" } } }
+      ]
+    },
+    {
+      "name": "get user",
+      "request": {
+        "url": "{{ base }}/users/{{ user_id }}"
+      },
+      "response": [
+        {
+          "verify": {
+            "status": 200,
+            "expressions": ["{{ body.name == 'Alice' }}"]
+          }
+        }
+      ]
+    },
+    {
+      "name": "delete user",
+      "request": {
+        "url": "{{ base }}/users/{{ user_id }}",
+        "method": "DELETE"
+      },
+      "response": [
+        { "verify": { "status": 204 } }
+      ]
+    }
+  ]
+}
+```

{pytest_httpchain-0.2.1 → pytest_httpchain-0.2.4}/src/pytest_httpchain/utils.py

@@ -1,7 +1,9 @@
+import ast
 import logging
 from collections.abc import Mapping, Sequence
 from typing import Any
 
+import pytest
 from pytest_httpchain_models import FunctionsSubstitution, Substitution, UserFunctionCall, UserFunctionKwargs, UserFunctionName, VarsSubstitution
 from pytest_httpchain_templates import walk
 from pytest_httpchain_userfunc import call_function, wrap_function
@@ -11,6 +13,22 @@ from .exceptions import StageExecutionError
 logger = logging.getLogger(__name__)
 
 
+def make_marker(mark_str: str) -> pytest.MarkDecorator:
+    """Create a pytest marker from a string like 'skip(reason="foo")' or 'geofencing'."""
+    tree = ast.parse(mark_str, mode="eval")
+    node = tree.body
+
+    if isinstance(node, ast.Name):
+        return getattr(pytest.mark, node.id)
+
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+        args = [ast.literal_eval(a) for a in node.args]
+        kwargs = {kw.arg: ast.literal_eval(kw.value) for kw in node.keywords if kw.arg is not None}
+        return getattr(pytest.mark, node.func.id)(*args, **kwargs)
+
+    raise ValueError(f"unsupported marker expression: {mark_str}")
+
+
 def process_substitutions(
     substitutions: Sequence[Substitution],
     context: Mapping[str, Any] = {},