pytest-httpchain 0.7.0__tar.gz → 0.8.1__tar.gz

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pytest-httpchain
-Version: 0.7.0
+Version: 0.8.1
 Summary: pytest plugin for HTTP testing using JSON files
-Keywords: testing,pytest,requests
+Keywords: testing,pytest,httpx,http,api,integration-testing
 Author: Alexander Eresov
 Author-email: Alexander Eresov <aeresov@gmail.com>
 License-Expression: MIT
@@ -197,11 +197,21 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 
 -   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 using relative paths; absolute paths are rejected for security.
     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**.
 
+### HAR export
+
+Pass `--output-dir DIR` on the pytest command line to write an [HAR](http://www.softwareishard.com/blog/har-12-spec/) file (and a "HAR File" report section) capturing each test's HTTP traffic:
+
+```bash
+pytest --output-dir ./har-output
+```
+
+HAR files contain full requests/responses **including credential headers and saved tokens** — nothing is redacted, so scrub them before sharing. See the [HAR export docs](https://aeresov.github.io/pytest-httpchain/getting-started/#har-export).
+
 ## AI agent support
 
 `pytest-httpchain` ships a scenario validator to help AI coding agents (and humans) author and check test scenarios.
@@ -241,7 +251,7 @@ 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
+uvx pytest-httpchain schema > scenario.schema.json
 ```
 
 ### Inspecting scenarios

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/README.md

@@ -164,11 +164,21 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
 
 -   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 using relative paths; absolute paths are rejected for security.
     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**.
 
+### HAR export
+
+Pass `--output-dir DIR` on the pytest command line to write an [HAR](http://www.softwareishard.com/blog/har-12-spec/) file (and a "HAR File" report section) capturing each test's HTTP traffic:
+
+```bash
+pytest --output-dir ./har-output
+```
+
+HAR files contain full requests/responses **including credential headers and saved tokens** — nothing is redacted, so scrub them before sharing. See the [HAR export docs](https://aeresov.github.io/pytest-httpchain/getting-started/#har-export).
+
 ## AI agent support
 
 `pytest-httpchain` ships a scenario validator to help AI coding agents (and humans) author and check test scenarios.
@@ -208,7 +218,7 @@ 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
+uvx pytest-httpchain schema > scenario.schema.json
 ```
 
 ### Inspecting scenarios

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-httpchain"
-version = "0.7.0"
+version = "0.8.1"
 description = "pytest plugin for HTTP testing using JSON files"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -21,7 +21,7 @@ dependencies = [
     "simpleeval>=1.0.3",
     "typer>=0.16.0",
 ]
-keywords = ["testing", "pytest", "requests"]
+keywords = ["testing", "pytest", "httpx", "http", "api", "integration-testing"]
 license = "MIT"
 license-files = ["LICENSE"]
 classifiers = [
@@ -94,6 +94,26 @@ ignore = []
 [tool.ruff.lint.isort]
 known-first-party = ["tests", "utils"]
 
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.terminal]
+error-on-warning = true
+
+# Test suites (especially the models package) deliberately construct models with
+# invalid types to assert ValidationError, and access attributes on unions/mocks
+# the checker can't narrow. Relax those specific rules for test code only; src/
+# stays strict and uses pinpoint `# ty: ignore[...]` comments instead.
+[[tool.ty.overrides]]
+include = ["tests/**", "packages/*/tests/**"]
+
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"
+unknown-argument = "ignore"
+unresolved-attribute = "ignore"
+not-subscriptable = "ignore"
+missing-argument = "ignore"
+
 [tool.pytest]
 minversion = "9.0"
 log_cli = true

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/carrier.py

@@ -1,7 +1,7 @@
 """Test execution engine for pytest-httpchain scenarios.
 
-``create_test_class`` turns a validated :class:`Scenario` into a dynamic pytest
-test class (a subclass of :class:`Carrier`), one ``test_NN - <stage name>``
+``create_test_class`` turns a validated `Scenario` into a dynamic pytest
+test class (a subclass of `Carrier`), one ``test_NN - <stage name>``
 method per stage, ordered by the ``order(i)`` marker so the stages run as a
 chain. Each scenario gets its own subclass; the per-scenario mutable state
 (``client``, ``global_context``, ``aborted``, ``last_request``/``last_response``,
@@ -10,7 +10,7 @@ subclass dict, so the stage methods — which are classmethods operating on
 ``cls`` — share one running context across the chain while different scenarios
 stay isolated from each other.
 
-Per stage, :meth:`Carrier.execute_stage` gates on the abort/``always_run`` flow,
+Per stage, `Carrier.execute_stage` gates on the abort/``always_run`` flow,
 layers fixtures and substitutions over the global context, expands any
 ``parallel`` config into iterations (sequential or thread-pooled, optionally
 rate limited), executes the HTTP request via httpx, runs the response
@@ -98,6 +98,13 @@ class Carrier:
     It manages the shared state, context, and execution flow for all stages in a test scenario.
     """
 
+    # These ClassVars are placeholders: create_test_class() overrides every one of
+    # them in each per-scenario subclass dict (see the bottom of this module), so
+    # the values here are never the ones used at runtime — do NOT rely on the
+    # ChainMap()/None/[] defaults, and do NOT move this state to instance
+    # attributes: the stage methods are classmethods that share one running context
+    # across the chain via `cls`, while distinct scenarios stay isolated because
+    # each gets its own subclass.
     client: ClassVar[httpx.Client | None] = None
     aborted: ClassVar[bool] = False
     last_request: ClassVar[httpx.Request | None] = None
@@ -155,9 +162,10 @@ class Carrier:
 
             total = len(iteration_substitutions)
             if total == 0:
-                # Unreachable via validated models (foreach values have min_length=1,
-                # repeat is PositiveInt), but guard so a future gap fails loudly
-                # instead of passing a stage that never sent a request.
+                # The models reject the static empty cases (foreach/combinations
+                # have min_length=1, repeat is PositiveInt), but a template- or
+                # $ref-sourced parallel config can still resolve to empty at
+                # runtime, so guard rather than silently send zero requests.
                 raise StageExecutionError("Parallel configuration produced zero iterations; foreach/repeat must yield at least one item")
             if total > cls.max_parallel_iterations:
                 raise StageExecutionError(
@@ -221,8 +229,11 @@ class Carrier:
     def _build_iteration_substitutions(parallel_config: Any) -> list[dict[str, Any]]:
         """Expand the (already template-resolved) parallel config into per-iteration
         substitution dicts: non-parallel -> a single empty dict; ``repeat`` -> N
-        empties; ``foreach`` -> the cross-product of its parameter steps (the same
-        algorithm pytest uses for the ``parametrize`` marker)."""
+        empties; ``foreach`` -> the cross-product of its parameter steps.
+
+        Like pytest's stacked ``parametrize`` marker this is a cross-product, but the
+        resulting iteration ORDER is the *reverse* of pytest's — do not assume the
+        two orders match."""
         iteration_substitutions: list[dict[str, Any]] = [{}]
         match parallel_config:
             case None:
@@ -231,13 +242,17 @@ class Carrier:
                 iteration_substitutions = [{} for _ in range(repeat_count)]
             case ParallelForeachConfig(foreach=foreach_steps):
                 for step in foreach_steps:
+                    # Comprehension clause order is load-bearing: the new values are the
+                    # OUTER loop and the accumulated dicts the INNER loop, which is what
+                    # produces the (reverse-of-pytest) ordering noted above. Swapping the
+                    # two `for` clauses silently changes the iteration order.
                     match step:
                         case IndividualParameter(individual=individual):
                             param_name = next(iter(individual.keys()))
                             values = individual[param_name]
                             iteration_substitutions = [{**existing, param_name: val} for val in values for existing in iteration_substitutions]
                         case CombinationsParameter(combinations=combinations):
-                            combos: list[dict[str, Any] | SimpleNamespace] = [vars(item) if isinstance(item, SimpleNamespace) else item for item in combinations]
+                            combos: list[dict[str, Any]] = [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]
         return iteration_substitutions
 
@@ -352,7 +367,7 @@ class Carrier:
     @classmethod
     def _execute_http_request(cls, request_kwargs: dict[str, Any]) -> httpx.Response:
         try:
-            return cls.client.request(**request_kwargs)
+            return cls.client.request(**request_kwargs)  # ty: ignore[unresolved-attribute]
         except httpx.TimeoutException as e:
             raise RequestError(f"HTTP request timed out: {e}") from e
         except httpx.ConnectError as e:
@@ -395,7 +410,7 @@ class Carrier:
                         if not isinstance(func_result, dict):
                             raise SaveError(f"Save function must return dict, got {type(func_result).__name__}")
 
-                        step_saved.update(func_result)
+                        step_saved.update(func_result)  # ty: ignore[no-matching-overload]
                     except SaveError:
                         raise
                     except UserFunctionError as e:
@@ -517,6 +532,15 @@ class Carrier:
 
     @classmethod
     def _wrap_factory_fixture(cls, fixture: Callable) -> Callable:
+        """Wrap a callable fixture so context-manager results are entered and tracked.
+
+        Not a pure pass-through: each call invokes ``fixture`` and, if the result is
+        a context manager, calls ``__enter__()`` and registers it on
+        ``cls.active_context_managers`` for LIFO teardown in ``teardown_class``.
+        Consequence: calling the wrapped value twice opens two resources (two
+        ``__enter__`` calls, two teardowns) — invoke it once per needed instance.
+        """
+
         def wrapped(*args, **kwargs):
             result = fixture(*args, **kwargs)
 
@@ -543,6 +567,19 @@ class Carrier:
             cls.client = None
 
 
+def _normalize_cert(cert: Any) -> str | tuple[str, ...]:
+    """Stringify SSL client-cert paths for httpx.
+
+    The model stores ``cert`` as ``pathlib.Path`` (single) or a tuple of Paths.
+    httpx builds the SSL context via ``load_cert_chain(*cert)`` for a non-tuple
+    cert, so a bare ``Path`` is unpacked and raises ``TypeError``. Passing string
+    paths avoids that for both the single-path and (cert, key) tuple forms.
+    """
+    if isinstance(cert, list | tuple):
+        return tuple(str(p) for p in cert)
+    return str(cert)
+
+
 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)
@@ -553,7 +590,7 @@ def create_test_class(scenario: Scenario, class_name: str, max_parallel_iteratio
         "http2": True,
     }
     if scenario.ssl.cert is not None:
-        client_kwargs["cert"] = resolved_ssl.cert
+        client_kwargs["cert"] = _normalize_cert(resolved_ssl.cert)
     if scenario.auth:
         resolved_auth = walk(scenario.auth, scenario_context)
         auth_result = call_user_function(resolved_auth)
@@ -580,7 +617,9 @@ def create_test_class(scenario: Scenario, class_name: str, max_parallel_iteratio
     padding_width = len(str(total_stages - 1)) if total_stages > 0 else 1
 
     for i, stage in enumerate(scenario.stages):
-
+        # Factory captures `stage` by value (as stage_template) per iteration. Do NOT
+        # inline this into a closure over the loop variable `stage`: Python closes over
+        # the variable, not its value, so every stage method would run the LAST stage.
         def make_stage_method(stage_template: Stage) -> Callable:
             def call_execute_stage(self, **kwargs):
                 type(self).execute_stage(stage_template, kwargs)
@@ -622,7 +661,7 @@ def create_test_class(scenario: Scenario, class_name: str, max_parallel_iteratio
                         stage_method = parametrize_marker(stage_method)
 
         all_fixtures = ["self"] + list(dict.fromkeys(all_param_names + stage.fixtures + scenario.fixtures))
-        stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures])  # type: ignore[assignment]
+        stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures])  # ty: ignore[unresolved-attribute]
 
         all_marks = [f"order({i})"] + stage.marks
         for mark_str in all_marks:

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/cli.py

@@ -1,14 +1,16 @@
 import enum
 import json
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated
+from typing import Annotated
 
 import typer
+from pydantic import ValidationError
+from pytest_httpchain_jsonref import ReferenceResolverError, load_json
+from pytest_httpchain_models import Scenario
 
-if TYPE_CHECKING:
-    from pytest_httpchain_models import Scenario
-
-    from pytest_httpchain.dataflow import DataFlow
+from pytest_httpchain.dataflow import DataFlow, analyze_dataflow
+from pytest_httpchain.schema import build_schema
+from pytest_httpchain.validation import ValidateResult, load_scenario, resolve_root_path, validate_scenario
 
 app = typer.Typer()
 
@@ -28,23 +30,6 @@ class GraphDirection(enum.StrEnum):
 RefParentTraversalDepth = Annotated[int, typer.Option(help="Maximum $ref parent directory traversal depth.")]
 
 
-def _emit(text: str, output: Path | None, label: str) -> None:
-    """Write text to a file (with a confirmation) or echo it to stdout.
-
-    A failed write reports a clean ``error: ...`` and exits non-zero, matching
-    the load-error handling elsewhere in this module instead of a raw traceback.
-    """
-    if output is None:
-        typer.echo(text)
-        return
-    try:
-        output.write_text(text + "\n")
-    except OSError as e:
-        typer.echo(f"error: cannot write {output}: {e}", err=True)
-        raise typer.Exit(1) from e
-    typer.echo(f"Wrote {label} to {output}")
-
-
 @app.callback()
 def main() -> None:
     """pytest-httpchain command-line tools."""
@@ -66,8 +51,6 @@ def validate(
     per file and exits non-zero if any file is invalid (or, with --strict, has any
     warnings).
     """
-    from pytest_httpchain.validation import ValidateResult, validate_scenario
-
     results = [
         (path, validate_scenario(path, ref_parent_traversal_depth=ref_parent_traversal_depth, root_path=root_path, deep=deep, syspaths=list(syspath or []))) for path in paths
     ]
@@ -99,28 +82,21 @@ def validate(
 
 
 @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
+def schema() -> None:
+    """Emit the JSON Schema for scenario files (editor autocomplete/validation).
 
-    text = json.dumps(build_schema(), indent=2, default=str)
-    _emit(text, output, "schema")
+    Writes to stdout; redirect to a file (``pytest-httpchain schema > scenario.schema.json``).
+    """
+    typer.echo(json.dumps(build_schema(), indent=2, default=str))
 
 
 @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: RefParentTraversalDepth = 3,
     root_path: Annotated[Path | None, typer.Option("--root-path", help="Directory that constrains $ref resolution (default: nearest tests/ ancestor).")] = None,
 ) -> None:
-    """Resolve $ref/$include/$merge and print the merged scenario JSON."""
-    from pytest_httpchain_jsonref import ReferenceResolverError, load_json
-
-    from pytest_httpchain.validation import resolve_root_path
-
+    """Resolve $ref/$include/$merge and print the merged scenario JSON to stdout."""
     try:
         data = load_json(
             scenario,
@@ -131,17 +107,11 @@ def resolve(
         typer.echo(f"error: {e}", err=True)
         raise typer.Exit(1) from e
 
-    text = json.dumps(data, indent=2, default=str)
-    _emit(text, output, "resolved scenario")
+    typer.echo(json.dumps(data, indent=2, default=str))
 
 
-def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None) -> tuple["Scenario", dict]:
+def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None) -> tuple[Scenario, dict]:
     """Load + validate a scenario for show/graph, mapping failures to Exit(1)."""
-    from pydantic import ValidationError
-    from pytest_httpchain_jsonref import ReferenceResolverError
-
-    from pytest_httpchain.validation import load_scenario
-
     try:
         return load_scenario(path, root_path=root_path, ref_parent_traversal_depth=depth)
     except (ReferenceResolverError, json.JSONDecodeError, OSError) as e:
@@ -152,7 +122,7 @@ def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None)
         raise typer.Exit(1) from None
 
 
-def _render_show_text(path: Path, scenario: "Scenario", flow: "DataFlow") -> list[str]:
+def _render_show_text(path: Path, scenario: Scenario, flow: DataFlow) -> list[str]:
     producer_of: dict[tuple[int, str], int] = {}
     for edge in flow.edges:
         for var_name in edge.vars:
@@ -196,8 +166,6 @@ def show(
     root_path: Annotated[Path | None, typer.Option("--root-path", help="Directory that constrains $ref resolution (default: nearest tests/ ancestor).")] = None,
 ) -> 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, root_path)
     flow = analyze_dataflow(sc, test_data)
 
@@ -214,7 +182,7 @@ def _mermaid_label(text: str) -> str:
     return text.replace('"', "'").replace("\n", " ")
 
 
-def _to_mermaid(flow: "DataFlow", direction: str = "TD") -> str:
+def _to_mermaid(flow: DataFlow, direction: str = "TD") -> str:
     lines = [f"flowchart {direction}"]
     if not flow.stages:
         lines.append("    %% (no stages)")
@@ -235,8 +203,6 @@ def graph(
     root_path: Annotated[Path | None, typer.Option("--root-path", help="Directory that constrains $ref resolution (default: nearest tests/ ancestor).")] = None,
 ) -> 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, root_path)
     flow = analyze_dataflow(sc, test_data)
     typer.echo(_to_mermaid(flow, direction.value))

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/dataflow.py

@@ -12,8 +12,8 @@ from pydantic import BaseModel
 from pytest_httpchain_models import Scenario
 
 from pytest_httpchain.validation import (
-    _parameter_names,
     extract_template_variables,
+    parameter_names,
     raw_stages,
     saved_in_stage,
     stage_defined_names,
@@ -90,7 +90,7 @@ def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
         # always_run resolves before stage substitutions exist, so only fixtures
         # and parametrize parameters shadow an earlier save there.
         always_run_refs = extract_template_variables(raw.get("always_run"))
-        always_run_local = set(stage.fixtures) | _parameter_names(stage.parametrize) | scenario_fixture_names
+        always_run_local = set(stage.fixtures) | parameter_names(stage.parametrize) | scenario_fixture_names
         consumes |= {name for name in always_run_refs if name in cumulative_saves and name not in always_run_local}
 
         by_producer: dict[int, list[str]] = {}

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/har_writer.py

@@ -4,8 +4,10 @@ This module converts httpx Request/Response objects to HAR 1.2 format
 and writes them to files for external analysis.
 """
 
+import base64
 import json
 from datetime import UTC, datetime
+from importlib.metadata import version
 from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qs, urlparse
@@ -16,14 +18,12 @@ 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]]:
+def _format_cookies(cookies: httpx.Cookies) -> list[dict[str, str]]:
     """Convert httpx Cookies to HAR cookie format."""
     result = []
     for name, value in cookies.items():
@@ -71,8 +71,6 @@ def _format_post_data(request: httpx.Request) -> dict[str, Any] | None:
     try:
         text = request.content.decode("utf-8")
     except UnicodeDecodeError:
-        import base64
-
         text = base64.b64encode(request.content).decode("ascii")
         return {
             "mimeType": mime_type,
@@ -106,8 +104,6 @@ def _format_response_content(response: httpx.Response) -> dict[str, Any]:
         try:
             content["text"] = response.content.decode("utf-8")
         except UnicodeDecodeError:
-            import base64
-
             content["text"] = base64.b64encode(response.content).decode("ascii")
             content["encoding"] = "base64"
 
@@ -118,7 +114,7 @@ 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
+        size += len(name) + len(value) + 4  # ": " (2) + CRLF (2) per header line
     return size
 
 
@@ -194,7 +190,7 @@ def request_response_to_har_entry(
 
     post_data = _format_post_data(request)
     if post_data:
-        entry["request"]["postData"] = post_data
+        entry["request"]["postData"] = post_data  # ty: ignore[invalid-assignment]
 
     return entry
 

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/plugin.py

@@ -7,16 +7,16 @@ scenarios into pytest:
   options (``suffix``, ``ref_parent_traversal_depth``, ``max_comprehension_length``,
   ``max_parallel_iterations``) and the ``--output-dir`` flag.
 - ``pytest_collect_file`` matches ``test_<name>.<suffix>.json`` files and hands
-  them to :class:`JsonModule`.
-- :class:`JsonModule.collect` loads the JSON (resolving ``$ref``), validates it
-  against the :class:`Scenario` model, runs the semantic validator
-  (warnings become :class:`ScenarioValidationWarning`, errors become
+  them to `JsonModule`.
+- `JsonModule.collect` loads the JSON (resolving ``$ref``), validates it
+  against the `Scenario` model, runs the semantic validator
+  (warnings become `ScenarioValidationWarning`, errors become
   ``CollectError``), and builds the dynamic test class via
   ``carrier.create_test_class``.
 - ``pytest_runtest_makereport`` attaches the last HTTP request/response to the
   test report and optionally writes a HAR file.
 
-:class:`ScenarioValidationWarning` is defined here because the collection hook
+`ScenarioValidationWarning` is defined here because the collection hook
 and the ``pytest11`` entry point reference it directly; it is re-exported from
 the package ``__init__`` as the user-facing name.
 """
@@ -165,26 +165,33 @@ def pytest_addoption(parser: pytest.Parser) -> None:
 
 
 def pytest_configure(config: pytest.Config) -> None:
-    # Numeric options are registered with type="int", so getini returns an int and a
-    # non-int value in the ini is reported by pytest as a clean usage error. Range
-    # checks below raise pytest.UsageError (not bare ValueError, which pytest renders
-    # as an INTERNALERROR with traceback).
+    # Numeric options are registered with type="int", but pytest performs the
+    # int() conversion with a bare int(value) that raises ValueError for a
+    # non-integer ini value — which pytest renders as an INTERNALERROR traceback.
+    # Wrap the read so a garbage value becomes a clean usage error; the range
+    # checks below likewise raise pytest.UsageError.
+    def _getint(name: str) -> int:
+        try:
+            return config.getini(name)
+        except ValueError as e:
+            raise pytest.UsageError(f"{name} must be an integer: {e}") from None
+
     suffix = str(config.getini(ConfigOptions.SUFFIX))
     if not re.match(r"^[a-zA-Z0-9_-]{1,32}$", suffix):
         raise pytest.UsageError("suffix must contain only alphanumeric characters, underscores, hyphens, and be ≤32 chars")
 
-    ref_parent_traversal_depth = config.getini(ConfigOptions.REF_PARENT_TRAVERSAL_DEPTH)
+    ref_parent_traversal_depth = _getint(ConfigOptions.REF_PARENT_TRAVERSAL_DEPTH)
     if ref_parent_traversal_depth < 0:
         raise pytest.UsageError("ref_parent_traversal_depth must be non-negative")
 
-    max_comprehension_length = config.getini(ConfigOptions.MAX_COMPREHENSION_LENGTH)
+    max_comprehension_length = _getint(ConfigOptions.MAX_COMPREHENSION_LENGTH)
     if max_comprehension_length < 1:
         raise pytest.UsageError("max_comprehension_length must be a positive integer")
     if max_comprehension_length > 1_000_000:
         raise pytest.UsageError("max_comprehension_length must not exceed 1,000,000")
     simpleeval.MAX_COMPREHENSION_LENGTH = max_comprehension_length  # ty: ignore[invalid-assignment]
 
-    max_parallel_iterations = config.getini(ConfigOptions.MAX_PARALLEL_ITERATIONS)
+    max_parallel_iterations = _getint(ConfigOptions.MAX_PARALLEL_ITERATIONS)
     if max_parallel_iterations < 1:
         raise pytest.UsageError("max_parallel_iterations must be a positive integer")
     if max_parallel_iterations > 1_000_000:

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/utils.py

@@ -86,7 +86,7 @@ def process_substitutions(
     return result
 
 
-def call_user_function(func_call: UserFunctionCall, **extra_kwargs) -> object:
+def call_user_function(func_call: UserFunctionCall, **extra_kwargs: Any) -> object:
     """Import and call a user function described by a ``UserFunctionCall`` model.
 
     A bare ``UserFunctionName`` is called with only ``extra_kwargs``; a

{pytest_httpchain-0.7.0 → pytest_httpchain-0.8.1}/src/pytest_httpchain/validation.py

@@ -6,7 +6,7 @@ pytest plugin, and available for editor/CI integrations. It performs structural
 validation via the Pydantic ``Scenario`` model plus cross-cutting *semantic*
 checks that a JSON Schema cannot express.
 
-Every finding is reported as a :class:`Diagnostic` carrying a stable code
+Every finding is reported as a `Diagnostic` carrying a stable code
 (``HTTPCHAINxxx``), a severity, a human-readable message and (where meaningful)
 a location, so tooling can filter/sort/route diagnostics deterministically.
 
@@ -32,6 +32,9 @@ Code     Severity Meaning
 014      error    Invalid JSON syntax
 015      error    Failed to parse JSON file
 016      error    Fixture referenced in a scenario-level template
+017      error    Scenario-level template references an undefined name
+018      warning  Verify expression is not a template (``{{ }}``) — asserts nothing
+019      error    Invalid pytest marker expression (scenario or stage ``marks``)
 020      warning  Referenced file does not exist (deep, opt-in)
 021      warning  Schema file is not valid JSON / not a valid schema (deep)
 022      warning  User function cannot be imported (deep)
@@ -45,8 +48,11 @@ runs at collection time. Deep findings are always warnings.
 """
 
 import ast
+import inspect
 import json
 import re
+import sys
+import warnings
 from pathlib import Path
 from typing import Any, Literal
 
@@ -55,16 +61,24 @@ from pytest_httpchain_jsonref import ReferenceResolverError, load_json
 from pytest_httpchain_models import (
     FunctionsSubstitution,
     JMESPathSave,
+    Parameters,
     SaveStep,
     Scenario,
     Stage,
     SubstitutionsSave,
+    UserFunctionCall,
+    UserFunctionKwargs,
+    UserFunctionName,
     UserFunctionsSave,
     VarsSubstitution,
     Verify,
     VerifyStep,
+    check_json_schema,
 )
-from pytest_httpchain_templates import TEMPLATE_BUILTINS, TEMPLATE_PATTERN
+from pytest_httpchain_templates import TEMPLATE_BUILTINS, TEMPLATE_PATTERN, is_complete_template
+from pytest_httpchain_userfunc import UserFunctionError, import_function
+
+from pytest_httpchain.utils import make_marker
 
 Severity = Literal["error", "warning"]
 
@@ -90,6 +104,8 @@ class DiagnosticCode:
     PARSE_ERROR = "HTTPCHAIN015"
     FIXTURE_IN_SCENARIO_TEMPLATE = "HTTPCHAIN016"
     SCENARIO_UNDEFINED_VAR = "HTTPCHAIN017"
+    NONTEMPLATE_EXPRESSION = "HTTPCHAIN018"
+    INVALID_MARKER = "HTTPCHAIN019"
     # Deep (opt-in) checks: imports, signatures, referenced files.
     REFERENCED_FILE_NOT_FOUND = "HTTPCHAIN020"
     SCHEMA_FILE_INVALID = "HTTPCHAIN021"
@@ -194,7 +210,7 @@ def extract_saved_variables(scenario: Scenario) -> set[str]:
     return saved_vars
 
 
-def _parameter_names(params: Any) -> set[str]:
+def parameter_names(params: Parameters | None) -> set[str]:
     """Names injected by a list of parametrize/foreach Parameter entries.
 
     Covers both ``individual`` (one name -> list of values) and ``combinations``
@@ -218,9 +234,9 @@ 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 |= _parameter_names(stage.parametrize)
+    names |= parameter_names(stage.parametrize)
     if stage.parallel is not None:
-        names |= _parameter_names(getattr(stage.parallel, "foreach", None))
+        names |= parameter_names(getattr(stage.parallel, "foreach", None))
     names |= set(stage.fixtures)
     return names
 
@@ -232,7 +248,7 @@ def extract_defined_variables(scenario: Scenario) -> set[str]:
     plus parameter names injected by ``parametrize`` and ``parallel.foreach``. This
     is the *union* across the whole scenario, used for the fixture-conflict check
     and informational output; the order-aware data-flow check
-    (:func:`_dataflow_diagnostics`) computes availability per stage instead.
+    (`_dataflow_diagnostics`) computes availability per stage instead.
     """
     defined_vars: set[str] = set()
 
@@ -240,9 +256,9 @@ def extract_defined_variables(scenario: Scenario) -> set[str]:
 
     for stage in scenario.stages:
         defined_vars |= substitution_names(stage.substitutions)
-        defined_vars |= _parameter_names(stage.parametrize)
+        defined_vars |= parameter_names(stage.parametrize)
         if stage.parallel is not None:
-            defined_vars |= _parameter_names(getattr(stage.parallel, "foreach", None))
+            defined_vars |= parameter_names(getattr(stage.parallel, "foreach", None))
 
     return defined_vars
 
@@ -300,9 +316,9 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any]) -> list
       processed and before any iteration runs: only fixtures, parametrize
       parameters, scenario substitutions and earlier saves are in scope.
 
-    A reference that is unavailable is reported as :data:`DiagnosticCode.FORWARD_REF`
+    A reference that is unavailable is reported as `DiagnosticCode.FORWARD_REF`
     if the name is saved somewhere later (an ordering bug) or
-    :data:`DiagnosticCode.UNDEFINED_VAR` otherwise (likely a typo).
+    `DiagnosticCode.UNDEFINED_VAR` otherwise (likely a typo).
     """
     diagnostics: list[Diagnostic] = []
 
@@ -322,6 +338,8 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any]) -> list
 
     scenario_available = scenario_scope | set(scenario.fixtures)
 
+    # raws[i] is the unvalidated dict for scenario.stages[i]: both come from the same
+    # order-preserving normalization (_normalize_stages_input), so they pair by index.
     raws = raw_stages(test_data)
     cumulative_saves: set[str] = set()
 
@@ -333,8 +351,8 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any]) -> list
         # parametrize parameters, scenario substitutions and earlier saves — but not
         # foreach parameters. The request/response are resolved per iteration, so
         # they additionally see the foreach parameters.
-        foreach_params = _parameter_names(getattr(stage.parallel, "foreach", None)) if stage.parallel is not None else set()
-        pre_iteration_available = scenario_available | set(stage.fixtures) | _parameter_names(stage.parametrize) | substitution_names(stage.substitutions) | cumulative_saves
+        foreach_params = parameter_names(getattr(stage.parallel, "foreach", None)) if stage.parallel is not None else set()
+        pre_iteration_available = scenario_available | set(stage.fixtures) | parameter_names(stage.parametrize) | substitution_names(stage.substitutions) | cumulative_saves
         request_available = pre_iteration_available | foreach_params
         response_available = request_available | saves_by_stage[i]
 
@@ -359,7 +377,7 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any]) -> list
         # ``always_run`` resolves at stage start (carrier.execute_stage) against
         # fixtures + parametrize parameters + global context — stage substitutions
         # and foreach parameters don't exist yet, and neither do this stage's saves.
-        always_run_available = scenario_available | set(stage.fixtures) | _parameter_names(stage.parametrize) | cumulative_saves
+        always_run_available = scenario_available | set(stage.fixtures) | parameter_names(stage.parametrize) | cumulative_saves
         for name in sorted(extract_template_variables(raw.get("always_run"))):
             if name in always_run_available:
                 continue
@@ -420,8 +438,8 @@ def _verify_diagnostics(scenario: Scenario) -> list[Diagnostic]:
     """Per-stage verify-step checks: missing validation, no-op verifies, and
     contradictory body ``contains``/``matches`` declarations.
 
-    Extracted from :func:`check_scenario` so each check family has its own
-    helper, mirroring :func:`_dataflow_diagnostics` and the deep-check helpers.
+    Extracted from `check_scenario` so each check family has its own
+    helper, mirroring `_dataflow_diagnostics` and the deep-check helpers.
     Behavior, codes and messages are unchanged.
     """
     diagnostics: list[Diagnostic] = []
@@ -453,6 +471,21 @@ def _verify_diagnostics(scenario: Scenario) -> list[Diagnostic]:
                     )
                 )
 
+            # A verify expression is meant to be a complete ``{{ }}`` template that
+            # evaluates to a truthy/falsy value. A plain string (e.g. a forgotten
+            # ``{{ }}``) is non-empty and therefore always truthy at runtime, so the
+            # assertion silently passes — it tests nothing.
+            for expr in verify.expressions:
+                if isinstance(expr, str) and not is_complete_template(expr):
+                    diagnostics.append(
+                        _diag(
+                            DiagnosticCode.NONTEMPLATE_EXPRESSION,
+                            "warning",
+                            f"Stage '{stage.name}': verify expression {expr!r} is not a template ({{{{ }}}}); it is always truthy and asserts nothing",
+                            location=location,
+                        )
+                    )
+
             # Overlap is compared on the raw (unrendered) strings: identical
             # entries — including identical templates — are caught. A contradiction
             # that only emerges after rendering (e.g. a template that resolves to a
@@ -483,6 +516,43 @@ def _verify_diagnostics(scenario: Scenario) -> list[Diagnostic]:
     return diagnostics
 
 
+def _marker_diagnostics(scenario: Scenario) -> list[Diagnostic]:
+    """Validate scenario- and stage-level pytest marker expressions.
+
+    Markers are parsed by ``make_marker`` only at collection time, so a malformed
+    marker (``skip(``) or an unsupported form (``foo.bar``) would pass ``validate``
+    yet crash collection. Run the same parser here so the validator catches it as
+    an error, keeping ``validate`` a faithful pre-flight check of what collection
+    will accept.
+    """
+    diagnostics: list[Diagnostic] = []
+
+    def _check(marks: list[str], location: str) -> None:
+        for mark in marks:
+            try:
+                # We only care whether the marker parses; constructing it would
+                # otherwise emit PytestUnknownMarkWarning for custom (unregistered)
+                # marks, which is noise during validation.
+                with warnings.catch_warnings():
+                    warnings.simplefilter("ignore")
+                    make_marker(mark)
+            except (ValueError, SyntaxError) as e:
+                diagnostics.append(
+                    _diag(
+                        DiagnosticCode.INVALID_MARKER,
+                        "error",
+                        f"Invalid marker {mark!r}: {e}",
+                        location=location,
+                    )
+                )
+
+    _check(scenario.marks, "marks")
+    for i, stage in enumerate(scenario.stages):
+        _check(stage.marks, f"stages[{i}].marks")
+
+    return diagnostics
+
+
 # --------------------------------------------------------------------------- #
 # Deep (opt-in) validation: imports, signatures, referenced files.
 # These touch the filesystem and import user code, so they NEVER run at
@@ -529,8 +599,6 @@ def _check_schema_path(schema: Any, location: str) -> list[Diagnostic]:
     except (OSError, json.JSONDecodeError) as e:
         return [_diag(DiagnosticCode.SCHEMA_FILE_INVALID, "warning", f"Schema file is not valid JSON: {path}: {e}", location)]
     try:
-        from pytest_httpchain_models import check_json_schema
-
         check_json_schema(data)
     except Exception as e:
         return [_diag(DiagnosticCode.SCHEMA_FILE_INVALID, "warning", f"Schema file is not a valid JSON Schema: {path}: {e}", location)]
@@ -559,18 +627,19 @@ def _file_diagnostics(scenario: Scenario) -> list[Diagnostic]:
     return diagnostics
 
 
-def _func_name_and_kwargs(call: Any) -> tuple[str | None, dict[str, Any] | None]:
+def _func_name_and_kwargs(call: UserFunctionCall) -> tuple[str | None, dict[str, Any] | None]:
     """Extract ``(import_name, explicit_kwargs)`` from a UserFunctionCall.
 
     ``kwargs`` is None for the bare ``UserFunctionName`` form (no explicit
-    keyword arguments)."""
-    root = getattr(call, "root", None)
-    if root is not None:  # UserFunctionName
-        return str(root), None
-    name_obj = getattr(call, "name", None)  # UserFunctionKwargs
-    if name_obj is not None:
-        return str(getattr(name_obj, "root", name_obj)), dict(getattr(call, "kwargs", {}) or {})
-    return None, None
+    keyword arguments). Mirrors the structural dispatch in ``carrier``/``utils`` so
+    a new union variant is caught by a class-name search."""
+    match call:
+        case UserFunctionName():
+            return str(call.root), None
+        case UserFunctionKwargs():
+            return str(call.name.root), dict(call.kwargs or {})
+        case _:
+            return None, None
 
 
 def _signature_problems(func: Any, provided: set[str]) -> list[tuple[str, str]]:
@@ -580,8 +649,6 @@ def _signature_problems(func: Any, provided: set[str]) -> list[tuple[str, str]]:
     kwargs plus framework-injected names such as ``response``). All arguments are
     passed by keyword at the call sites, so positional-only parameters are not
     considered fillable here. Returns ``(code, message)`` tuples."""
-    import inspect
-
     try:
         signature = inspect.signature(func)
     except (TypeError, ValueError):
@@ -608,8 +675,6 @@ def _signature_problems(func: Any, provided: set[str]) -> list[tuple[str, str]]:
 def _function_diagnostics(scenario: Scenario) -> list[Diagnostic]:
     """Resolve every literal user-function reference and (where the call
     arguments are statically known) check them against the signature."""
-    from pytest_httpchain_userfunc import UserFunctionError, import_function
-
     diagnostics: list[Diagnostic] = []
 
     # (call, injected-arg-names, check_signature, location). Substitution
@@ -669,8 +734,6 @@ def check_scenario_deep(scenario: Scenario, syspaths: list[Path] | None = None)
     ``validate --deep`` — never at collection time. ``syspaths`` (and the current
     working directory) are temporarily prepended to ``sys.path`` so user modules
     resolve the same way they would under pytest."""
-    import sys
-
     diagnostics = _file_diagnostics(scenario)
 
     saved_path = list(sys.path)
@@ -722,7 +785,7 @@ def check_scenario(scenario: Scenario, test_data: dict[str, Any]) -> tuple[list[
     """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
+    so it can be shared by `validate_scenario` (file-based) and by the pytest
     collector. Returns ``(diagnostics, scenario_info)``.
     """
     diagnostics: list[Diagnostic] = []
@@ -763,9 +826,9 @@ def check_scenario(scenario: Scenario, test_data: dict[str, Any]) -> tuple[list[
     var_conflicts: set[str] = set()
     for stage in scenario.stages:
         stage_fixtures = scenario_fixture_set | set(stage.fixtures)
-        stage_params = _parameter_names(stage.parametrize)
+        stage_params = parameter_names(stage.parametrize)
         if stage.parallel is not None:
-            stage_params |= _parameter_names(getattr(stage.parallel, "foreach", None))
+            stage_params |= parameter_names(getattr(stage.parallel, "foreach", None))
         stage_vars = scenario_sub_names | substitution_names(stage.substitutions) | stage_params
         var_conflicts |= stage_fixtures & stage_vars
     if var_conflicts:
@@ -829,6 +892,8 @@ def check_scenario(scenario: Scenario, test_data: dict[str, Any]) -> tuple[list[
 
     diagnostics.extend(_verify_diagnostics(scenario))
 
+    diagnostics.extend(_marker_diagnostics(scenario))
+
     scenario_info = ScenarioInfo(
         num_stages=len(scenario.stages),
         stage_names=stage_names,
@@ -857,12 +922,12 @@ def load_scenario(path: Path, *, root_path: Path | None = None, ref_parent_trave
 
     The single load+resolve+validate path shared by the CLI inspection commands
     (``show``/``graph``) and the data-flow loader. ``root_path`` constrains ``$ref``
-    resolution; when omitted it defaults to :func:`resolve_root_path` (the nearest
+    resolution; when omitted it defaults to `resolve_root_path` (the nearest
     ``tests/`` ancestor).
 
     NOTE on the root-path divergence: pytest collection (``plugin.py``) constrains
     ``$ref`` resolution to ``config.rootpath`` (the repo root), while every CLI path
-    defaults to :func:`resolve_root_path`. A ``$ref`` reaching above ``tests/`` but
+    defaults to `resolve_root_path`. A ``$ref`` reaching above ``tests/`` but
     inside the repo therefore resolves under collection yet may need an explicit
     ``--root-path`` to resolve the same way from the CLI. Raises
     ``ReferenceResolverError`` / ``json.JSONDecodeError`` / ``pydantic.ValidationError``
@@ -884,10 +949,10 @@ def validate_scenario(
     """Validate a pytest-httpchain test scenario file.
 
     Performs file/JSON/$ref/schema validation plus the semantic checks in
-    :func:`check_scenario`, returning a :class:`ValidateResult` whose
+    `check_scenario`, returning a `ValidateResult` whose
     ``diagnostics`` carry stable codes.
 
-    When ``deep`` is true, additionally runs :func:`check_scenario_deep`
+    When ``deep`` is true, additionally runs `check_scenario_deep`
     (referenced-file, import, and signature checks). This imports user modules,
     so it is opt-in; ``syspaths`` are added to ``sys.path`` for resolution.
     """
@@ -919,7 +984,14 @@ def validate_scenario(
             root_path=root_path,
         )
     except ReferenceResolverError as e:
-        diagnostics.append(_diag(DiagnosticCode.REF_ERROR, "error", f"JSON reference resolution error: {e}"))
+        # The resolver wraps a plain JSON syntax error as a ReferenceResolverError
+        # (chaining the JSONDecodeError as __cause__). Report those under the
+        # accurate "Invalid JSON syntax" code rather than the $ref-flavored one,
+        # which would mislead when no reference is involved.
+        if isinstance(e.__cause__, json.JSONDecodeError):
+            diagnostics.append(_diag(DiagnosticCode.INVALID_JSON, "error", f"Invalid JSON syntax: {e.__cause__}"))
+        else:
+            diagnostics.append(_diag(DiagnosticCode.REF_ERROR, "error", f"JSON reference resolution error: {e}"))
         return _result(diagnostics)
     except json.JSONDecodeError as e:
         diagnostics.append(_diag(DiagnosticCode.INVALID_JSON, "error", f"Invalid JSON syntax: {e}"))