pytest-httpchain 0.4.0__tar.gz → 0.5.0__tar.gz

{pytest_httpchain-0.4.0 → pytest_httpchain-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-httpchain
-Version: 0.4.0
+Version: 0.5.0
 Summary: pytest plugin for HTTP testing using JSON files
 Keywords: testing,pytest,requests
 Author: Alexander Eresov
@@ -198,17 +198,7 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 
 ## AI agent support
 
-`pytest-httpchain` ships tooling to help AI coding agents (and humans) author and check test scenarios.
-
-### Claude Code skill
-
-Install the authoring skill into your project (or `--global` for personal scope):
-
-```bash
-uvx pytest-httpchain install
-```
-
-This writes `.claude/skills/pytest-httpchain/SKILL.md` with guidance for writing scenarios.
+`pytest-httpchain` ships a scenario validator to help AI coding agents (and humans) author and check test scenarios.
 
 ### Scenario validation
 
@@ -242,6 +232,27 @@ A JSON Schema is published for as-you-type validation and autocomplete. Referenc
 }
 ```
 
+The hosted schema tracks the latest release; to pin the schema matching your installed version (e.g. for CI), emit it locally:
+
+```bash
+uvx pytest-httpchain schema --output scenario.schema.json
+```
+
+### Inspecting scenarios
+
+More read-only commands help author and debug scenarios offline — no network, no test run:
+
+```bash
+# Print a scenario with all $ref/$include/$merge inlined and deep-merged
+uvx pytest-httpchain resolve tests/test_login.http.json
+
+# Summarize stages and the variable data-flow (which stage saves what, who consumes it)
+uvx pytest-httpchain show tests/test_login.http.json
+
+# Render the stage data-flow as a Mermaid flowchart
+uvx pytest-httpchain graph tests/test_login.http.json
+```
+
 ## Documentation
 
 -   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete usage guide

{pytest_httpchain-0.4.0 → pytest_httpchain-0.5.0}/README.md

@@ -171,17 +171,7 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 
 ## AI agent support
 
-`pytest-httpchain` ships tooling to help AI coding agents (and humans) author and check test scenarios.
-
-### Claude Code skill
-
-Install the authoring skill into your project (or `--global` for personal scope):
-
-```bash
-uvx pytest-httpchain install
-```
-
-This writes `.claude/skills/pytest-httpchain/SKILL.md` with guidance for writing scenarios.
+`pytest-httpchain` ships a scenario validator to help AI coding agents (and humans) author and check test scenarios.
 
 ### Scenario validation
 
@@ -215,6 +205,27 @@ A JSON Schema is published for as-you-type validation and autocomplete. Referenc
 }
 ```
 
+The hosted schema tracks the latest release; to pin the schema matching your installed version (e.g. for CI), emit it locally:
+
+```bash
+uvx pytest-httpchain schema --output scenario.schema.json
+```
+
+### Inspecting scenarios
+
+More read-only commands help author and debug scenarios offline — no network, no test run:
+
+```bash
+# Print a scenario with all $ref/$include/$merge inlined and deep-merged
+uvx pytest-httpchain resolve tests/test_login.http.json
+
+# Summarize stages and the variable data-flow (which stage saves what, who consumes it)
+uvx pytest-httpchain show tests/test_login.http.json
+
+# Render the stage data-flow as a Mermaid flowchart
+uvx pytest-httpchain graph tests/test_login.http.json
+```
+
 ## Documentation
 
 -   [Full Documentation](https://aeresov.github.io/pytest-httpchain) - Complete usage guide

{pytest_httpchain-0.4.0 → pytest_httpchain-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-httpchain"
-version = "0.4.0"
+version = "0.5.0"
 description = "pytest plugin for HTTP testing using JSON files"
 readme = "README.md"
 requires-python = ">=3.13,<4.0"

pytest_httpchain-0.5.0/src/pytest_httpchain/cli.py

@@ -0,0 +1,222 @@
+import enum
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+app = typer.Typer()
+
+
+class OutputFormat(enum.StrEnum):
+    text = "text"
+    json = "json"
+
+
+class GraphDirection(enum.StrEnum):
+    TD = "TD"
+    LR = "LR"
+
+
+@app.callback()
+def main() -> None:
+    """pytest-httpchain command-line tools."""
+
+
+@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,
+    output_format: Annotated[OutputFormat, typer.Option("--format", help="Output format: human-readable text or machine-readable JSON.")] = OutputFormat.text,
+    deep: Annotated[bool, typer.Option("--deep", help="Run deep checks: resolve user-function imports/signatures and referenced files. Imports user modules.")] = False,
+    syspath: Annotated[list[Path] | None, typer.Option("--syspath", help="Extra directories to add to sys.path for --deep import resolution (repeatable).")] = None,
+    strict: Annotated[bool, typer.Option("--strict", help="Treat warnings as failures for the exit code.")] = False,
+) -> None:
+    """Validate pytest-httpchain scenario file(s).
+
+    Reports errors and warnings (each with a stable HTTPCHAINxxx diagnostic code)
+    per file and exits non-zero if any file is invalid (or, with --strict, has any
+    warnings).
+    """
+    from pytest_httpchain.validation import validate_scenario
+
+    results = [(path, validate_scenario(path, ref_parent_traversal_depth=ref_parent_traversal_depth, deep=deep, syspaths=list(syspath or []))) for path in paths]
+
+    def passed(result) -> bool:
+        return result.valid and not (strict and result.warnings)
+
+    all_passed = all(passed(result) for _, result in results)
+
+    if output_format is OutputFormat.json:
+        payload = {
+            "valid": all_passed,
+            "files": [{"path": str(path), "result": result.model_dump()} for path, result in results],
+        }
+        typer.echo(json.dumps(payload, indent=2, default=str))
+    else:
+        for path, result in results:
+            if not result.valid:
+                status = "INVALID"
+            elif result.warnings:
+                status = "FAILED (warnings)" if strict else "OK with warnings"
+            else:
+                status = "OK"
+            typer.echo(f"{path}: {status}")
+            for diagnostic in result.diagnostics:
+                typer.echo(f"  {diagnostic.severity} [{diagnostic.code}]: {diagnostic.message}")
+
+    raise typer.Exit(0 if all_passed else 1)
+
+
+@app.command()
+def schema(
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Write schema to PATH instead of stdout.")] = None,
+) -> None:
+    """Emit the JSON Schema for scenario files (editor autocomplete/validation)."""
+    from pytest_httpchain.schema import build_schema
+
+    text = json.dumps(build_schema(), indent=2, default=str)
+    if output is not None:
+        output.write_text(text + "\n")
+        typer.echo(f"Wrote schema to {output}")
+    else:
+        typer.echo(text)
+
+
+@app.command()
+def resolve(
+    scenario: Annotated[Path, typer.Argument(help="Scenario JSON file to resolve.")],
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Write resolved JSON to PATH instead of stdout.")] = None,
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Resolve $ref/$include/$merge and print the merged scenario JSON."""
+    import pytest_httpchain_jsonref.loader
+    from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+
+    from pytest_httpchain.validation import resolve_root_path
+
+    try:
+        data = pytest_httpchain_jsonref.loader.load_json(
+            scenario,
+            max_parent_traversal_depth=ref_parent_traversal_depth,
+            root_path=resolve_root_path(scenario),
+        )
+    except (ReferenceResolverError, json.JSONDecodeError, OSError) as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    text = json.dumps(data, indent=2, default=str)
+    if output is not None:
+        output.write_text(text + "\n")
+        typer.echo(f"Wrote resolved scenario to {output}")
+    else:
+        typer.echo(text)
+
+
+def _load_for_inspection(path: Path, depth: int):
+    """Load + validate a scenario for show/graph, mapping failures to Exit(1)."""
+    from pydantic import ValidationError
+    from pytest_httpchain_jsonref.exceptions import ReferenceResolverError
+
+    from pytest_httpchain.dataflow import load_scenario
+
+    try:
+        return load_scenario(path, ref_parent_traversal_depth=depth)
+    except (ReferenceResolverError, json.JSONDecodeError, OSError) as e:
+        typer.echo(f"error: cannot load {path}: {e}", err=True)
+        raise typer.Exit(1) from e
+    except ValidationError:
+        typer.echo(f"error: {path} is not a valid scenario — run `pytest-httpchain validate {path}` for details", err=True)
+        raise typer.Exit(1) from None
+
+
+def _render_show_text(path: Path, scenario, flow) -> list[str]:
+    producer_of: dict[tuple[int, str], int] = {}
+    for edge in flow.edges:
+        for name in edge.vars:
+            producer_of[(edge.consumer, name)] = edge.producer
+
+    all_fixtures = sorted({*flow.scenario_fixtures, *(f for s in flow.stages for f in s.fixtures)})
+    lines: list[str] = [scenario.description or path.name]
+    summary = f"{len(flow.stages)} stage(s)"
+    if all_fixtures:
+        summary += f" · fixtures: {all_fixtures}"
+    if flow.scenario_vars:
+        summary += f" · vars: {flow.scenario_vars}"
+    lines.append(summary)
+    lines.append("")
+
+    for s in flow.stages:
+        name = s.name or f"(stage {s.index + 1})"
+        lines.append(f"{s.index + 1} · {name}    {s.method} {s.url}")
+        if s.saves:
+            lines.append(f"    saves:    {', '.join(s.saves)}")
+        if s.consumes:
+            parts: list[str] = []
+            for name in s.consumes:
+                producer = producer_of.get((s.index, name))
+                if producer is None:
+                    parts.append(name)
+                else:
+                    producer_name = flow.stages[producer].name or f"stage {producer + 1}"
+                    parts.append(f"{name} (from #{producer + 1} {producer_name})")
+            lines.append(f"    consumes: {', '.join(parts)}")
+        if s.marks:
+            lines.append(f"    marks:    {', '.join(s.marks)}")
+    return lines
+
+
+@app.command()
+def show(
+    scenario: Annotated[Path, typer.Argument(help="Scenario JSON file to summarize.")],
+    output_format: Annotated[OutputFormat, typer.Option("--format", help="Output format: human-readable text or machine-readable JSON.")] = OutputFormat.text,
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Summarize a scenario's stages and variable data-flow."""
+    from pytest_httpchain.dataflow import analyze_dataflow
+
+    sc, test_data = _load_for_inspection(scenario, ref_parent_traversal_depth)
+    flow = analyze_dataflow(sc, test_data)
+
+    if output_format is OutputFormat.json:
+        payload = flow.model_dump()
+        payload["description"] = sc.description or None
+        typer.echo(json.dumps(payload, indent=2, default=str))
+    else:
+        for line in _render_show_text(scenario, sc, flow):
+            typer.echo(line)
+
+
+def _mermaid_label(text: str) -> str:
+    return text.replace('"', "'").replace("\n", " ")
+
+
+def _to_mermaid(flow, direction: str = "TD") -> str:
+    lines = [f"flowchart {direction}"]
+    if not flow.stages:
+        lines.append("    %% (no stages)")
+        return "\n".join(lines)
+    for s in flow.stages:
+        label = f"{s.index + 1} · {s.name}" if s.name else f"{s.index + 1}"
+        lines.append(f'    S{s.index}["{_mermaid_label(label)}"]')
+    for edge in flow.edges:
+        lines.append(f"    S{edge.producer} -->|{', '.join(edge.vars)}| S{edge.consumer}")
+    return "\n".join(lines)
+
+
+@app.command()
+def graph(
+    scenario: Annotated[Path, typer.Argument(help="Scenario JSON file to graph.")],
+    direction: Annotated[GraphDirection, typer.Option("--direction", help="Flowchart orientation.")] = GraphDirection.TD,
+    ref_parent_traversal_depth: Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")] = 3,
+) -> None:
+    """Emit a Mermaid flowchart of the stage data-flow."""
+    from pytest_httpchain.dataflow import analyze_dataflow
+
+    sc, test_data = _load_for_inspection(scenario, ref_parent_traversal_depth)
+    flow = analyze_dataflow(sc, test_data)
+    typer.echo(_to_mermaid(flow, direction.value))
+
+
+if __name__ == "__main__":
+    app()

pytest_httpchain-0.5.0/src/pytest_httpchain/dataflow.py

@@ -0,0 +1,127 @@
+"""Structured stage data-flow analysis for the ``show`` and ``graph`` CLI commands.
+
+Reuses the same extraction helpers as the order-aware validator
+(``validation._dataflow_diagnostics``) but produces a graph model instead of
+diagnostics: which variables each stage saves, which it consumes from earlier
+stages, and the producer -> consumer edges between stages.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import pytest_httpchain_jsonref.loader
+from pydantic import BaseModel
+from pytest_httpchain_models import Scenario
+
+from pytest_httpchain.validation import (
+    extract_template_variables,
+    raw_stages,
+    resolve_root_path,
+    saved_in_stage,
+    stage_defined_names,
+    substitution_names,
+)
+
+
+class DataFlowEdge(BaseModel):
+    """A data dependency: ``vars`` saved by stage ``producer`` are referenced by stage ``consumer``."""
+
+    producer: int
+    consumer: int
+    vars: list[str]
+
+
+class StageFlow(BaseModel):
+    """Per-stage data-flow summary."""
+
+    index: int
+    name: str
+    method: str
+    url: str
+    fixtures: list[str]
+    marks: list[str]
+    saves: list[str]
+    consumes: list[str]
+
+
+class DataFlow(BaseModel):
+    """Whole-scenario data-flow graph."""
+
+    stages: list[StageFlow]
+    edges: list[DataFlowEdge]
+    scenario_fixtures: list[str] = []
+    scenario_vars: list[str] = []
+
+
+def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
+    """Build the stage data-flow graph for a validated scenario.
+
+    A stage *consumes* a variable when its request/response/substitutions/parallel
+    templates reference a name saved by an earlier stage and not redefined locally
+    (own substitutions, parametrize/foreach parameters, or fixtures). ``parametrize``
+    values are excluded — they resolve against scenario scope, never saved values.
+    """
+    raws = raw_stages(test_data)
+    saves_by_stage = [saved_in_stage(stage) for stage in scenario.stages]
+
+    first_save_stage: dict[str, int] = {}
+    for i, saved in enumerate(saves_by_stage):
+        for name in saved:
+            first_save_stage.setdefault(name, i)
+
+    stages: list[StageFlow] = []
+    edges: list[DataFlowEdge] = []
+    cumulative_saves: set[str] = set()
+
+    for i, stage in enumerate(scenario.stages):
+        raw = raws[i] if i < len(raws) and isinstance(raws[i], dict) else {}
+
+        refs: set[str] = set()
+        for key in ("request", "response", "substitutions", "parallel"):
+            extract_template_variables(raw.get(key), refs)
+
+        local = stage_defined_names(stage)
+        consumes = {name for name in refs if name in cumulative_saves and name not in local}
+
+        by_producer: dict[int, list[str]] = {}
+        for name in consumes:
+            by_producer.setdefault(first_save_stage[name], []).append(name)
+        for producer in sorted(by_producer):
+            edges.append(DataFlowEdge(producer=producer, consumer=i, vars=sorted(by_producer[producer])))
+
+        stages.append(
+            StageFlow(
+                index=i,
+                name=stage.name,
+                method=str(stage.request.method),
+                url=str(stage.request.url),
+                fixtures=sorted(stage.fixtures),
+                marks=list(stage.marks),
+                saves=sorted(saves_by_stage[i]),
+                consumes=sorted(consumes),
+            )
+        )
+
+        cumulative_saves |= saves_by_stage[i]
+
+    scenario_fixtures = sorted(f for f in test_data["fixtures"] if isinstance(f, str)) if isinstance(test_data.get("fixtures"), list) else []
+    scenario_var_names = set(substitution_names(scenario.substitutions))
+    if isinstance(test_data.get("vars"), dict):
+        scenario_var_names |= {k for k in test_data["vars"] if isinstance(k, str)}
+
+    return DataFlow(stages=stages, edges=edges, scenario_fixtures=scenario_fixtures, scenario_vars=sorted(scenario_var_names))
+
+
+def load_scenario(path: Path, ref_parent_traversal_depth: int = 3) -> tuple[Scenario, dict[str, Any]]:
+    """Load + ``$ref``-resolve + validate a scenario file.
+
+    Returns ``(scenario, raw_test_data)``. Raises ``ReferenceResolverError``,
+    ``json.JSONDecodeError`` or ``pydantic.ValidationError`` on failure — callers
+    map these to user-facing errors.
+    """
+    test_data = pytest_httpchain_jsonref.loader.load_json(
+        path,
+        max_parent_traversal_depth=ref_parent_traversal_depth,
+        root_path=resolve_root_path(path),
+    )
+    return Scenario.model_validate(test_data), test_data

pytest_httpchain-0.5.0/src/pytest_httpchain/schema.py

@@ -0,0 +1,69 @@
+"""Build the JSON Schema for pytest-httpchain scenario files.
+
+Shared by the ``pytest-httpchain schema`` CLI command and
+``scripts/generate_schema.py``. The schema is derived from the Pydantic
+``Scenario`` model and augmented so editors accept pytest-httpchain's
+``$ref``/``$include``/``$merge`` reference directives at any object level.
+"""
+
+from typing import Any
+
+from pytest_httpchain_models import Scenario
+
+SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+SCHEMA_ID = "https://aeresov.github.io/pytest-httpchain/schema/scenario.schema.json"
+
+
+def _add_jsonref_support(schema: dict[str, Any]) -> dict[str, Any]:
+    """Allow ``$include``/``$merge``/``$ref`` objects as alternatives anywhere.
+
+    pytest-httpchain-jsonref can substitute any element at runtime, so each
+    definition and root property is wrapped in an ``anyOf`` that also accepts a
+    reference object — otherwise editors flag missing required properties when a
+    reference is used.
+    """
+    if "$defs" not in schema:
+        schema["$defs"] = {}
+
+    schema["$defs"]["JsonRef"] = {
+        "type": "object",
+        "description": "Reference to external JSON file or JSON pointer. Use $include or $merge (preferred) or $ref. Resolved at runtime by pytest-httpchain-jsonref.",
+        "properties": {
+            "$include": {
+                "type": "string",
+                "description": "Path to external JSON file, JSON pointer (#/path), or combined (file.json#/path). Preferred over $ref to avoid VS Code conflicts.",
+            },
+            "$merge": {
+                "type": "string",
+                "description": "Alias for $include. Path to external JSON file, JSON pointer (#/path), or combined (file.json#/path).",
+            },
+        },
+        "additionalProperties": True,
+    }
+
+    for type_name, original_def in list(schema["$defs"].items()):
+        if type_name == "JsonRef":
+            continue
+        schema["$defs"][type_name] = {"anyOf": [{"$ref": "#/$defs/JsonRef"}, original_def]}
+        if "title" in original_def:
+            schema["$defs"][type_name]["title"] = original_def.pop("title")
+        if "description" in original_def:
+            schema["$defs"][type_name]["description"] = original_def.pop("description")
+
+    for prop_name, prop_def in list(schema.get("properties", {}).items()):
+        schema["properties"][prop_name] = {
+            "anyOf": [{"$ref": "#/$defs/JsonRef"}, prop_def],
+            "title": prop_def.get("title", prop_name),
+        }
+        if "description" in prop_def:
+            schema["properties"][prop_name]["description"] = prop_def.get("description")
+
+    return schema
+
+
+def build_schema() -> dict[str, Any]:
+    """Return the augmented JSON Schema dict for the ``Scenario`` model."""
+    schema = Scenario.model_json_schema()
+    schema["$schema"] = SCHEMA_DIALECT
+    schema["$id"] = SCHEMA_ID
+    return _add_jsonref_support(schema)

{pytest_httpchain-0.4.0 → pytest_httpchain-0.5.0}/src/pytest_httpchain/validation.py

@@ -152,7 +152,7 @@ def extract_template_variables(obj: Any, variables: set[str] | None = None) -> s
     return variables
 
 
-def _substitution_names(substitutions: Any) -> set[str]:
+def substitution_names(substitutions: Any) -> set[str]:
     """Names introduced by a list of ``vars``/``functions`` substitution entries."""
     names: set[str] = set()
     for sub in substitutions or []:
@@ -165,7 +165,7 @@ def _substitution_names(substitutions: Any) -> set[str]:
     return names
 
 
-def _saved_in_stage(stage: Stage) -> set[str]:
+def saved_in_stage(stage: Stage) -> set[str]:
     """Variable names a single stage's response steps save into the context."""
     saved: set[str] = set()
     for response_step in stage.response:
@@ -177,7 +177,7 @@ def _saved_in_stage(stage: Stage) -> set[str]:
             saved.update(jmespath.keys())
         substitutions = getattr(save, "substitutions", None)
         if substitutions is not None:
-            saved |= _substitution_names(substitutions)
+            saved |= substitution_names(substitutions)
         # user_functions saves return arbitrary dict keys -> not statically known.
     return saved
 
@@ -186,7 +186,7 @@ def extract_saved_variables(scenario: Scenario) -> set[str]:
     """Extract variable names saved across all response steps in the scenario."""
     saved_vars: set[str] = set()
     for stage in scenario.stages:
-        saved_vars |= _saved_in_stage(stage)
+        saved_vars |= saved_in_stage(stage)
     return saved_vars
 
 
@@ -210,10 +210,10 @@ def _parameter_names(params: Any) -> set[str]:
     return names
 
 
-def _stage_defined_names(stage: Stage) -> set[str]:
+def stage_defined_names(stage: Stage) -> set[str]:
     """Names available *within a single stage*: its substitutions, parametrize /
     foreach parameters, and its declared fixtures."""
-    names = _substitution_names(stage.substitutions)
+    names = substitution_names(stage.substitutions)
     names |= _parameter_names(stage.parametrize)
     if stage.parallel is not None:
         names |= _parameter_names(getattr(stage.parallel, "foreach", None))
@@ -236,10 +236,10 @@ def extract_defined_variables(scenario: Scenario, test_data: dict[str, Any]) ->
     if isinstance(test_data.get("vars"), dict):
         defined_vars.update(k for k in test_data["vars"] if isinstance(k, str))
 
-    defined_vars |= _substitution_names(scenario.substitutions)
+    defined_vars |= substitution_names(scenario.substitutions)
 
     for stage in scenario.stages:
-        defined_vars |= _substitution_names(stage.substitutions)
+        defined_vars |= 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))
@@ -247,7 +247,7 @@ def extract_defined_variables(scenario: Scenario, test_data: dict[str, Any]) ->
     return defined_vars
 
 
-def _raw_stages(test_data: dict[str, Any]) -> list[Any]:
+def raw_stages(test_data: dict[str, Any]) -> list[Any]:
     """Raw (pre-validation) stage bodies in declaration order.
 
     Stages may be authored as a list or as a ``{name: stage}`` mapping; both
@@ -298,7 +298,7 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any]) -> list
     diagnostics: list[Diagnostic] = []
 
     all_saved = extract_saved_variables(scenario)
-    saves_by_stage: list[set[str]] = [_saved_in_stage(stage) for stage in scenario.stages]
+    saves_by_stage: list[set[str]] = [saved_in_stage(stage) for stage in scenario.stages]
     first_save_stage: dict[str, int] = {}
     for i, saved in enumerate(saves_by_stage):
         for name in saved:
@@ -312,19 +312,19 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any]) -> list
     scenario_scope: set[str] = set()
     if isinstance(test_data.get("vars"), dict):
         scenario_scope |= {k for k in test_data["vars"] if isinstance(k, str)}
-    scenario_scope |= _substitution_names(scenario.substitutions)
+    scenario_scope |= substitution_names(scenario.substitutions)
 
     scenario_available = set(scenario_scope)
     if isinstance(test_data.get("fixtures"), list):
         scenario_available |= {f for f in test_data["fixtures"] if isinstance(f, str)}
 
-    raw_stages = _raw_stages(test_data)
+    raws = raw_stages(test_data)
     cumulative_saves: set[str] = set()
 
     for i, stage in enumerate(scenario.stages):
-        raw = raw_stages[i] if i < len(raw_stages) and isinstance(raw_stages[i], dict) else {}
+        raw = raws[i] if i < len(raws) and isinstance(raws[i], dict) else {}
 
-        request_available = scenario_available | _stage_defined_names(stage) | cumulative_saves
+        request_available = scenario_available | stage_defined_names(stage) | cumulative_saves
         response_available = request_available | saves_by_stage[i]
 
         # ``parallel.foreach`` values are resolved at stage execution against the
@@ -736,6 +736,17 @@ def check_scenario(scenario: Scenario, test_data: dict[str, Any]) -> tuple[list[
     return diagnostics, scenario_info
 
 
+def resolve_root_path(path: Path) -> Path:
+    """Directory that constrains ``$ref`` resolution: the nearest ``tests/``
+    ancestor of ``path``, else the file's own parent."""
+    potential_root = path.parent
+    while potential_root.parent != potential_root:
+        if potential_root.name == "tests":
+            return potential_root
+        potential_root = potential_root.parent
+    return path.parent
+
+
 def validate_scenario(
     path: Path,
     ref_parent_traversal_depth: int = 3,
@@ -772,14 +783,7 @@ def validate_scenario(
         )
 
     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
+        root_path = resolve_root_path(path)
 
     try:
         test_data = pytest_httpchain_jsonref.loader.load_json(

pytest_httpchain-0.4.0/src/pytest_httpchain/cli.py

@@ -1,83 +0,0 @@
-import enum
-import json
-from pathlib import Path
-from typing import Annotated
-
-import typer
-
-app = typer.Typer()
-
-SKILL_FILE = Path(__file__).parent / "skill.md"
-
-
-class OutputFormat(enum.StrEnum):
-    text = "text"
-    json = "json"
-
-
-@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,
-    output_format: Annotated[OutputFormat, typer.Option("--format", help="Output format: human-readable text or machine-readable JSON.")] = OutputFormat.text,
-    deep: Annotated[bool, typer.Option("--deep", help="Run deep checks: resolve user-function imports/signatures and referenced files. Imports user modules.")] = False,
-    syspath: Annotated[list[Path] | None, typer.Option("--syspath", help="Extra directories to add to sys.path for --deep import resolution (repeatable).")] = None,
-    strict: Annotated[bool, typer.Option("--strict", help="Treat warnings as failures for the exit code.")] = False,
-) -> None:
-    """Validate pytest-httpchain scenario file(s).
-
-    Reports errors and warnings (each with a stable HTTPCHAINxxx diagnostic code)
-    per file and exits non-zero if any file is invalid (or, with --strict, has any
-    warnings).
-    """
-    from pytest_httpchain.validation import validate_scenario
-
-    results = [(path, validate_scenario(path, ref_parent_traversal_depth=ref_parent_traversal_depth, deep=deep, syspaths=list(syspath or []))) for path in paths]
-
-    def passed(result) -> bool:
-        return result.valid and not (strict and result.warnings)
-
-    all_passed = all(passed(result) for _, result in results)
-
-    if output_format is OutputFormat.json:
-        payload = {
-            "valid": all_passed,
-            "files": [{"path": str(path), "result": result.model_dump()} for path, result in results],
-        }
-        typer.echo(json.dumps(payload, indent=2, default=str))
-    else:
-        for path, result in results:
-            if not result.valid:
-                status = "INVALID"
-            elif result.warnings:
-                status = "FAILED (warnings)" if strict else "OK with warnings"
-            else:
-                status = "OK"
-            typer.echo(f"{path}: {status}")
-            for diagnostic in result.diagnostics:
-                typer.echo(f"  {diagnostic.severity} [{diagnostic.code}]: {diagnostic.message}")
-
-    raise typer.Exit(0 if all_passed 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.4.0/src/pytest_httpchain/skill.md

@@ -1,282 +0,0 @@
----
-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" },
-      "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)"
-      }
-    }
-  },
-  {
-    "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
-- `{"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 } },
-        { "save": { "jmespath": { "name": "name" } } },
-        { "verify": { "expressions": ["{{ name == 'Alice' }}"] } }
-      ]
-    },
-    {
-      "name": "delete user",
-      "request": {
-        "url": "{{ base }}/users/{{ user_id }}",
-        "method": "DELETE"
-      },
-      "response": [
-        { "verify": { "status": 204 } }
-      ]
-    }
-  ]
-}
-```
-
-## Validate your scenario
-
-After writing a scenario, validate it (no server or network needed):
-
-```bash
-pytest-httpchain validate test_<name>.http.json
-```
-
-It checks structure plus semantics a JSON Schema cannot, each with a stable `HTTPCHAINxxx` code:
-
-- `HTTPCHAIN003` — a `{{ var }}` that is never defined, saved, or provided as a fixture (likely a typo).
-- `HTTPCHAIN004` — a variable used **before** the stage that saves it, or used in a stage's request when it is only saved in that same stage's response. Remember: a value `save`d in a stage's response is available to *later* response steps and *later* stages, never to the request that produced it.
-- `HTTPCHAIN006` — a `verify` step that asserts nothing.
-- `HTTPCHAIN007` / `HTTPCHAIN008` — body `contains`/`not_contains` (or `matches`/`not_matches`) that list the same value, which can never pass.
-
-Add `--format json` for machine-readable output. The same checks run automatically during `pytest --collect-only`.
-
-For a deeper check that imports your `module:func` references (confirming they resolve and their signatures match — including the injected `response` for save/verify functions) and verifies referenced files/schemas exist, add `--deep` (optionally `--syspath <dir>` for import roots, `--strict` to fail on warnings):
-
-```bash
-pytest-httpchain validate --deep test_<name>.http.json
-```
-
-Note: the HTTP response is **not** ambient in `{{ }}` templates — `save` what you need from a response first, then reference the saved variable.