pytest-httpchain 0.14.3__tar.gz → 0.15.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/PKG-INFO +19 -17
  2. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/README.md +17 -15
  3. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/pyproject.toml +3 -3
  4. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/pyproject.toml.orig +7 -4
  5. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/carrier.py +90 -45
  6. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/cli.py +19 -12
  7. pytest_httpchain-0.15.1/src/pytest_httpchain/constants.py +44 -0
  8. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/dataflow.py +6 -3
  9. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/errors.py +6 -0
  10. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/factory.py +16 -10
  11. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/har_writer.py +77 -50
  12. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/plumbing/circular.py +2 -3
  13. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/plumbing/path.py +1 -1
  14. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/plumbing/reference.py +13 -23
  15. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/models/__init__.py +2 -0
  16. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/models/entities.py +17 -7
  17. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/models/types.py +14 -7
  18. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/plugin.py +126 -117
  19. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/report_formatter.py +1 -1
  20. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/response_steps.py +13 -8
  21. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/schema.py +41 -26
  22. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/scoping.py +69 -24
  23. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/templates/substitution.py +22 -14
  24. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/userfunc.py +9 -15
  25. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/utils.py +39 -13
  26. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/validation/__init__.py +6 -3
  27. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/validation/deep.py +15 -19
  28. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/validation/diagnostics.py +44 -2
  29. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/validation/loader.py +67 -9
  30. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/validation/semantic.py +121 -64
  31. pytest_httpchain-0.15.1/src/pytest_httpchain/validation/validate.py +50 -0
  32. pytest_httpchain-0.14.3/src/pytest_httpchain/constants.py +0 -23
  33. pytest_httpchain-0.14.3/src/pytest_httpchain/validation/validate.py +0 -88
  34. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/LICENSE +0 -0
  35. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/__init__.py +0 -0
  36. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/__init__.py +0 -0
  37. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/exceptions.py +0 -0
  38. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/loader.py +0 -0
  39. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/jsonref/plumbing/__init__.py +0 -0
  40. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/py.typed +0 -0
  41. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/request_builder.py +0 -0
  42. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/templates/__init__.py +0 -0
  43. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/templates/exceptions.py +0 -0
  44. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/templates/expressions.py +0 -0
  45. {pytest_httpchain-0.14.3 → pytest_httpchain-0.15.1}/src/pytest_httpchain/warnings.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pytest-httpchain
3
- Version: 0.14.3
3
+ Version: 0.15.1
4
4
  Summary: pytest plugin for HTTP testing using JSON files
5
5
  Keywords: testing,pytest,httpx,http,api,integration-testing
6
6
  Author: Alexander Eresov
@@ -25,7 +25,7 @@ Requires-Dist: referencing>=0.28.4
25
25
  Requires-Dist: pyrate-limiter>=4.2.0
26
26
  Requires-Dist: pytest>=9.0
27
27
  Requires-Dist: simpleeval>=1.0.3
28
- Requires-Dist: typer>=0.16.0
28
+ Requires-Dist: typer>=0.26.0
29
29
  Requires-Python: >=3.13
30
30
  Project-URL: Repository, https://github.com/aeresov/pytest-httpchain
31
31
  Project-URL: Documentation, https://aeresov.github.io/pytest-httpchain/
@@ -64,9 +64,9 @@ Testing HTTP APIs with plain pytest often leads to these pain points:
64
64
 
65
65
  Test scenarios are JSON documents that describe _what_ to test, not _how_. No setup code to scroll through — the request and assertions are right there.
66
66
 
67
- ### `$ref` with deep merging
67
+ ### `$include` / `$merge` with deep merging
68
68
 
69
- Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type checking, so you can compose scenarios from shared fragments (auth flows, common headers, base URLs).
69
+ Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type checking, so you can compose scenarios from shared fragments (auth flows, common headers, base URLs). `$ref` is a legacy alias that still works, but prefer `$include`/`$merge`: VS Code gives `$ref` its own JSON Schema handling, which fights the editor integration below.
70
70
 
71
71
  ### Multi-stage execution
72
72
 
@@ -90,17 +90,6 @@ Markers, fixtures, parametrization, and other plugins work as expected. You're n
90
90
 
91
91
  Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix is `http`):
92
92
 
93
- ```python
94
- # conftest.py
95
- import pytest
96
- from datetime import datetime
97
-
98
-
99
- @pytest.fixture
100
- def now_utc():
101
- return datetime.now()
102
- ```
103
-
104
93
  ```json
105
94
  {
106
95
  "substitutions": [
@@ -163,6 +152,19 @@ def now_utc():
163
152
  }
164
153
  ```
165
154
 
155
+ The one stage above that needs Python is `update_user`, which asks for a `now_utc` fixture — ordinary pytest fixtures, resolved from your `conftest.py`:
156
+
157
+ ```python
158
+ # conftest.py
159
+ import pytest
160
+ from datetime import datetime
161
+
162
+
163
+ @pytest.fixture
164
+ def now_utc():
165
+ return datetime.now()
166
+ ```
167
+
166
168
  Scenario we created:
167
169
 
168
170
  - common data context is seeded with the first variable `user_id`
@@ -181,7 +183,7 @@ Scenario we created:
181
183
  finalizing call meant for graceful exit
182
184
  `always_run` parameter means this stage will be executed regardless of errors in previous stages
183
185
 
184
- For detailed usage guide see the [full documentation](https://aeresov.github.io/pytest-httpchain).
186
+ For detailed usage guide see the [full documentation](https://aeresov.github.io/pytest-httpchain), and the [CLI reference](https://aeresov.github.io/pytest-httpchain/cli/) for the offline authoring commands.
185
187
 
186
188
  ## Installation
187
189
 
@@ -201,7 +203,7 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
201
203
 
202
204
  - Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.
203
205
  The suffix is configurable via the `httpchain_suffix` pytest ini option, default value is **http**.
204
- - `$ref` instructions can point to other files using relative paths; absolute paths are rejected for security, and every reference must resolve inside the root path (pytest's `rootdir` when collecting; `--root-path` for the CLI).
206
+ - `$include`/`$merge` instructions (and their legacy alias `$ref`) can point to other files using relative paths; absolute paths are rejected for security, and every reference must resolve inside the root path (pytest's `rootdir` when collecting; `--root-path` for the CLI).
205
207
  You can limit the depth of relative path traversal using the `httpchain_ref_parent_traversal_depth` ini option, default value is **3**.
206
208
  - Template expressions support list/dict comprehensions. You can limit the maximum comprehension length using the `httpchain_max_comprehension_length` ini option, default value is **50000**.
207
209
  - Parallel stage iterations (repeat/foreach) have a safety limit configurable via the `httpchain_max_parallel_iterations` ini option, default value is **10000**.
@@ -30,9 +30,9 @@ Testing HTTP APIs with plain pytest often leads to these pain points:
30
30
 
31
31
  Test scenarios are JSON documents that describe _what_ to test, not _how_. No setup code to scroll through — the request and assertions are right there.
32
32
 
33
- ### `$ref` with deep merging
33
+ ### `$include` / `$merge` with deep merging
34
34
 
35
- Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type checking, so you can compose scenarios from shared fragments (auth flows, common headers, base URLs).
35
+ Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type checking, so you can compose scenarios from shared fragments (auth flows, common headers, base URLs). `$ref` is a legacy alias that still works, but prefer `$include`/`$merge`: VS Code gives `$ref` its own JSON Schema handling, which fights the editor integration below.
36
36
 
37
37
  ### Multi-stage execution
38
38
 
@@ -56,17 +56,6 @@ Markers, fixtures, parametrization, and other plugins work as expected. You're n
56
56
 
57
57
  Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix is `http`):
58
58
 
59
- ```python
60
- # conftest.py
61
- import pytest
62
- from datetime import datetime
63
-
64
-
65
- @pytest.fixture
66
- def now_utc():
67
- return datetime.now()
68
- ```
69
-
70
59
  ```json
71
60
  {
72
61
  "substitutions": [
@@ -129,6 +118,19 @@ def now_utc():
129
118
  }
130
119
  ```
131
120
 
121
+ The one stage above that needs Python is `update_user`, which asks for a `now_utc` fixture — ordinary pytest fixtures, resolved from your `conftest.py`:
122
+
123
+ ```python
124
+ # conftest.py
125
+ import pytest
126
+ from datetime import datetime
127
+
128
+
129
+ @pytest.fixture
130
+ def now_utc():
131
+ return datetime.now()
132
+ ```
133
+
132
134
  Scenario we created:
133
135
 
134
136
  - common data context is seeded with the first variable `user_id`
@@ -147,7 +149,7 @@ Scenario we created:
147
149
  finalizing call meant for graceful exit
148
150
  `always_run` parameter means this stage will be executed regardless of errors in previous stages
149
151
 
150
- For detailed usage guide see the [full documentation](https://aeresov.github.io/pytest-httpchain).
152
+ For detailed usage guide see the [full documentation](https://aeresov.github.io/pytest-httpchain), and the [CLI reference](https://aeresov.github.io/pytest-httpchain/cli/) for the offline authoring commands.
151
153
 
152
154
  ## Installation
153
155
 
@@ -167,7 +169,7 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
167
169
 
168
170
  - Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.
169
171
  The suffix is configurable via the `httpchain_suffix` pytest ini option, default value is **http**.
170
- - `$ref` instructions can point to other files using relative paths; absolute paths are rejected for security, and every reference must resolve inside the root path (pytest's `rootdir` when collecting; `--root-path` for the CLI).
172
+ - `$include`/`$merge` instructions (and their legacy alias `$ref`) can point to other files using relative paths; absolute paths are rejected for security, and every reference must resolve inside the root path (pytest's `rootdir` when collecting; `--root-path` for the CLI).
171
173
  You can limit the depth of relative path traversal using the `httpchain_ref_parent_traversal_depth` ini option, default value is **3**.
172
174
  - Template expressions support list/dict comprehensions. You can limit the maximum comprehension length using the `httpchain_max_comprehension_length` ini option, default value is **50000**.
173
175
  - Parallel stage iterations (repeat/foreach) have a safety limit configurable via the `httpchain_max_parallel_iterations` ini option, default value is **10000**.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytest-httpchain"
3
- version = "0.14.3"
3
+ version = "0.15.1"
4
4
  description = "pytest plugin for HTTP testing using JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
@@ -15,7 +15,7 @@ dependencies = [
15
15
  "pyrate-limiter>=4.2.0",
16
16
  "pytest>=9.0",
17
17
  "simpleeval>=1.0.3",
18
- "typer>=0.16.0",
18
+ "typer>=0.26.0",
19
19
  ]
20
20
  keywords = [
21
21
  "testing",
@@ -152,7 +152,7 @@ patch = ["subprocess"]
152
152
  precision = 2
153
153
  show_missing = true
154
154
  skip_covered = false
155
- fail_under = 88
155
+ fail_under = 96
156
156
 
157
157
  [tool.importlinter]
158
158
  root_package = "pytest_httpchain"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytest-httpchain"
3
- version = "0.14.3"
3
+ version = "0.15.1"
4
4
  description = "pytest plugin for HTTP testing using JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
@@ -16,7 +16,10 @@ dependencies = [
16
16
  "pyrate-limiter>=4.2.0",
17
17
  "pytest>=9.0",
18
18
  "simpleeval>=1.0.3",
19
- "typer>=0.16.0",
19
+ # 0.26.0 is the first release that stopped importing the deprecated
20
+ # `click.utils.get_binary_stream`; with `filterwarnings = error` any older
21
+ # typer fails collection against current click.
22
+ "typer>=0.26.0",
20
23
  ]
21
24
  keywords = ["testing", "pytest", "httpx", "http", "api", "integration-testing"]
22
25
  license = "MIT"
@@ -168,10 +171,10 @@ precision = 2
168
171
  show_missing = true
169
172
  skip_covered = false
170
173
  # Regression floor for the CI `coverage report` step (full suite under
171
- # `coverage run -m pytest`, ~95%). Kept a few points below the real number to
174
+ # `coverage run -m pytest`, ~98%). Kept a few points below the real number to
172
175
  # tolerate platform/Python-version branch differences; ratchet upward as
173
176
  # coverage improves rather than letting it silently erode.
174
- fail_under = 88
177
+ fail_under = 96
175
178
 
176
179
  [tool.importlinter]
177
180
  root_package = "pytest_httpchain"
@@ -34,6 +34,7 @@ from pydantic import ValidationError
34
34
  from pyrate_limiter import Duration, Limiter, Rate
35
35
 
36
36
  from pytest_httpchain.errors import RequestError, SaveError, StageExecutionError
37
+ from pytest_httpchain.har_writer import Exchange
37
38
  from pytest_httpchain.models import (
38
39
  CombinationsParameter,
39
40
  IndividualParameter,
@@ -58,7 +59,7 @@ from pytest_httpchain.scoping import (
58
59
  with_stage_substitutions,
59
60
  )
60
61
  from pytest_httpchain.templates import TemplatesError, walk
61
- from pytest_httpchain.utils import make_marker, process_substitutions
62
+ from pytest_httpchain.utils import process_substitutions
62
63
  from pytest_httpchain.warnings import ScenarioValidationWarning
63
64
 
64
65
  logger = logging.getLogger(__name__)
@@ -87,22 +88,6 @@ def _response_meta(response: httpx.Response) -> SimpleNamespace:
87
88
  )
88
89
 
89
90
 
90
- def _is_active_xfail(mark: pytest.MarkDecorator) -> bool:
91
- """True when the mark is an xfail that will actually apply to the item.
92
-
93
- Mirrors pytest's ``evaluate_xfail_marks``: no conditions means unconditional,
94
- otherwise any truthy one activates it. An inactive xfail means pytest counts
95
- the failure as genuine, so the abort machinery must too; string conditions
96
- (which pytest evaluates itself) are conservatively treated as active.
97
- """
98
- if mark.name != "xfail":
99
- return False
100
- conditions = (mark.kwargs["condition"],) if "condition" in mark.kwargs else mark.args
101
- if not conditions:
102
- return True
103
- return any(isinstance(condition, str) or bool(condition) for condition in conditions)
104
-
105
-
106
91
  def _error_request(e: Exception) -> httpx.Request | None:
107
92
  """The request an httpx error was raised for, if it recorded one.
108
93
 
@@ -116,6 +101,47 @@ def _error_request(e: Exception) -> httpx.Request | None:
116
101
  return request if isinstance(request, httpx.Request) else None
117
102
 
118
103
 
104
+ def _parallel_number(field: str, value: Any) -> float:
105
+ """A walk()-resolved ``parallel`` setting as a float, or a stage failure.
106
+
107
+ The numeric fields are `PositiveInt | NumberOrTemplate` and walk() re-validates
108
+ the config it resolves, but NumberOrTemplate accepts any complete template:
109
+ a template resolving to another template string satisfies it and arrives here
110
+ as text. A bare ``float()``/``int()`` would raise ValueError, which is not a
111
+ stage failure and so escapes as a plugin traceback.
112
+ """
113
+ if isinstance(value, bool):
114
+ # float(True) is 1.0, so without this a resolved bool would silently
115
+ # configure one worker / one call per second.
116
+ raise StageExecutionError(f"parallel.{field} must be a positive number, got {value!r}")
117
+ try:
118
+ number = float(value)
119
+ except (TypeError, ValueError, ArithmeticError):
120
+ raise StageExecutionError(f"parallel.{field} must be a positive number, got {value!r}") from None
121
+ if not math.isfinite(number) or number <= 0:
122
+ raise StageExecutionError(f"parallel.{field} must be a positive number, got {value!r}")
123
+ return number
124
+
125
+
126
+ def _parallel_int(field: str, value: Any) -> int:
127
+ """`_parallel_number` for a whole-number setting. Truncating instead would
128
+ turn a resolved 0.5 into 0 — no workers, or a silently disabled limiter.
129
+
130
+ An int is taken as it stands: `PositiveInt` has no upper bound, and routing
131
+ one through ``float()`` would raise OverflowError on a value the callers
132
+ handle perfectly well (``max_concurrency`` clamps against the iteration
133
+ count, and pyrate_limiter accepts any int rate).
134
+ """
135
+ if isinstance(value, int) and not isinstance(value, bool):
136
+ if value <= 0:
137
+ raise StageExecutionError(f"parallel.{field} must be a positive whole number, got {value!r}")
138
+ return value
139
+ number = _parallel_number(field, value)
140
+ if not number.is_integer():
141
+ raise StageExecutionError(f"parallel.{field} must be a positive whole number, got {value!r}")
142
+ return int(number)
143
+
144
+
119
145
  def fresh_scenario_state() -> dict[str, Any]:
120
146
  """The per-scenario mutable class state, in its pristine form.
121
147
 
@@ -161,7 +187,7 @@ class Carrier:
161
187
  aborted: ClassVar[bool] = False
162
188
  last_request: ClassVar[httpx.Request | None] = None
163
189
  last_response: ClassVar[httpx.Response | None] = None
164
- last_exchanges: ClassVar[list[tuple[httpx.Request, httpx.Response | None, datetime | None]]] = []
190
+ last_exchanges: ClassVar[list[Exchange]] = []
165
191
  last_iterations_attempted: ClassVar[int] = 0
166
192
  last_shown_exchange_is_failed: ClassVar[bool] = False
167
193
  record_all_exchanges: ClassVar[bool] = False
@@ -203,9 +229,20 @@ class Carrier:
203
229
  @classmethod
204
230
  def _resolve_always_run(cls, stage: Stage, stage_fixtures: dict[str, Any]) -> bool:
205
231
  """Resolve ``always_run``, evaluating a template form against the
206
- stage-start context (stage substitutions do not exist yet)."""
232
+ stage-start context (stage substitutions do not exist yet).
233
+
234
+ Only a template form still missing its context initializes, and it must:
235
+ the scenario substitutions it is promised (see `scoping`'s scope table)
236
+ exist only once the context is built, and an abort raised before any stage
237
+ body ran — a fixture error in stage one — leaves it empty otherwise. A
238
+ static bool reads no context, and a collection-resolved context is already
239
+ populated; initializing for either would run auth and allocate the client
240
+ for a stage about to skip.
241
+ """
207
242
  if isinstance(stage.always_run, bool):
208
243
  return stage.always_run
244
+ if not cls._context_resolved_at_collection:
245
+ cls._ensure_initialized()
209
246
  try:
210
247
  return bool(walk(stage.always_run, stage_start_context(cls.global_context, stage_fixtures)))
211
248
  except TemplatesError as e:
@@ -218,8 +255,10 @@ class Carrier:
218
255
  Gates on the abort/``always_run`` flow, layers the stage context, runs
219
256
  the iteration matrix, and on full success commits the collected saves as
220
257
  a new global-context layer. A failure is reported via ``pytest.fail``
221
- and aborts the chain unless the stage is marked xfail; a failing stage
222
- commits no saves, so the context never carries a timing-dependent subset.
258
+ and commits no saves, so the context never carries a timing-dependent
259
+ subset. The report hook owns chain-abort classification because only
260
+ pytest's final report knows whether xfail/strict and setup/teardown made
261
+ the item a genuine failure.
223
262
  """
224
263
  # Reset before anything can fail or skip: a stage that never records an
225
264
  # exchange must report nothing, not the previous stage's.
@@ -283,13 +322,6 @@ class Carrier:
283
322
  raise exc
284
323
 
285
324
  except _STAGE_FAILURE_EXCEPTIONS as e:
286
- # Structural detection, so `skip(reason="...xfail...")` or a custom
287
- # `my_xfail` marker is not misclassified. An xfail stage's failure is
288
- # expected and must not abort the chain.
289
- is_xfail = any(_is_active_xfail(make_marker(mark)) for mark in stage.marks)
290
- if not is_xfail:
291
- logger.error(str(e))
292
- cls.aborted = True
293
325
  failure_reason = str(e)
294
326
 
295
327
  # Deliberately outside the handler: raising there would set
@@ -307,7 +339,7 @@ class Carrier:
307
339
  return {name: cls._wrap_factory_fixture(value) if callable(value) and not inspect.isclass(value) else value for name, value in fixture_kwargs.items()}
308
340
 
309
341
  @staticmethod
310
- def _build_iteration_substitutions(parallel_config: "ParallelConfig | None", max_parallel_iterations: int) -> list[dict[str, Any]]:
342
+ def _build_iteration_substitutions(parallel_config: ParallelConfig | None, max_parallel_iterations: int) -> list[dict[str, Any]]:
311
343
  """Expand a resolved parallel config into per-iteration substitutions:
312
344
  no config -> one empty dict; ``repeat`` -> N empties; ``foreach`` -> the
313
345
  cross-product of its steps.
@@ -331,7 +363,7 @@ class Carrier:
331
363
  case ParallelRepeatConfig(repeat=repeat_count):
332
364
  # int(): the field is `PositiveInt | NumberOrTemplate`, but the
333
365
  # config arrives walk()-resolved.
334
- repeat_total = int(repeat_count)
366
+ repeat_total = _parallel_int("repeat", repeat_count)
335
367
  check_cap(repeat_total)
336
368
  iteration_substitutions = [{} for _ in range(repeat_total)]
337
369
  case ParallelForeachConfig(foreach=foreach_steps):
@@ -360,7 +392,7 @@ class Carrier:
360
392
  return iteration_substitutions
361
393
 
362
394
  @classmethod
363
- def _record_exchanges(cls, completed: list["IterationResult"], failed: Exception | None, attempted: int) -> None:
395
+ def _record_exchanges(cls, completed: list[IterationResult], failed: Exception | None, attempted: int) -> None:
364
396
  """Record this stage's HTTP exchanges for the report and the HAR file.
365
397
 
366
398
  ``last_request``/``last_response`` are the one exchange the report shows:
@@ -371,7 +403,7 @@ class Carrier:
371
403
  """
372
404
  failed_request, failed_response, failed_started = (failed.request, failed.response, failed.started) if isinstance(failed, StageExecutionError) else (None, None, None)
373
405
 
374
- exchanges: list[tuple[httpx.Request, httpx.Response | None, datetime | None]] = []
406
+ exchanges: list[Exchange] = []
375
407
  for r in completed:
376
408
  # A redirect chain lives on .history, each hop carrying its own
377
409
  # request: expand it so the HAR shows every wire exchange. Individual
@@ -393,7 +425,7 @@ class Carrier:
393
425
  cls.last_request, cls.last_response = failed_request, failed_response
394
426
  cls.last_shown_exchange_is_failed = True
395
427
  elif exchanges:
396
- cls.last_request, cls.last_response = exchanges[-1][0], exchanges[-1][1]
428
+ cls.last_request, cls.last_response, _ = exchanges[-1]
397
429
 
398
430
  @classmethod
399
431
  def _run_iterations(
@@ -401,7 +433,7 @@ class Carrier:
401
433
  stage: Stage,
402
434
  local_context: ChainMap[str, Any],
403
435
  iteration_substitutions: list[dict[str, Any]],
404
- parallel_config: "ParallelConfig | None",
436
+ parallel_config: ParallelConfig | None,
405
437
  ) -> tuple[list[IterationResult | None], tuple[int, Exception] | None]:
406
438
  """Run the iterations and return ``(results_by_index, first_error)``.
407
439
 
@@ -409,25 +441,31 @@ class Carrier:
409
441
  ``max_concurrency`` with an optional global rate limiter. The first
410
442
  expected failure cancels the pool.
411
443
  """
412
- # The numeric fields are `PositiveInt | NumberOrTemplate`, but the config
413
- # arrives walk()-resolved.
414
- max_concurrency = int(parallel_config.max_concurrency) if parallel_config else 1
415
- calls_per_sec = int(parallel_config.calls_per_sec) if parallel_config and parallel_config.calls_per_sec else None
416
- max_rate_limit_delay = float(parallel_config.max_rate_limit_delay) if parallel_config else 60.0
417
-
418
444
  total = len(iteration_substitutions)
419
445
  results: list[IterationResult | None] = [None] * total
420
446
  first_error: tuple[int, Exception] | None = None
421
- # A single iteration cannot block on a fresh bucket, so it needs no limiter.
422
- limiter = Limiter(Rate(calls_per_sec, Duration.SECOND)) if calls_per_sec and total > 1 else None
447
+ limiter: Limiter | None = None
423
448
 
424
449
  try:
425
450
  if total == 1:
451
+ # No limiter and no delay budget: a single iteration cannot block
452
+ # on a fresh bucket, so the pool's rate-limiting arguments have
453
+ # nothing to do here.
426
454
  try:
427
- results[0] = cls._execute_single_iteration(stage, local_context, iteration_substitutions[0], limiter, max_rate_limit_delay)
455
+ results[0] = cls._execute_single_iteration(stage, local_context, iteration_substitutions[0])
428
456
  except _STAGE_FAILURE_EXCEPTIONS as e:
429
457
  first_error = (0, e)
430
458
  else:
459
+ # Only a parallel config can yield more than one iteration:
460
+ # `_build_iteration_substitutions(None, ...)` returns exactly one.
461
+ assert parallel_config is not None, "more than one iteration implies a parallel config"
462
+ # Guarded rather than cast: the config arrives walk()-resolved,
463
+ # and a resolved value can still be unusable (see `_parallel_number`).
464
+ max_concurrency = _parallel_int("max_concurrency", parallel_config.max_concurrency)
465
+ calls_per_sec = _parallel_int("calls_per_sec", parallel_config.calls_per_sec) if parallel_config.calls_per_sec is not None else None
466
+ max_rate_limit_delay = _parallel_number("max_rate_limit_delay", parallel_config.max_rate_limit_delay)
467
+ limiter = Limiter(Rate(calls_per_sec, Duration.SECOND)) if calls_per_sec is not None else None
468
+
431
469
  workers = min(max_concurrency, total)
432
470
  cancel = threading.Event()
433
471
  futures: dict[Future[IterationResult], int] = {}
@@ -497,7 +535,14 @@ class Carrier:
497
535
  def _acquire_rate_slot(limiter: Limiter, timeout: float, cancel: threading.Event | None) -> bool:
498
536
  """Poll for a rate-limit slot so a pool-wide cancellation interrupts the
499
537
  wait; a blocking ``try_acquire`` would pin the thread (and delay the
500
- stage's failure report) for up to the full timeout."""
538
+ stage's failure report) for up to the full timeout.
539
+
540
+ The 50ms interval is a cancellation-latency budget, NOT a throughput
541
+ knob: pyrate_limiter's bucket is a sliding-window log, so a whole
542
+ window's budget frees at once and one wake admits many calls. Deriving
543
+ it from ``calls_per_sec`` was measured to change achieved throughput by
544
+ under 2% while tripling CPU burnt in this loop.
545
+ """
501
546
  deadline = time.monotonic() + timeout
502
547
  while True:
503
548
  if limiter.try_acquire("api", blocking=False):
@@ -640,7 +685,7 @@ class Carrier:
640
685
  try:
641
686
  ctx.__exit__(None, None, None)
642
687
  except Exception as e:
643
- logger.error(f"Error while cleaning up context manager fixture: {e}")
688
+ logger.error("Error while cleaning up context manager fixture: %s", e)
644
689
 
645
690
  if cls.client is not None:
646
691
  cls.client.close()
@@ -1,6 +1,9 @@
1
- import enum
1
+ """The ``pytest-httpchain`` command line: ``validate``, ``schema``, ``resolve``,
2
+ ``show`` and ``graph`` over scenario files, outside a pytest run."""
3
+
2
4
  import importlib.metadata
3
5
  import json
6
+ from enum import StrEnum
4
7
  from pathlib import Path
5
8
  from typing import Annotated
6
9
 
@@ -16,12 +19,12 @@ from pytest_httpchain.validation import ValidateResult, is_inline_schema_positio
16
19
  app = typer.Typer(no_args_is_help=True)
17
20
 
18
21
 
19
- class OutputFormat(enum.StrEnum):
22
+ class OutputFormat(StrEnum):
20
23
  text = "text"
21
24
  json = "json"
22
25
 
23
26
 
24
- class GraphDirection(enum.StrEnum):
27
+ class GraphDirection(StrEnum):
25
28
  TD = "TD"
26
29
  LR = "LR"
27
30
 
@@ -91,7 +94,12 @@ def validate(
91
94
  status = "OK"
92
95
  typer.echo(f"{path}: {status}")
93
96
  for diagnostic in result.diagnostics:
94
- at = f" (at {diagnostic.location})" if diagnostic.location else ""
97
+ # Some diagnostics already name the location inside the
98
+ # message; repeating it makes the suffix look untrustworthy
99
+ # everywhere else. The field itself stays — it is the
100
+ # machine-readable form of what the message spells out in prose,
101
+ # so a JSON consumer can route on it without parsing English.
102
+ at = f" (at {diagnostic.location})" if diagnostic.location and diagnostic.location not in diagnostic.message else ""
95
103
  typer.echo(f" {diagnostic.severity} [{diagnostic.code}]: {diagnostic.message}{at}")
96
104
 
97
105
  raise typer.Exit(0 if all_passed else 1)
@@ -151,9 +159,9 @@ def _render_show_text(path: Path, scenario: Scenario, flow: DataFlow) -> list[st
151
159
  lines: list[str] = [scenario.description or path.name]
152
160
  summary = f"{len(flow.stages)} stage(s)"
153
161
  if all_fixtures:
154
- summary += f" · fixtures: {all_fixtures}"
162
+ summary += f" · fixtures: {', '.join(all_fixtures)}"
155
163
  if flow.scenario_vars:
156
- summary += f" · vars: {flow.scenario_vars}"
164
+ summary += f" · vars: {', '.join(flow.scenario_vars)}"
157
165
  lines.append(summary)
158
166
  lines.append("")
159
167
 
@@ -165,12 +173,11 @@ def _render_show_text(path: Path, scenario: Scenario, flow: DataFlow) -> list[st
165
173
  if s.consumes:
166
174
  parts: list[str] = []
167
175
  for var_name in s.consumes:
168
- producer = producer_of.get((s.index, var_name))
169
- if producer is None:
170
- parts.append(var_name)
171
- else:
172
- producer_name = flow.stages[producer].name or f"stage {producer + 1}"
173
- parts.append(f"{var_name} (from #{producer + 1} {producer_name})")
176
+ # analyze_dataflow lists a consume only when an earlier stage
177
+ # saved the name, so every one has a producing edge.
178
+ producer = producer_of[(s.index, var_name)]
179
+ producer_name = flow.stages[producer].name or f"stage {producer + 1}"
180
+ parts.append(f"{var_name} (from #{producer + 1} {producer_name})")
174
181
  lines.append(f" consumes: {', '.join(parts)}")
175
182
  if s.marks:
176
183
  lines.append(f" marks: {', '.join(s.marks)}")
@@ -0,0 +1,44 @@
1
+ """Ini option names and the user-function name grammar."""
2
+
3
+ import re
4
+ from enum import StrEnum
5
+
6
+ # "module.path:function_name": a required dotted module path (no leading,
7
+ # trailing or doubled dots) and a single identifier. Shared by the models'
8
+ # validator and the importer, so a bare name fails at validation, not at import.
9
+ # Anchored with \A and \Z, not ^ and $: "$" also matches just before a trailing
10
+ # "\n", so match() against "^...$" accepted "mod:func\n". The pattern is exported
11
+ # as userfunc.NAME_PATTERN, so match() has to be as strict as fullmatch() here.
12
+ USER_FUNCTION_NAME_PATTERN = re.compile(r"\A(?P<module>[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*):(?P<function>[a-zA-Z_][a-zA-Z0-9_]*)\Z")
13
+
14
+ _BARE_NAME_PATTERN = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*")
15
+
16
+
17
+ def parse_user_function_name(name: str) -> tuple[str, str]:
18
+ """Split ``module.path:function_name`` into ``(module_path, function_name)``,
19
+ raising ``ValueError`` that says what is wrong with an unusable name.
20
+
21
+ The wording is shared, not just the grammar: the models' validator surfaces
22
+ it as a validation error and the importer as a ``UserFunctionError``, and one
23
+ mistake must not be described to the author in two different ways.
24
+ """
25
+ if match := USER_FUNCTION_NAME_PATTERN.fullmatch(name):
26
+ return match["module"], match["function"]
27
+ # The most common mistake deserves an actionable hint.
28
+ if _BARE_NAME_PATTERN.fullmatch(name):
29
+ raise ValueError(f"Module path is required: use 'module:{name}' format instead of '{name}'")
30
+ raise ValueError(f"Invalid function name format: {name}")
31
+
32
+
33
+ class ConfigOptions(StrEnum):
34
+ """Ini option names, settable in pytest.ini or [tool.pytest.ini_options].
35
+
36
+ The ``httpchain_`` prefix is required: pytest ini options share one global
37
+ namespace across plugins. Defaults live in ``plugin.pytest_addoption``; the
38
+ HAR output directory is a CLI flag, not an ini option.
39
+ """
40
+
41
+ SUFFIX = "httpchain_suffix"
42
+ REF_PARENT_TRAVERSAL_DEPTH = "httpchain_ref_parent_traversal_depth"
43
+ MAX_COMPREHENSION_LENGTH = "httpchain_max_comprehension_length"
44
+ MAX_PARALLEL_ITERATIONS = "httpchain_max_parallel_iterations"
@@ -127,6 +127,9 @@ def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
127
127
  for name in scope.saves:
128
128
  last_save_stage[name] = i
129
129
 
130
- scenario_var_names = set(substitution_names(scenario.substitutions))
131
-
132
- return DataFlow(stages=stages, edges=edges, scenario_fixtures=sorted(scenario.fixtures), scenario_vars=sorted(scenario_var_names))
130
+ return DataFlow(
131
+ stages=stages,
132
+ edges=edges,
133
+ scenario_fixtures=sorted(scenario.fixtures),
134
+ scenario_vars=sorted(substitution_names(scenario.substitutions)),
135
+ )
@@ -7,6 +7,12 @@ class HttpChainError(Exception):
7
7
  """Base exception for all pytest-httpchain errors."""
8
8
 
9
9
 
10
+ class SchemaFileError(HttpChainError):
11
+ """A referenced JSON Schema file could not be read or parsed. Raised by
12
+ ``utils.read_json_schema_file`` so the validator and the runtime can word
13
+ the failure their own way without re-deriving what counts as one."""
14
+
15
+
10
16
  class StageExecutionError(HttpChainError):
11
17
  """A stage failed. Carries the HTTP request/response when one was made, for
12
18
  the failure report and the HAR file; ``started`` is when the request went on
@@ -23,6 +23,20 @@ from pytest_httpchain.templates import walk
23
23
  from pytest_httpchain.utils import make_marker, process_substitutions
24
24
 
25
25
 
26
+ def _make_stage_method(stage_template: Stage) -> Callable:
27
+ """Build one stage's test method.
28
+
29
+ The stage arrives as an argument, not captured from the caller's loop
30
+ variable: a closure over that variable would make every method run the LAST
31
+ stage.
32
+ """
33
+
34
+ def call_execute_stage(self, **kwargs):
35
+ type(self).execute_stage(stage_template, kwargs)
36
+
37
+ return call_execute_stage
38
+
39
+
26
40
  def create_test_class(
27
41
  scenario: Scenario,
28
42
  class_name: str,
@@ -62,15 +76,7 @@ def create_test_class(
62
76
  padding_width = len(str(total_stages - 1)) if total_stages > 0 else 1
63
77
 
64
78
  for i, stage in enumerate(scenario.stages):
65
- # Captures `stage` by value: a closure over the loop variable would make
66
- # every method run the LAST stage.
67
- def make_stage_method(stage_template: Stage) -> Callable:
68
- def call_execute_stage(self, **kwargs):
69
- type(self).execute_stage(stage_template, kwargs)
70
-
71
- return call_execute_stage
72
-
73
- stage_method = make_stage_method(stage)
79
+ stage_method = _make_stage_method(stage)
74
80
 
75
81
  if stage.description:
76
82
  stage_method.__doc__ = stage.description
@@ -109,7 +115,7 @@ def create_test_class(
109
115
  all_param_names.extend(param_names)
110
116
  stage_method = pytest.mark.parametrize(",".join(param_names), param_values, ids=step.ids or None)(stage_method)
111
117
 
112
- all_fixtures = ["self"] + list(dict.fromkeys(all_param_names + stage.fixtures + scenario.fixtures))
118
+ all_fixtures = ["self", *dict.fromkeys(all_param_names + stage.fixtures + scenario.fixtures)]
113
119
  stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures]) # ty: ignore[unresolved-attribute]
114
120
 
115
121
  # Read by the chain-contiguity hook to restore stage order.