pytest-httpchain 0.15.1__tar.gz → 0.16.0__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 (73) hide show
  1. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/PKG-INFO +53 -33
  2. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/README.md +47 -30
  3. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/pyproject.toml +13 -7
  4. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/pyproject.toml.orig +32 -7
  5. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/__init__.py +2 -1
  6. pytest_httpchain-0.16.0/src/pytest_httpchain/body_schema.py +1303 -0
  7. pytest_httpchain-0.16.0/src/pytest_httpchain/carrier.py +2274 -0
  8. pytest_httpchain-0.16.0/src/pytest_httpchain/cli.py +496 -0
  9. pytest_httpchain-0.16.0/src/pytest_httpchain/constants.py +84 -0
  10. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/dataflow.py +49 -15
  11. pytest_httpchain-0.16.0/src/pytest_httpchain/errors.py +97 -0
  12. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/factory.py +32 -5
  13. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/har_writer.py +37 -23
  14. pytest_httpchain-0.16.0/src/pytest_httpchain/importers/__init__.py +53 -0
  15. pytest_httpchain-0.16.0/src/pytest_httpchain/importers/builder.py +936 -0
  16. pytest_httpchain-0.16.0/src/pytest_httpchain/importers/curl.py +1208 -0
  17. pytest_httpchain-0.16.0/src/pytest_httpchain/importers/har.py +212 -0
  18. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/__init__.py +12 -2
  19. pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/equality.py +22 -0
  20. pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/exceptions.py +30 -0
  21. pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/jsonc.py +119 -0
  22. pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/loader.py +34 -0
  23. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/path.py +13 -1
  24. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/reference.py +80 -22
  25. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/models/__init__.py +66 -4
  26. pytest_httpchain-0.16.0/src/pytest_httpchain/models/entities.py +1362 -0
  27. pytest_httpchain-0.16.0/src/pytest_httpchain/models/types.py +892 -0
  28. pytest_httpchain-0.16.0/src/pytest_httpchain/parallel_stats.py +282 -0
  29. pytest_httpchain-0.16.0/src/pytest_httpchain/plugin.py +784 -0
  30. pytest_httpchain-0.16.0/src/pytest_httpchain/redaction.py +172 -0
  31. pytest_httpchain-0.16.0/src/pytest_httpchain/report_formatter.py +322 -0
  32. pytest_httpchain-0.16.0/src/pytest_httpchain/request_builder.py +675 -0
  33. pytest_httpchain-0.16.0/src/pytest_httpchain/response_steps.py +949 -0
  34. pytest_httpchain-0.16.0/src/pytest_httpchain/scoping.py +772 -0
  35. pytest_httpchain-0.16.0/src/pytest_httpchain/templates/__init__.py +56 -0
  36. pytest_httpchain-0.16.0/src/pytest_httpchain/templates/expressions.py +170 -0
  37. pytest_httpchain-0.16.0/src/pytest_httpchain/templates/functions.py +235 -0
  38. pytest_httpchain-0.16.0/src/pytest_httpchain/templates/substitution.py +556 -0
  39. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/userfunc.py +15 -5
  40. pytest_httpchain-0.16.0/src/pytest_httpchain/utils.py +214 -0
  41. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/__init__.py +24 -3
  42. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/deep.py +100 -36
  43. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/diagnostics.py +20 -0
  44. pytest_httpchain-0.16.0/src/pytest_httpchain/validation/discovery.py +248 -0
  45. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/loader.py +105 -18
  46. pytest_httpchain-0.16.0/src/pytest_httpchain/validation/semantic.py +969 -0
  47. pytest_httpchain-0.16.0/src/pytest_httpchain/validation/validate.py +122 -0
  48. pytest_httpchain-0.15.1/src/pytest_httpchain/carrier.py +0 -707
  49. pytest_httpchain-0.15.1/src/pytest_httpchain/cli.py +0 -238
  50. pytest_httpchain-0.15.1/src/pytest_httpchain/constants.py +0 -44
  51. pytest_httpchain-0.15.1/src/pytest_httpchain/errors.py +0 -47
  52. pytest_httpchain-0.15.1/src/pytest_httpchain/jsonref/exceptions.py +0 -10
  53. pytest_httpchain-0.15.1/src/pytest_httpchain/jsonref/loader.py +0 -23
  54. pytest_httpchain-0.15.1/src/pytest_httpchain/models/entities.py +0 -582
  55. pytest_httpchain-0.15.1/src/pytest_httpchain/models/types.py +0 -200
  56. pytest_httpchain-0.15.1/src/pytest_httpchain/plugin.py +0 -415
  57. pytest_httpchain-0.15.1/src/pytest_httpchain/report_formatter.py +0 -72
  58. pytest_httpchain-0.15.1/src/pytest_httpchain/request_builder.py +0 -131
  59. pytest_httpchain-0.15.1/src/pytest_httpchain/response_steps.py +0 -210
  60. pytest_httpchain-0.15.1/src/pytest_httpchain/scoping.py +0 -423
  61. pytest_httpchain-0.15.1/src/pytest_httpchain/templates/__init__.py +0 -23
  62. pytest_httpchain-0.15.1/src/pytest_httpchain/templates/expressions.py +0 -30
  63. pytest_httpchain-0.15.1/src/pytest_httpchain/templates/substitution.py +0 -200
  64. pytest_httpchain-0.15.1/src/pytest_httpchain/utils.py +0 -144
  65. pytest_httpchain-0.15.1/src/pytest_httpchain/validation/semantic.py +0 -550
  66. pytest_httpchain-0.15.1/src/pytest_httpchain/validation/validate.py +0 -50
  67. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/LICENSE +0 -0
  68. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/__init__.py +0 -0
  69. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/circular.py +0 -0
  70. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/py.typed +0 -0
  71. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/schema.py +0 -0
  72. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/src/pytest_httpchain/templates/exceptions.py +0 -0
  73. {pytest_httpchain-0.15.1 → pytest_httpchain-0.16.0}/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.15.1
3
+ Version: 0.16.0
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
@@ -15,16 +15,19 @@ Classifier: Programming Language :: Python :: 3.13
15
15
  Classifier: Programming Language :: Python :: 3.14
16
16
  Classifier: Topic :: Software Development :: Testing
17
17
  Classifier: Typing :: Typed
18
+ Requires-Dist: attrs>=22.2.0
18
19
  Requires-Dist: deepmerge>=2.0
19
20
  Requires-Dist: graphql-core>=3.0.0
20
- Requires-Dist: httpx[http2]>=0.27.0
21
+ Requires-Dist: httpx[http2]>=0.28.0
22
+ Requires-Dist: iniconfig>=1.0.1
21
23
  Requires-Dist: jmespath>=1.0.0
22
24
  Requires-Dist: jsonschema>=4.18.0
25
+ Requires-Dist: jsonschema-specifications>=2023.3.6
23
26
  Requires-Dist: pydantic>=2.13.4
24
27
  Requires-Dist: referencing>=0.28.4
25
28
  Requires-Dist: pyrate-limiter>=4.2.0
26
29
  Requires-Dist: pytest>=9.0
27
- Requires-Dist: simpleeval>=1.0.3
30
+ Requires-Dist: simpleeval>=1.0.8
28
31
  Requires-Dist: typer>=0.26.0
29
32
  Requires-Python: >=3.13
30
33
  Project-URL: Repository, https://github.com/aeresov/pytest-httpchain
@@ -62,7 +65,7 @@ Testing HTTP APIs with plain pytest often leads to these pain points:
62
65
 
63
66
  ### Declarative JSON format
64
67
 
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.
68
+ 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. Comments (`//`, `/* */`) and trailing commas are welcome in every scenario and every file it pulls in; name a file `test_<name>.http.jsonc` and editors treat it as JSON with comments.
66
69
 
67
70
  ### `$include` / `$merge` with deep merging
68
71
 
@@ -70,17 +73,43 @@ Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type
70
73
 
71
74
  ### Multi-stage execution
72
75
 
73
- Each scenario contains 1+ stages executed in order. One stage failure stops the chain. Use `always_run` for cleanup stages that should execute regardless.
76
+ Each scenario contains 1+ stages executed in order. One stage failure stops the chain. Use `always_run` for cleanup stages that should execute regardless, and `skip_if` to skip a stage on a condition known only once the chain is running, such as a value an earlier stage saved.
77
+
78
+ ### Retries and polling
79
+
80
+ A stage's `retry` attempts it again while it fails, after a wait that can grow each time: poll an asynchronous job until it reports `done`, or ride out eventual consistency and a flaky network (`"retry": {"attempts": 10, "delay": 0.5, "backoff": 2}`). Each attempt sends a freshly rendered request and runs every response step; only the attempt that passes saves anything.
81
+
82
+ ### Parallel stages and load checks
83
+
84
+ A stage's `parallel` sends its request many times at once (`repeat`) or once per parameter set (`foreach`), with a concurrency cap and a rate limit. Its report sums the run up: iterations passed, failed and cancelled, wall time, throughput and p50/p95/p99 latency. `thresholds` fail the stage below a success ratio or above a latency (`"thresholds": {"min_success_ratio": 0.99, "max_p95_ms": 300}`), letting it run on after failed requests as long as enough pass, and `stats_as` saves the numbers for a later stage.
74
85
 
75
86
  ### Common data context
76
87
 
77
- A key-value store persists throughout scenario execution. Variables, fixtures, and saved response data all live here. Use template expressions (`{{ var }}`) in any request **value** — substitution happens dynamically before each stage. (Dict keys are not substituted; `HTTPCHAIN029` flags a template in a key.)
88
+ A key-value store persists throughout scenario execution. Variables, fixtures, and saved response data all live here. Use template expressions (`{{ var }}`) in any request **value** — substitution happens dynamically before each stage. (Dict keys are not substituted; `HTTPCHAIN029` flags a template in a key.) Built-in functions give the values tests keep needing without a fixture: the time (`now()`, `timestamp()`), base64, JSON and URL encoding, and SHA-256, MD5 and HMAC-SHA256 digests for signing a request.
89
+
90
+ ### Request bodies
91
+
92
+ JSON, form, XML, text, base64, a binary file and GraphQL, and multipart uploads that mix form fields with files: each file read from a path or given inline, several under one name if need be, with its own filename and content type.
78
93
 
79
94
  ### Response processing
80
95
 
81
- - **JMESPath** — Extract values from JSON responses directly
82
- - **JSON Schema** — Validate response structure against a schema
96
+ - **JMESPath** — Assert on values in JSON responses directly (`"jmespath": {"data.id": 42, "items": {"length": 3}}`), or extract them for later stages
97
+ - **Regex** — Save values from bodies that are not JSON, such as a CSRF token from an HTML form (`"regex": {"csrf": "name=\"csrf\" value=\"([^\"]+)\""}`)
98
+ - **JSON Schema** — Validate response structure against a schema, inline or from a file, or one inside a document you already have: `"schema": "./openapi.json#/components/schemas/User"` checks the response against an OpenAPI component, its `$ref`s resolved across the document and into local files, never over the network
83
99
  - **User functions** — Call Python functions for custom extraction, verification, or [authentication](https://www.python-httpx.org/advanced/authentication/#custom-authentication-schemes)
100
+ - **Failure reports** — A failing verify step lists every check that failed, not only the first, and the report gives the request as a ready-to-run `curl` command beside the request and response it shows
101
+
102
+ ### Scenario-wide client settings
103
+
104
+ A scenario's `client` block sets up the HTTP client all its stages share, once: a base URL their relative URLs are appended to, headers and query parameters sent with every request, timeout, redirects, proxy, HTTP/2 and connection pool. A stage overrides what it needs.
105
+
106
+ ### Authentication
107
+
108
+ Basic, digest and bearer authentication are built in, for the whole scenario or one request: `"auth": {"bearer": "{{ token }}"}` sends the token a login stage saved. `"auth": false` exempts a public endpoint, and a Python function covers any other scheme.
109
+
110
+ ### Import recorded traffic
111
+
112
+ Start from traffic you already have: `pytest-httpchain import har session.har` turns a browser's HAR export into a scenario, a stage per request, and `pytest-httpchain import curl '...'` does the same for curl commands from an API's docs or a failing stage's report. It sets the base URL, maps query strings, JSON, form and multipart bodies and Basic or Bearer credentials into the dialect, leaves out the transport headers and static assets, and writes no secret: tokens, passwords and cookies become placeholders read from environment variables. What it writes passes `validate`.
84
113
 
85
114
  ### Full pytest integration
86
115
 
@@ -92,6 +121,9 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
92
121
 
93
122
  ```json
94
123
  {
124
+ "client": {
125
+ "base_url": "https://api.example.com"
126
+ },
95
127
  "substitutions": [
96
128
  {
97
129
  "vars": {
@@ -102,7 +134,7 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
102
134
  "stages": {
103
135
  "get_user": {
104
136
  "request": {
105
- "url": "https://api.example.com/users/{{ user_id }}"
137
+ "url": "/users/{{ user_id }}"
106
138
  },
107
139
  "response": [
108
140
  {
@@ -120,15 +152,14 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
120
152
  ]
121
153
  },
122
154
  "update_user": {
123
- "fixtures": ["now_utc"],
124
155
  "request": {
125
- "url": "https://api.example.com/users/{{ user_id }}",
156
+ "url": "/users/{{ user_id }}",
126
157
  "method": "PUT",
127
158
  "body": {
128
159
  "json": {
129
160
  "user": {
130
161
  "name": "{{ user_name }}_updated",
131
- "timestamp": "{{ str(now_utc) }}"
162
+ "timestamp": "{{ now() }}"
132
163
  }
133
164
  }
134
165
  }
@@ -144,7 +175,7 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
144
175
  "cleanup": {
145
176
  "always_run": true,
146
177
  "request": {
147
- "url": "https://api.example.com/cleanup",
178
+ "url": "/cleanup",
148
179
  "method": "POST"
149
180
  }
150
181
  }
@@ -152,31 +183,18 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
152
183
  }
153
184
  ```
154
185
 
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
-
168
186
  Scenario we created:
169
187
 
188
+ - the scenario's HTTP client gets a base URL, so every stage gives only its path
170
189
  - common data context is seeded with the first variable `user_id`
171
190
  - **get_user**
172
- url is assembled using `user_id` variable from common data context
191
+ url is assembled using `user_id` variable from common data context, and appended to the base URL
173
192
  HTTP GET call is made
174
193
  we verify the call returned code 200
175
194
  assuming JSON body is returned, we extract a value by JMESPath expression `user.name` and save it to common data context under `user_name` key
176
195
  - **update_user**
177
- `now_utc` fixture value is injected into common data context
178
196
  url is assembled using `user_id` variable from common data context
179
- we create JSON body in place using values from common data context, note that `now_utc` is converted to string in place
197
+ we create JSON body in place using values from common data context, and the current UTC time from the built-in `now()`
180
198
  HTTP PUT call with body is made
181
199
  we verify the call returned code 200
182
200
  - **cleanup**
@@ -201,12 +219,13 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
201
219
 
202
220
  ## Configuration
203
221
 
204
- - Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.
222
+ - Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`, or `test_<name>.<suffix>.jsonc`.
205
223
  The suffix is configurable via the `httpchain_suffix` pytest ini option, default value is **http**.
206
224
  - `$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).
207
225
  You can limit the depth of relative path traversal using the `httpchain_ref_parent_traversal_depth` ini option, default value is **3**.
208
226
  - 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**.
209
227
  - Parallel stage iterations (repeat/foreach) have a safety limit configurable via the `httpchain_max_parallel_iterations` ini option, default value is **10000**.
228
+ - A failing stage's report prints the values of credential headers and query parameters as `[REDACTED]`, keeping their names (and cookie names). The lists are set by the `httpchain_redact_headers` ini option, default **Authorization Proxy-Authorization Cookie Set-Cookie X-API-Key API-Key X-Auth-Token**, and `httpchain_redact_query_params`, default **access_token refresh_token id_token api_key apikey client_secret password token**; an empty value disables one. Request and response bodies, and DEBUG logs, are not redacted. See [Secrets in reports](https://aeresov.github.io/pytest-httpchain/getting-started/#secrets-in-reports).
210
229
 
211
230
  ### HAR export
212
231
 
@@ -216,7 +235,7 @@ Pass `--httpchain-output-dir DIR` on the pytest command line to write an [HAR](h
216
235
  pytest --httpchain-output-dir ./har-output
217
236
  ```
218
237
 
219
- HAR files contain full requests/responses **including credential headers and saved tokens** — nothing is redacted, so scrub them before sharing. Bodies are embedded complete and uncapped (binary bodies grow ~33% as base64), so scenarios that transfer large payloads produce large `.har` files. See the [HAR export docs](https://aeresov.github.io/pytest-httpchain/getting-started/#har-export).
238
+ HAR files contain full requests/responses **including credential headers and saved tokens**: a HAR is usually replayed, which needs the real values, so nothing is redacted unless the `httpchain_har_redact` ini option is `true` (it applies the report's rules to URLs, headers and cookies; bodies stay complete). Scrub them before sharing. Bodies are embedded complete and uncapped (binary bodies grow ~33% as base64), so scenarios that transfer large payloads produce large `.har` files. See the [HAR export docs](https://aeresov.github.io/pytest-httpchain/getting-started/#har-export).
220
239
 
221
240
  ## AI agent support
222
241
 
@@ -224,10 +243,11 @@ HAR files contain full requests/responses **including credential headers and sav
224
243
 
225
244
  ### Scenario validation
226
245
 
227
- Validate scenario files for structure and common problems — undefined variables, variables referenced before they are saved (data-flow ordering), duplicate stage names, fixture/variable conflicts, no-op `verify` steps, and contradictory body checks:
246
+ Validate scenario files for structure and common problems — undefined variables, variables referenced before they are saved (data-flow ordering), duplicate stage names, fixture/variable conflicts, no-op `verify` steps, and contradictory body checks. Name the files, or a directory to check every scenario pytest would collect in it:
228
247
 
229
248
  ```bash
230
249
  uvx pytest-httpchain validate tests/test_login.http.json
250
+ uvx pytest-httpchain validate tests/
231
251
  ```
232
252
 
233
253
  Each finding carries a stable diagnostic code (`HTTPCHAINxxx`) and a severity — the [full code reference](https://aeresov.github.io/pytest-httpchain/diagnostics/) is on the docs site, along with a recipe for filtering the `ScenarioValidationWarning` warnings the same checks emit at pytest collection. It exits non-zero when any file is invalid, so it doubles as a CI gate. Use `--format json` for machine-readable output (editor/CI integration):
@@ -273,7 +293,7 @@ uvx pytest-httpchain schema > scenario.schema.json
273
293
  More read-only commands help author and debug scenarios offline — no network, no test run:
274
294
 
275
295
  ```bash
276
- # Print a scenario with all $ref/$include/$merge inlined and deep-merged
296
+ # Print a scenario with all $ref/$include/$merge inlined and deep-merged, as strict JSON (comments dropped)
277
297
  uvx pytest-httpchain resolve tests/test_login.http.json
278
298
 
279
299
  # Summarize stages and the variable data-flow (which stage saves what, who consumes it)
@@ -28,7 +28,7 @@ Testing HTTP APIs with plain pytest often leads to these pain points:
28
28
 
29
29
  ### Declarative JSON format
30
30
 
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.
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. Comments (`//`, `/* */`) and trailing commas are welcome in every scenario and every file it pulls in; name a file `test_<name>.http.jsonc` and editors treat it as JSON with comments.
32
32
 
33
33
  ### `$include` / `$merge` with deep merging
34
34
 
@@ -36,17 +36,43 @@ Reuse arbitrary parts of your scenarios with JSONRef. Properties merge with type
36
36
 
37
37
  ### Multi-stage execution
38
38
 
39
- Each scenario contains 1+ stages executed in order. One stage failure stops the chain. Use `always_run` for cleanup stages that should execute regardless.
39
+ Each scenario contains 1+ stages executed in order. One stage failure stops the chain. Use `always_run` for cleanup stages that should execute regardless, and `skip_if` to skip a stage on a condition known only once the chain is running, such as a value an earlier stage saved.
40
+
41
+ ### Retries and polling
42
+
43
+ A stage's `retry` attempts it again while it fails, after a wait that can grow each time: poll an asynchronous job until it reports `done`, or ride out eventual consistency and a flaky network (`"retry": {"attempts": 10, "delay": 0.5, "backoff": 2}`). Each attempt sends a freshly rendered request and runs every response step; only the attempt that passes saves anything.
44
+
45
+ ### Parallel stages and load checks
46
+
47
+ A stage's `parallel` sends its request many times at once (`repeat`) or once per parameter set (`foreach`), with a concurrency cap and a rate limit. Its report sums the run up: iterations passed, failed and cancelled, wall time, throughput and p50/p95/p99 latency. `thresholds` fail the stage below a success ratio or above a latency (`"thresholds": {"min_success_ratio": 0.99, "max_p95_ms": 300}`), letting it run on after failed requests as long as enough pass, and `stats_as` saves the numbers for a later stage.
40
48
 
41
49
  ### Common data context
42
50
 
43
- A key-value store persists throughout scenario execution. Variables, fixtures, and saved response data all live here. Use template expressions (`{{ var }}`) in any request **value** — substitution happens dynamically before each stage. (Dict keys are not substituted; `HTTPCHAIN029` flags a template in a key.)
51
+ A key-value store persists throughout scenario execution. Variables, fixtures, and saved response data all live here. Use template expressions (`{{ var }}`) in any request **value** — substitution happens dynamically before each stage. (Dict keys are not substituted; `HTTPCHAIN029` flags a template in a key.) Built-in functions give the values tests keep needing without a fixture: the time (`now()`, `timestamp()`), base64, JSON and URL encoding, and SHA-256, MD5 and HMAC-SHA256 digests for signing a request.
52
+
53
+ ### Request bodies
54
+
55
+ JSON, form, XML, text, base64, a binary file and GraphQL, and multipart uploads that mix form fields with files: each file read from a path or given inline, several under one name if need be, with its own filename and content type.
44
56
 
45
57
  ### Response processing
46
58
 
47
- - **JMESPath** — Extract values from JSON responses directly
48
- - **JSON Schema** — Validate response structure against a schema
59
+ - **JMESPath** — Assert on values in JSON responses directly (`"jmespath": {"data.id": 42, "items": {"length": 3}}`), or extract them for later stages
60
+ - **Regex** — Save values from bodies that are not JSON, such as a CSRF token from an HTML form (`"regex": {"csrf": "name=\"csrf\" value=\"([^\"]+)\""}`)
61
+ - **JSON Schema** — Validate response structure against a schema, inline or from a file, or one inside a document you already have: `"schema": "./openapi.json#/components/schemas/User"` checks the response against an OpenAPI component, its `$ref`s resolved across the document and into local files, never over the network
49
62
  - **User functions** — Call Python functions for custom extraction, verification, or [authentication](https://www.python-httpx.org/advanced/authentication/#custom-authentication-schemes)
63
+ - **Failure reports** — A failing verify step lists every check that failed, not only the first, and the report gives the request as a ready-to-run `curl` command beside the request and response it shows
64
+
65
+ ### Scenario-wide client settings
66
+
67
+ A scenario's `client` block sets up the HTTP client all its stages share, once: a base URL their relative URLs are appended to, headers and query parameters sent with every request, timeout, redirects, proxy, HTTP/2 and connection pool. A stage overrides what it needs.
68
+
69
+ ### Authentication
70
+
71
+ Basic, digest and bearer authentication are built in, for the whole scenario or one request: `"auth": {"bearer": "{{ token }}"}` sends the token a login stage saved. `"auth": false` exempts a public endpoint, and a Python function covers any other scheme.
72
+
73
+ ### Import recorded traffic
74
+
75
+ Start from traffic you already have: `pytest-httpchain import har session.har` turns a browser's HAR export into a scenario, a stage per request, and `pytest-httpchain import curl '...'` does the same for curl commands from an API's docs or a failing stage's report. It sets the base URL, maps query strings, JSON, form and multipart bodies and Basic or Bearer credentials into the dialect, leaves out the transport headers and static assets, and writes no secret: tokens, passwords and cookies become placeholders read from environment variables. What it writes passes `validate`.
50
76
 
51
77
  ### Full pytest integration
52
78
 
@@ -58,6 +84,9 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
58
84
 
59
85
  ```json
60
86
  {
87
+ "client": {
88
+ "base_url": "https://api.example.com"
89
+ },
61
90
  "substitutions": [
62
91
  {
63
92
  "vars": {
@@ -68,7 +97,7 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
68
97
  "stages": {
69
98
  "get_user": {
70
99
  "request": {
71
- "url": "https://api.example.com/users/{{ user_id }}"
100
+ "url": "/users/{{ user_id }}"
72
101
  },
73
102
  "response": [
74
103
  {
@@ -86,15 +115,14 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
86
115
  ]
87
116
  },
88
117
  "update_user": {
89
- "fixtures": ["now_utc"],
90
118
  "request": {
91
- "url": "https://api.example.com/users/{{ user_id }}",
119
+ "url": "/users/{{ user_id }}",
92
120
  "method": "PUT",
93
121
  "body": {
94
122
  "json": {
95
123
  "user": {
96
124
  "name": "{{ user_name }}_updated",
97
- "timestamp": "{{ str(now_utc) }}"
125
+ "timestamp": "{{ now() }}"
98
126
  }
99
127
  }
100
128
  }
@@ -110,7 +138,7 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
110
138
  "cleanup": {
111
139
  "always_run": true,
112
140
  "request": {
113
- "url": "https://api.example.com/cleanup",
141
+ "url": "/cleanup",
114
142
  "method": "POST"
115
143
  }
116
144
  }
@@ -118,31 +146,18 @@ Create a JSON test file named like `test_<name>.<suffix>.json` (default suffix i
118
146
  }
119
147
  ```
120
148
 
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
-
134
149
  Scenario we created:
135
150
 
151
+ - the scenario's HTTP client gets a base URL, so every stage gives only its path
136
152
  - common data context is seeded with the first variable `user_id`
137
153
  - **get_user**
138
- url is assembled using `user_id` variable from common data context
154
+ url is assembled using `user_id` variable from common data context, and appended to the base URL
139
155
  HTTP GET call is made
140
156
  we verify the call returned code 200
141
157
  assuming JSON body is returned, we extract a value by JMESPath expression `user.name` and save it to common data context under `user_name` key
142
158
  - **update_user**
143
- `now_utc` fixture value is injected into common data context
144
159
  url is assembled using `user_id` variable from common data context
145
- we create JSON body in place using values from common data context, note that `now_utc` is converted to string in place
160
+ we create JSON body in place using values from common data context, and the current UTC time from the built-in `now()`
146
161
  HTTP PUT call with body is made
147
162
  we verify the call returned code 200
148
163
  - **cleanup**
@@ -167,12 +182,13 @@ pip install 'git+https://github.com/aeresov/pytest-httpchain@main'
167
182
 
168
183
  ## Configuration
169
184
 
170
- - Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`.
185
+ - Test file discovery is based on this name pattern: `test_<name>.<suffix>.json`, or `test_<name>.<suffix>.jsonc`.
171
186
  The suffix is configurable via the `httpchain_suffix` pytest ini option, default value is **http**.
172
187
  - `$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).
173
188
  You can limit the depth of relative path traversal using the `httpchain_ref_parent_traversal_depth` ini option, default value is **3**.
174
189
  - 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**.
175
190
  - Parallel stage iterations (repeat/foreach) have a safety limit configurable via the `httpchain_max_parallel_iterations` ini option, default value is **10000**.
191
+ - A failing stage's report prints the values of credential headers and query parameters as `[REDACTED]`, keeping their names (and cookie names). The lists are set by the `httpchain_redact_headers` ini option, default **Authorization Proxy-Authorization Cookie Set-Cookie X-API-Key API-Key X-Auth-Token**, and `httpchain_redact_query_params`, default **access_token refresh_token id_token api_key apikey client_secret password token**; an empty value disables one. Request and response bodies, and DEBUG logs, are not redacted. See [Secrets in reports](https://aeresov.github.io/pytest-httpchain/getting-started/#secrets-in-reports).
176
192
 
177
193
  ### HAR export
178
194
 
@@ -182,7 +198,7 @@ Pass `--httpchain-output-dir DIR` on the pytest command line to write an [HAR](h
182
198
  pytest --httpchain-output-dir ./har-output
183
199
  ```
184
200
 
185
- HAR files contain full requests/responses **including credential headers and saved tokens** — nothing is redacted, so scrub them before sharing. Bodies are embedded complete and uncapped (binary bodies grow ~33% as base64), so scenarios that transfer large payloads produce large `.har` files. See the [HAR export docs](https://aeresov.github.io/pytest-httpchain/getting-started/#har-export).
201
+ HAR files contain full requests/responses **including credential headers and saved tokens**: a HAR is usually replayed, which needs the real values, so nothing is redacted unless the `httpchain_har_redact` ini option is `true` (it applies the report's rules to URLs, headers and cookies; bodies stay complete). Scrub them before sharing. Bodies are embedded complete and uncapped (binary bodies grow ~33% as base64), so scenarios that transfer large payloads produce large `.har` files. See the [HAR export docs](https://aeresov.github.io/pytest-httpchain/getting-started/#har-export).
186
202
 
187
203
  ## AI agent support
188
204
 
@@ -190,10 +206,11 @@ HAR files contain full requests/responses **including credential headers and sav
190
206
 
191
207
  ### Scenario validation
192
208
 
193
- Validate scenario files for structure and common problems — undefined variables, variables referenced before they are saved (data-flow ordering), duplicate stage names, fixture/variable conflicts, no-op `verify` steps, and contradictory body checks:
209
+ Validate scenario files for structure and common problems — undefined variables, variables referenced before they are saved (data-flow ordering), duplicate stage names, fixture/variable conflicts, no-op `verify` steps, and contradictory body checks. Name the files, or a directory to check every scenario pytest would collect in it:
194
210
 
195
211
  ```bash
196
212
  uvx pytest-httpchain validate tests/test_login.http.json
213
+ uvx pytest-httpchain validate tests/
197
214
  ```
198
215
 
199
216
  Each finding carries a stable diagnostic code (`HTTPCHAINxxx`) and a severity — the [full code reference](https://aeresov.github.io/pytest-httpchain/diagnostics/) is on the docs site, along with a recipe for filtering the `ScenarioValidationWarning` warnings the same checks emit at pytest collection. It exits non-zero when any file is invalid, so it doubles as a CI gate. Use `--format json` for machine-readable output (editor/CI integration):
@@ -239,7 +256,7 @@ uvx pytest-httpchain schema > scenario.schema.json
239
256
  More read-only commands help author and debug scenarios offline — no network, no test run:
240
257
 
241
258
  ```bash
242
- # Print a scenario with all $ref/$include/$merge inlined and deep-merged
259
+ # Print a scenario with all $ref/$include/$merge inlined and deep-merged, as strict JSON (comments dropped)
243
260
  uvx pytest-httpchain resolve tests/test_login.http.json
244
261
 
245
262
  # Summarize stages and the variable data-flow (which stage saves what, who consumes it)
@@ -1,20 +1,23 @@
1
1
  [project]
2
2
  name = "pytest-httpchain"
3
- version = "0.15.1"
3
+ version = "0.16.0"
4
4
  description = "pytest plugin for HTTP testing using JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
7
7
  dependencies = [
8
+ "attrs>=22.2.0",
8
9
  "deepmerge>=2.0",
9
10
  "graphql-core>=3.0.0",
10
- "httpx[http2]>=0.27.0",
11
+ "httpx[http2]>=0.28.0",
12
+ "iniconfig>=1.0.1",
11
13
  "jmespath>=1.0.0",
12
14
  "jsonschema>=4.18.0",
15
+ "jsonschema-specifications>=2023.03.6",
13
16
  "pydantic>=2.13.4",
14
17
  "referencing>=0.28.4",
15
18
  "pyrate-limiter>=4.2.0",
16
19
  "pytest>=9.0",
17
- "simpleeval>=1.0.3",
20
+ "simpleeval>=1.0.8",
18
21
  "typer>=0.26.0",
19
22
  ]
20
23
  keywords = [
@@ -59,10 +62,12 @@ dev = [
59
62
  "flask-httpauth>=4.8.0",
60
63
  "import-linter>=2.0",
61
64
  "ruff>=0.12.1",
65
+ "ty>=0.0.84",
62
66
  "coverage[toml]>=7.10",
63
67
  "pytest-datadir>=1.7.2",
64
68
  "pytest-order>=1.3.0",
65
69
  "pytest-xdist>=3.8.0",
70
+ "socksio>=1.0.0",
66
71
  "trustme>=1.1.0",
67
72
  ]
68
73
  docs = [
@@ -165,9 +170,10 @@ exhaustive = true
165
170
  layers = [
166
171
  "plugin : cli",
167
172
  "factory",
168
- "carrier : dataflow : schema",
169
- "validation : har_writer : report_formatter : request_builder : response_steps",
170
- "utils : scoping",
173
+ "carrier : dataflow : schema : importers",
174
+ "validation : har_writer : report_formatter : request_builder : response_steps : parallel_stats",
175
+ "body_schema",
176
+ "utils : scoping : redaction",
171
177
  "userfunc",
172
178
  "models",
173
179
  "templates : jsonref",
@@ -181,5 +187,5 @@ source_modules = ["pytest_httpchain.models"]
181
187
  forbidden_modules = ["pytest_httpchain.jsonref"]
182
188
 
183
189
  [build-system]
184
- requires = ["uv_build>=0.11,<0.12"]
190
+ requires = ["uv_build>=0.12,<0.13"]
185
191
  build-backend = "uv_build"
@@ -1,21 +1,38 @@
1
1
  [project]
2
2
  name = "pytest-httpchain"
3
- version = "0.15.1"
3
+ version = "0.16.0"
4
4
  description = "pytest plugin for HTTP testing using JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
7
7
  authors = [{ name = "Alexander Eresov", email = "aeresov@gmail.com" }]
8
8
  dependencies = [
9
+ # attrs.fields, for the validator classes a body schema is validated with
10
+ # (body_schema): the floor jsonschema 4.18.0 itself requires.
11
+ "attrs>=22.2.0",
9
12
  "deepmerge>=2.0",
10
13
  "graphql-core>=3.0.0",
11
- "httpx[http2]>=0.27.0",
14
+ # 0.28.0 is the first release that takes a socks5h:// proxy, which
15
+ # client.proxy accepts. (0.27.0 also percent-encoded a `\` in a URL path,
16
+ # `/a%5Cb`, so a URL the plugin sends as written did not reach the server
17
+ # as written.) No upper bound, but before taking a new httpx: the built-in
18
+ # digest auth (request_builder._DigestAuth) builds on DigestAuth's private
19
+ # state, which its unit tests in tests/unit/test_request_builder.py pin.
20
+ "httpx[http2]>=0.28.0",
21
+ # The parser pytest reads its ini files with: `validate` reads
22
+ # httpchain_suffix from one (validation.discovery) as pytest would. The
23
+ # floor pytest 9.0 itself requires.
24
+ "iniconfig>=1.0.1",
12
25
  "jmespath>=1.0.0",
13
26
  "jsonschema>=4.18.0",
27
+ # The meta-schemas a body schema's registry holds (body_schema): the
28
+ # floor jsonschema 4.18.0 itself requires, as for attrs.
29
+ "jsonschema-specifications>=2023.03.6",
14
30
  "pydantic>=2.13.4",
15
31
  "referencing>=0.28.4",
16
32
  "pyrate-limiter>=4.2.0",
17
33
  "pytest>=9.0",
18
- "simpleeval>=1.0.3",
34
+ # 1.0.8 blocks sandbox escapes through the operator module and os.exec*/spawn*.
35
+ "simpleeval>=1.0.8",
19
36
  # 0.26.0 is the first release that stopped importing the deprecated
20
37
  # `click.utils.get_binary_stream`; with `filterwarnings = error` any older
21
38
  # typer fails collection against current click.
@@ -46,6 +63,7 @@ dev = [
46
63
  "flask-httpauth>=4.8.0",
47
64
  "import-linter>=2.0",
48
65
  "ruff>=0.12.1",
66
+ "ty>=0.0.84",
49
67
  "coverage[toml]>=7.10", # `patch = ["subprocess"]` needs 7.10
50
68
 
51
69
  "pytest-datadir>=1.7.2",
@@ -54,6 +72,9 @@ dev = [
54
72
  # the regroup's defense against a user-installed pytest-order.
55
73
  "pytest-order>=1.3.0",
56
74
  "pytest-xdist>=3.8.0",
75
+ # httpx's SOCKS support (its `socks` extra), which users install
76
+ # themselves: the tests build a client for every client.proxy scheme.
77
+ "socksio>=1.0.0",
57
78
  "trustme>=1.1.0",
58
79
  ]
59
80
  docs = [
@@ -65,7 +86,7 @@ docs = [
65
86
  default-groups = ["dev", "docs"]
66
87
 
67
88
  [build-system]
68
- requires = ["uv_build>=0.11,<0.12"]
89
+ requires = ["uv_build>=0.12,<0.13"]
69
90
  build-backend = "uv_build"
70
91
 
71
92
  [tool.uv.build-backend]
@@ -190,9 +211,13 @@ exhaustive = true
190
211
  layers = [
191
212
  "plugin : cli",
192
213
  "factory",
193
- "carrier : dataflow : schema",
194
- "validation : har_writer : report_formatter : request_builder : response_steps",
195
- "utils : scoping",
214
+ # importers is the cli's `import` command, beside carrier and independent
215
+ # of it: it builds on validation, templates and redaction, and nothing on
216
+ # a lower layer, the domain packages included, may import it.
217
+ "carrier : dataflow : schema : importers",
218
+ "validation : har_writer : report_formatter : request_builder : response_steps : parallel_stats",
219
+ "body_schema",
220
+ "utils : scoping : redaction",
196
221
  "userfunc",
197
222
  "models",
198
223
  "templates : jsonref",
@@ -1,6 +1,7 @@
1
1
  """pytest-httpchain: declarative HTTP API integration testing.
2
2
 
3
- Test scenarios are JSON files (``test_<name>.http.json``) with ``$ref`` support,
3
+ Test scenarios are JSON files (``test_<name>.http.json``, or ``.http.jsonc``;
4
+ comments and trailing commas allowed in either) with ``$ref`` support,
4
5
  ``{{ expr }}`` templates, and multi-stage request chaining.
5
6
  """
6
7