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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-httpchain
-Version: 0.2.4
+Version: 0.3.0
 Summary: pytest plugin for HTTP testing using JSON files
 Keywords: testing,pytest,requests
 Author: Alexander Eresov
@@ -18,8 +18,8 @@ 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-httpchain-templates
 Requires-Dist: pytest-order>=1.3.0
 Requires-Dist: typer>=0.16.0
 Requires-Python: >=3.13, <4.0
@@ -196,37 +196,39 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 -   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
+## AI agent support
 
-`pytest-httpchain` includes an MCP (Model Context Protocol) server to aid AI code assistants.
+`pytest-httpchain` ships tooling to help AI coding agents (and humans) author and check test scenarios.
 
-### Setup
+### Claude Code skill
 
-Install the MCP server config and Claude Code skill into your project:
+Install the authoring skill into your project (or `--global` for personal scope):
 
 ```bash
-uvx pytest-httpchain install --skill --mcp
+uvx pytest-httpchain install
 ```
 
-Or configure manually in `.mcp.json`:
+This writes `.claude/skills/pytest-httpchain/SKILL.md` with guidance for writing scenarios.
 
-```json
-{
-    "mcpServers": {
-        "pytest-httpchain": {
-            "command": "uvx",
-            "args": ["pytest-httpchain", "mcp"]
-        }
-    }
-}
+### Scenario validation
+
+Validate scenario files for structure and common problems — undefined variables, duplicate stage names, fixture/variable conflicts, stages with no assertions:
+
+```bash
+uvx pytest-httpchain validate tests/test_login.http.json
 ```
 
-### Features
+It exits non-zero when any file is invalid, so it doubles as a CI gate. The same checks also run automatically at **pytest collection time** — semantic errors fail collection and warnings are reported — so `pytest --collect-only` validates every scenario in your suite.
+
+### Editor schema
 
-The MCP server provides:
+A JSON Schema is published for as-you-type validation and autocomplete. Reference it from your test files:
 
--   **Scenario validation** - validate test scenario and scan for possible problems
--   **Claude Code skill** - authoring guidance for writing test scenarios
+```json
+{
+    "$schema": "https://aeresov.github.io/pytest-httpchain/schema/scenario.schema.json"
+}
+```
 
 ## Documentation
 

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

@@ -169,37 +169,39 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 -   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
+## AI agent support
 
-`pytest-httpchain` includes an MCP (Model Context Protocol) server to aid AI code assistants.
+`pytest-httpchain` ships tooling to help AI coding agents (and humans) author and check test scenarios.
 
-### Setup
+### Claude Code skill
 
-Install the MCP server config and Claude Code skill into your project:
+Install the authoring skill into your project (or `--global` for personal scope):
 
 ```bash
-uvx pytest-httpchain install --skill --mcp
+uvx pytest-httpchain install
 ```
 
-Or configure manually in `.mcp.json`:
+This writes `.claude/skills/pytest-httpchain/SKILL.md` with guidance for writing scenarios.
 
-```json
-{
-    "mcpServers": {
-        "pytest-httpchain": {
-            "command": "uvx",
-            "args": ["pytest-httpchain", "mcp"]
-        }
-    }
-}
+### Scenario validation
+
+Validate scenario files for structure and common problems — undefined variables, duplicate stage names, fixture/variable conflicts, stages with no assertions:
+
+```bash
+uvx pytest-httpchain validate tests/test_login.http.json
 ```
 
-### Features
+It exits non-zero when any file is invalid, so it doubles as a CI gate. The same checks also run automatically at **pytest collection time** — semantic errors fail collection and warnings are reported — so `pytest --collect-only` validates every scenario in your suite.
+
+### Editor schema
 
-The MCP server provides:
+A JSON Schema is published for as-you-type validation and autocomplete. Reference it from your test files:
 
--   **Scenario validation** - validate test scenario and scan for possible problems
--   **Claude Code skill** - authoring guidance for writing test scenarios
+```json
+{
+    "$schema": "https://aeresov.github.io/pytest-httpchain/schema/scenario.schema.json"
+}
+```
 
 ## Documentation
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-httpchain"
-version = "0.2.4"
+version = "0.3.0"
 description = "pytest plugin for HTTP testing using JSON files"
 readme = "README.md"
 requires-python = ">=3.13,<4.0"
@@ -10,8 +10,8 @@ dependencies = [
     "pydantic>=2.11.7",
     "pyrate-limiter>=3.0.0",
     "pytest-httpchain-jsonref",
-    "pytest-httpchain-mcp",
     "pytest-httpchain-models",
+    "pytest-httpchain-templates",
     "pytest-order>=1.3.0",
     "typer>=0.16.0",
 ]
@@ -54,7 +54,6 @@ members = ["packages/*"]
 pytest-httpchain-core = { workspace = true }
 pytest-httpchain-jsonref = { workspace = true }
 pytest-httpchain-templates = { workspace = true }
-pytest-httpchain-mcp = { workspace = true }
 pytest-httpchain-models = { workspace = true }
 pytest-httpchain-userfunc = { workspace = true }
 
@@ -103,7 +102,6 @@ pythonpath = [
     "packages/pytest-httpchain-core/src",
     "packages/pytest-httpchain-jsonref/src",
     "packages/pytest-httpchain-templates/src",
-    "packages/pytest-httpchain-mcp/src",
     "packages/pytest-httpchain-models/src",
     "packages/pytest-httpchain-userfunc/src",
 ]
@@ -124,7 +122,6 @@ source = [
     "packages/pytest-httpchain-core/src",
     "packages/pytest-httpchain-jsonref/src",
     "packages/pytest-httpchain-templates/src",
-    "packages/pytest-httpchain-mcp/src",
     "packages/pytest-httpchain-models/src",
     "packages/pytest-httpchain-userfunc/src",
 ]

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

@@ -180,7 +180,7 @@ class Carrier:
                         cls.last_request = exc.request
                     if exc.response is not None:
                         cls.last_response = exc.response
-                raise StageExecutionError(f"Parallel execution failed at iteration {idx}: {exc}")
+                raise StageExecutionError(f"Parallel execution failed at iteration {idx}: {exc}") from exc
 
         except (
             TemplatesError,
@@ -199,7 +199,7 @@ class Carrier:
             "method": request_model.method,
             "url": str(request_model.url),
             "headers": request_model.headers,
-            "params": request_model.params,
+            "params": request_model.params or None,
             "timeout": request_model.timeout,
             "follow_redirects": request_model.allow_redirects,
         }
@@ -209,7 +209,7 @@ class Carrier:
                 auth_result = call_user_function(request_model.auth)
                 request_kwargs["auth"] = auth_result
             except UserFunctionError as e:
-                raise RequestError(f"Failed to configure authentication: {str(e)}") from None
+                raise RequestError(f"Failed to configure authentication: {e}") from None
 
         match request_model.body:
             case None:
@@ -233,19 +233,16 @@ class Carrier:
 
             case BinaryBody(binary=file_path):
                 try:
-                    with open(file_path, "rb") as f:
-                        binary_data = f.read()
-                    request_kwargs["content"] = binary_data
+                    request_kwargs["content"] = Path(file_path).read_bytes()
                 except FileNotFoundError:
                     raise RequestError(f"Binary file not found: {file_path}") from None
 
             case FilesBody(files=file_paths):
                 files_list = []
                 for field_name, file_path in file_paths.items():
+                    path = Path(file_path)
                     try:
-                        with open(file_path, "rb") as f:
-                            file_content = f.read()
-                        files_list.append((field_name, (Path(file_path).name, file_content)))
+                        files_list.append((field_name, (path.name, path.read_bytes())))
                     except FileNotFoundError:
                         raise RequestError(f"File not found for upload: {file_path}") from None
                 request_kwargs["files"] = files_list
@@ -257,13 +254,13 @@ class Carrier:
         try:
             return cls.client.request(**request_kwargs)
         except httpx.TimeoutException as e:
-            raise RequestError(f"HTTP request timed out: {str(e)}") from None
+            raise RequestError(f"HTTP request timed out: {e}") from None
         except httpx.ConnectError as e:
-            raise RequestError(f"HTTP connection error: {str(e)}") from None
+            raise RequestError(f"HTTP connection error: {e}") from None
         except httpx.HTTPError as e:
-            raise RequestError(f"HTTP request failed: {str(e)}") from None
+            raise RequestError(f"HTTP request failed: {e}") from None
         except Exception as e:
-            raise RequestError(f"Unexpected error: {str(e)}") from None
+            raise RequestError(f"Unexpected error: {e}") from None
 
     @staticmethod
     def _process_save_step(save_model: Save, response: httpx.Response, context: ChainMap[str, Any]) -> dict[str, Any]:
@@ -274,21 +271,21 @@ class Carrier:
                 try:
                     response_json = response.json()
                 except (json.JSONDecodeError, UnicodeDecodeError) as e:
-                    raise SaveError(f"Cannot extract variables, response is not valid JSON: {str(e)}") from None
+                    raise SaveError(f"Cannot extract variables, response is not valid JSON: {e}") from None
 
                 for var_name, jmespath_expr in save_model.jmespath.items():
                     try:
                         saved_value = jmespath.search(jmespath_expr, response_json)
                         step_saved[var_name] = saved_value
                     except jmespath.exceptions.JMESPathError as e:
-                        raise SaveError(f"Error saving variable {var_name}: {str(e)}") from None
+                        raise SaveError(f"Error saving variable {var_name}: {e}") from None
 
             case SubstitutionsSave():
                 try:
                     substitution_result = process_substitutions(save_model.substitutions, context)
                     step_saved.update(substitution_result)
                 except TemplatesError as e:
-                    raise SaveError(f"Error processing substitutions: {str(e)}") from None
+                    raise SaveError(f"Error processing substitutions: {e}") from None
 
             case UserFunctionsSave():
                 for func_item in save_model.user_functions:
@@ -298,12 +295,11 @@ class Carrier:
                         if not isinstance(func_result, dict):
                             raise SaveError(f"Save function must return dict, got {type(func_result).__name__}")
 
-                        result_dict = cast(dict[str, Any], func_result)
-                        step_saved.update(result_dict)
+                        step_saved.update(func_result)
                     except SaveError:
                         raise
                     except UserFunctionError as e:
-                        raise SaveError(f"Error calling user function '{func_item}': {str(e)}") from None
+                        raise SaveError(f"Error calling user function '{func_item}': {e}") from None
 
         return step_saved
 
@@ -333,7 +329,7 @@ class Carrier:
             except VerificationError:
                 raise
             except UserFunctionError as e:
-                raise VerificationError(f"Error calling user function '{func_item}': {str(e)}") from None
+                raise VerificationError(f"Error calling user function '{func_item}': {e}") from None
 
         if verify_model.body.schema:
             schema = verify_model.body.schema
@@ -343,21 +339,21 @@ class Carrier:
                     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}': {str(e)}") from None
+                    raise VerificationError(f"Error reading body schema file '{schema_path}': {e}") from None
                 except jsonschema.SchemaError as e:
                     raise VerificationError(f"Invalid JSON Schema in file '{schema_path}': {e}") from None
 
             try:
                 response_json = response.json()
             except (json.JSONDecodeError, UnicodeDecodeError) as e:
-                raise VerificationError(f"Cannot validate schema, response is not valid JSON: {str(e)}") from None
+                raise VerificationError(f"Cannot validate schema, response is not valid JSON: {e}") from None
 
             try:
                 jsonschema.validate(instance=response_json, schema=schema)
             except jsonschema.ValidationError as e:
-                raise VerificationError(f"Body schema validation failed: {str(e)}") from None
+                raise VerificationError(f"Body schema validation failed: {e}") from None
             except jsonschema.SchemaError as e:
-                raise VerificationError(f"Invalid body validation schema: {str(e)}") from None
+                raise VerificationError(f"Invalid body validation schema: {e}") from None
 
         for substring in verify_model.body.contains:
             if substring not in response.text:
@@ -438,7 +434,7 @@ class Carrier:
             try:
                 ctx.__exit__(None, None, None)
             except Exception as e:
-                logger.error(f"Error while cleaning up context manager fixture: {str(e)}")
+                logger.error(f"Error while cleaning up context manager fixture: {e}")
 
         if cls.client is not None:
             cls.client.close()

pytest_httpchain-0.3.0/src/pytest_httpchain/cli.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+app = typer.Typer()
+
+SKILL_FILE = Path(__file__).parent / "skill.md"
+
+
+@app.command()
+def validate(
+    paths: Annotated[list[Path], typer.Argument(help="Scenario JSON file(s) to validate.")],
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Validate pytest-httpchain scenario file(s).
+
+    Prints errors and warnings per file and exits non-zero if any file is invalid.
+    """
+    from pytest_httpchain.validation import validate_scenario
+
+    all_valid = True
+    for path in paths:
+        result = validate_scenario(path, ref_parent_traversal_depth=ref_parent_traversal_depth)
+        if result.valid:
+            status = "OK with warnings" if result.warnings else "OK"
+        else:
+            status = "INVALID"
+            all_valid = False
+        typer.echo(f"{path}: {status}")
+        for error in result.errors:
+            typer.echo(f"  error: {error}")
+        for warning in result.warnings:
+            typer.echo(f"  warning: {warning}")
+
+    raise typer.Exit(0 if all_valid else 1)
+
+
+@app.command()
+def install(
+    global_: Annotated[bool, typer.Option("--global", "-g", help="Install to ~/.claude (personal scope) instead of project")] = False,
+    project_dir: Annotated[Path, typer.Option(help="Project directory (ignored with --global)")] = Path("."),
+) -> None:
+    """Install the Claude Code skill for authoring test scenarios."""
+    if global_:
+        _install_skill(Path.home() / ".claude" / "skills" / "pytest-httpchain")
+    else:
+        _install_skill(project_dir.resolve() / ".claude" / "skills" / "pytest-httpchain")
+
+
+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}")
+
+
+if __name__ == "__main__":
+    app()

{pytest_httpchain-0.2.4 → pytest_httpchain-0.3.0}/src/pytest_httpchain/har_writer.py

@@ -238,7 +238,6 @@ def write_har_file(
     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)
+    filepath.write_text(json.dumps(har, indent=2, ensure_ascii=False), encoding="utf-8")
 
     return filepath

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

@@ -1,6 +1,7 @@
 import logging
 import re
 import types
+import warnings
 from collections.abc import Iterable
 from pathlib import Path
 from typing import Any
@@ -19,10 +20,15 @@ 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
+from .validation import check_scenario
 
 logger = logging.getLogger(__name__)
 
 
+class ScenarioValidationWarning(pytest.PytestWarning):
+    """A collected scenario has a non-fatal validation issue (e.g. an undefined variable)."""
+
+
 class JsonModule(python.Module):
     """JSON test module that collects and executes HTTP chain tests.
 
@@ -42,9 +48,9 @@ class JsonModule(python.Module):
                 root_path=root_path,
             )
         except pytest_httpchain_jsonref.ReferenceResolverError as e:
-            raise nodes.Collector.CollectError(f"Cannot load JSON file {self.path}: {str(e)}") from None
+            raise nodes.Collector.CollectError(f"Cannot load JSON file {self.path}: {e}") from None
         except Exception as e:
-            raise nodes.Collector.CollectError(f"Failed to parse JSON file {self.path}: {str(e)}") from None
+            raise nodes.Collector.CollectError(f"Failed to parse JSON file {self.path}: {e}") from None
 
         # validate general scenario structure
         try:
@@ -59,6 +65,15 @@ class JsonModule(python.Module):
             full_error_msg = f"Cannot parse test scenario in {self.path}:\n" + "\n".join(error_details)
             raise nodes.Collector.CollectError(full_error_msg) from None
 
+        # semantic validation: cross-cutting checks the schema cannot express
+        # (duplicate stage names, fixture/variable conflicts, undefined variables, ...)
+        semantic_errors, semantic_warnings, _ = check_scenario(scenario, test_data)
+        for warning in semantic_warnings:
+            warnings.warn(ScenarioValidationWarning(f"{self.path}: {warning}"), stacklevel=2)
+        if semantic_errors:
+            detail = "\n".join(f"  - {e}" for e in semantic_errors)
+            raise nodes.Collector.CollectError(f"Invalid test scenario in {self.path}:\n{detail}")
+
         # generate python test class
         max_parallel_iterations = int(self.config.getini(ConfigOptions.MAX_PARALLEL_ITERATIONS))
         CarrierClass = create_test_class(scenario, self.name, max_parallel_iterations=max_parallel_iterations)

{pytest_httpchain-0.2.4 → pytest_httpchain-0.3.0}/src/pytest_httpchain/skill.md

@@ -82,10 +82,6 @@ Response is a list of verify and save steps, executed in order:
     "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"],
@@ -103,10 +99,22 @@ Response is a list of verify and save steps, executed in order:
         "total": "length(items)"
       }
     }
+  },
+  {
+    "verify": {
+      "expressions": [
+        "{{ total > 0 }}",
+        "{{ user_name != '' }}"
+      ]
+    }
   }
 ]
 ```
 
+**Important:** `verify.expressions` are `{{ }}` templates evaluated against the **context** (saved variables, fixtures, substitutions). The HTTP response is **not** ambient in templates — there is no `response`/`status_code`/`body`/`json` variable. To assert on response data, either:
+- use `verify.status`, `verify.headers`, `verify.body` (these check the response directly), or
+- `save` the value first (e.g. via `jmespath`) and reference the saved variable in a later `expressions` step (as shown above).
+
 **Save types:**
 - `{"jmespath": {...}}` - extract values from JSON response via JMESPath
 - `{"substitutions": [...]}` - compute values using template expressions
@@ -229,12 +237,9 @@ Or iterate over parameter sets in parallel:
         "url": "{{ base }}/users/{{ user_id }}"
       },
       "response": [
-        {
-          "verify": {
-            "status": 200,
-            "expressions": ["{{ body.name == 'Alice' }}"]
-          }
-        }
+        { "verify": { "status": 200 } },
+        { "save": { "jmespath": { "name": "name" } } },
+        { "verify": { "expressions": ["{{ name == 'Alice' }}"] } }
       ]
     },
     {

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

@@ -31,11 +31,11 @@ def make_marker(mark_str: str) -> pytest.MarkDecorator:
 
 def process_substitutions(
     substitutions: Sequence[Substitution],
-    context: Mapping[str, Any] = {},
+    context: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
-    result = {}
+    result: dict[str, Any] = {}
     for step in substitutions:
-        current_context = {**context, **result}
+        current_context = {**(context or {}), **result}
         match step:
             case FunctionsSubstitution():
                 for alias, func_def in step.functions.items():

pytest_httpchain-0.3.0/src/pytest_httpchain/validation.py

@@ -0,0 +1,272 @@
+"""Static validation for pytest-httpchain scenario files.
+
+This is the single source of truth for scenario validation, consumed by the
+`pytest-httpchain validate` CLI command (and available for collection-time and
+editor integrations). It performs structural validation via the Pydantic
+``Scenario`` model plus cross-cutting semantic checks that a JSON Schema cannot
+express (duplicate stage names, undefined-variable/data-flow, fixture conflicts).
+"""
+
+import ast
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import pytest_httpchain_jsonref.loader
+from pydantic import BaseModel, ValidationError
+from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+from pytest_httpchain_models.entities import Scenario
+from pytest_httpchain_templates.expressions import TEMPLATE_PATTERN
+from pytest_httpchain_templates.substitution import JSON_LITERALS, SAFE_FUNCTIONS
+
+# Names provided by the template engine that don't need user definition.
+TEMPLATE_BUILTINS = (
+    set(SAFE_FUNCTIONS)
+    | set(JSON_LITERALS)
+    | {"exists", "get"}  # context helpers added at eval time
+    | {"rand", "randint", "int", "float", "str"}  # simpleeval defaults
+)
+
+
+def _extract_names_from_expr(expr: str) -> set[str]:
+    """Extract identifier names from a Python expression using AST parsing."""
+    try:
+        tree = ast.parse(expr.strip(), mode="eval")
+        return {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}
+    except SyntaxError:
+        return set(re.findall(r"[a-zA-Z_][a-zA-Z0-9_]*", expr))
+
+
+def extract_template_variables(obj: Any, variables: set[str] | None = None) -> set[str]:
+    """Recursively extract variable names from {{ expr }} template expressions."""
+    if variables is None:
+        variables = set()
+
+    if isinstance(obj, str):
+        for match in re.finditer(TEMPLATE_PATTERN, obj):
+            names = _extract_names_from_expr(match.group("expr"))
+            variables.update(names - TEMPLATE_BUILTINS)
+    elif isinstance(obj, dict):
+        for value in obj.values():
+            extract_template_variables(value, variables)
+    elif isinstance(obj, list):
+        for item in obj:
+            extract_template_variables(item, variables)
+
+    return variables
+
+
+def extract_saved_variables(scenario: Scenario) -> set[str]:
+    """Extract variable names saved in response steps."""
+    saved_vars: set[str] = set()
+
+    for stage in scenario.stages:
+        for response_step in stage.response:
+            if not hasattr(response_step, "save"):
+                continue
+            save = response_step.save
+            if hasattr(save, "jmespath") and isinstance(save.jmespath, dict):
+                saved_vars.update(save.jmespath.keys())
+            if hasattr(save, "substitutions"):
+                for sub in save.substitutions:
+                    if hasattr(sub, "vars") and isinstance(sub.vars, dict):
+                        saved_vars.update(sub.vars.keys())
+                    if hasattr(sub, "functions") and isinstance(sub.functions, dict):
+                        saved_vars.update(sub.functions.keys())
+
+    return saved_vars
+
+
+def _parameter_names(params: Any) -> set[str]:
+    """Names injected by a list of parametrize/foreach Parameter entries.
+
+    Covers both ``individual`` (one name -> list of values) and ``combinations``
+    (list of dicts whose keys are the names). Template-string forms (deferred to
+    runtime) contribute no statically-known names.
+    """
+    names: set[str] = set()
+    for param in params or []:
+        individual = getattr(param, "individual", None)
+        if isinstance(individual, dict):
+            names.update(k for k in individual if isinstance(k, str))
+        combinations = getattr(param, "combinations", None)
+        if isinstance(combinations, list):
+            for combo in combinations:
+                if isinstance(combo, dict):
+                    names.update(k for k in combo if isinstance(k, str))
+    return names
+
+
+def extract_defined_variables(scenario: Scenario, test_data: dict[str, Any]) -> set[str]:
+    """Extract variable names made available before/within templates.
+
+    Sources: ``vars`` and ``functions`` substitutions (scenario- and stage-level),
+    plus parameter names injected by ``parametrize`` and ``parallel.foreach`` — all
+    of which the engine wires into the evaluation context at runtime.
+    """
+    defined_vars: set[str] = set()
+
+    # Defensive: a top-level "vars" key is not a model field but is tolerated.
+    if "vars" in test_data and isinstance(test_data["vars"], dict):
+        defined_vars.update(k for k in test_data["vars"] if isinstance(k, str))
+
+    def add_substitution_names(subs: Any) -> None:
+        for sub in subs:
+            vars_ = getattr(sub, "vars", None)
+            if isinstance(vars_, dict):
+                defined_vars.update(k for k in vars_ if isinstance(k, str))
+            functions = getattr(sub, "functions", None)
+            if isinstance(functions, dict):
+                defined_vars.update(k for k in functions if isinstance(k, str))
+
+    add_substitution_names(scenario.substitutions)
+
+    for stage in scenario.stages:
+        add_substitution_names(stage.substitutions)
+        defined_vars |= _parameter_names(stage.parametrize)
+        if stage.parallel is not None:
+            defined_vars |= _parameter_names(getattr(stage.parallel, "foreach", None))
+
+    return defined_vars
+
+
+class ScenarioInfo(BaseModel):
+    """Detailed information about the scenario structure."""
+
+    num_stages: int = 0
+    stage_names: list[str] = []
+    vars_referenced: list[str] = []
+    vars_saved: list[str] = []
+    vars_defined: list[str] = []
+    fixtures: list[str] = []
+
+
+class ValidateResult(BaseModel):
+    """Result of scenario validation."""
+
+    valid: bool
+    errors: list[str] = []
+    warnings: list[str] = []
+    scenario_info: ScenarioInfo | None = None
+
+
+def check_scenario(scenario: Scenario, test_data: dict[str, Any]) -> tuple[list[str], list[str], ScenarioInfo]:
+    """Semantic checks on an already-loaded, schema-valid scenario.
+
+    Operates on the parsed ``test_data`` dict together with the validated ``Scenario``
+    so it can be shared by :func:`validate_scenario` (file-based) and by the pytest
+    collector. Returns ``(errors, warnings, scenario_info)``.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    stage_names = [stage.name for stage in scenario.stages]
+    seen_names: set[str] = set()
+    duplicate_names: set[str] = set()
+    for name in stage_names:
+        if name in seen_names:
+            duplicate_names.add(name)
+        seen_names.add(name)
+    if duplicate_names:
+        errors.append(f"Duplicate stage names found: {sorted(duplicate_names)}")
+
+    fixtures: list[str] = []
+    if "fixtures" in test_data and isinstance(test_data["fixtures"], list):
+        fixtures = list(test_data["fixtures"])
+    for stage in scenario.stages:
+        fixtures.extend(stage.fixtures)
+    fixtures = list(set(fixtures))
+
+    vars_defined = extract_defined_variables(scenario, test_data)
+    vars_saved = extract_saved_variables(scenario)
+    vars_referenced = extract_template_variables(test_data)
+
+    fixture_set = set(fixtures)
+    var_conflicts = fixture_set & vars_defined
+    if var_conflicts:
+        errors.append(f"Conflicting fixtures and vars with same names: {sorted(var_conflicts)}")
+
+    # NOTE: response data (response/status_code/body/json/text/headers/cookies) is
+    # NOT ambient in {{ }} templates — it reaches save/verify handlers directly and
+    # only enters the template context via an earlier `save` step. So there are no
+    # response "builtins" to whitelist here; template functions are already excluded
+    # from vars_referenced via TEMPLATE_BUILTINS.
+    all_available_vars = vars_defined | vars_saved | fixture_set
+
+    undefined_vars = vars_referenced - all_available_vars
+    if undefined_vars:
+        warnings.append(f"Potentially undefined variables referenced: {sorted(undefined_vars)}")
+
+    for stage in scenario.stages:
+        if not any(hasattr(step, "verify") for step in stage.response):
+            warnings.append(f"Stage '{stage.name}' has no response validation (no verify step)")
+
+    scenario_info = ScenarioInfo(
+        num_stages=len(scenario.stages),
+        stage_names=stage_names,
+        vars_referenced=sorted(vars_referenced),
+        vars_saved=sorted(vars_saved),
+        vars_defined=sorted(vars_defined),
+        fixtures=sorted(fixtures),
+    )
+
+    return errors, warnings, scenario_info
+
+
+def validate_scenario(
+    path: Path,
+    ref_parent_traversal_depth: int = 3,
+    root_path: Path | None = None,
+) -> ValidateResult:
+    """Validate a pytest-httpchain test scenario file.
+
+    Performs file/JSON/$ref/schema validation plus semantic checks (duplicate
+    stage names, undefined variables, fixture/variable conflicts, missing verify).
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not path.exists():
+        return ValidateResult(valid=False, errors=[f"File not found: {path}"])
+
+    if not path.is_file():
+        return ValidateResult(valid=False, errors=[f"Path is not a file: {path}"])
+
+    if path.suffix.lower() not in (".json",):
+        warnings.append(f"File has extension '{path.suffix}' but expected '.json'. Consider renaming to use .json extension.")
+
+    if root_path is None:
+        potential_root = path.parent
+        while potential_root.parent != potential_root:
+            if potential_root.name == "tests":
+                root_path = potential_root
+                break
+            potential_root = potential_root.parent
+        else:
+            root_path = path.parent
+
+    try:
+        test_data = pytest_httpchain_jsonref.loader.load_json(
+            path,
+            max_parent_traversal_depth=ref_parent_traversal_depth,
+            root_path=root_path,
+        )
+    except ReferenceResolverError as e:
+        return ValidateResult(valid=False, errors=[f"JSON reference resolution error: {e}"], warnings=warnings)
+    except json.JSONDecodeError as e:
+        return ValidateResult(valid=False, errors=[f"Invalid JSON syntax: {e}"], warnings=warnings)
+    except Exception as e:
+        return ValidateResult(valid=False, errors=[f"Failed to parse JSON file: {e}"], warnings=warnings)
+
+    try:
+        scenario = Scenario.model_validate(test_data)
+    except ValidationError as e:
+        error_details = [f"{' -> '.join(str(x) for x in err['loc'])}: {err['msg']}" for err in e.errors()]
+        return ValidateResult(valid=False, errors=["Schema validation failed:"] + error_details, warnings=warnings)
+
+    semantic_errors, semantic_warnings, scenario_info = check_scenario(scenario, test_data)
+    errors.extend(semantic_errors)
+    warnings.extend(semantic_warnings)
+
+    return ValidateResult(valid=not errors, errors=errors, warnings=warnings, scenario_info=scenario_info)

pytest_httpchain-0.2.4/src/pytest_httpchain/cli.py

@@ -1,67 +0,0 @@
-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()