pytest-httpchain 0.15.2__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.
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/PKG-INFO +52 -32
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/README.md +47 -30
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/pyproject.toml +10 -5
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/pyproject.toml.orig +28 -5
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/__init__.py +2 -1
- pytest_httpchain-0.16.0/src/pytest_httpchain/body_schema.py +1303 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/carrier.py +2274 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/cli.py +496 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/constants.py +84 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/dataflow.py +49 -15
- pytest_httpchain-0.16.0/src/pytest_httpchain/errors.py +97 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/factory.py +32 -5
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/har_writer.py +37 -23
- pytest_httpchain-0.16.0/src/pytest_httpchain/importers/__init__.py +53 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/importers/builder.py +936 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/importers/curl.py +1208 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/importers/har.py +212 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/__init__.py +12 -2
- pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/equality.py +22 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/exceptions.py +30 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/jsonc.py +119 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/jsonref/loader.py +34 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/path.py +13 -1
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/reference.py +80 -22
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/models/__init__.py +66 -4
- pytest_httpchain-0.16.0/src/pytest_httpchain/models/entities.py +1362 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/models/types.py +892 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/parallel_stats.py +282 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/plugin.py +784 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/redaction.py +172 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/report_formatter.py +322 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/request_builder.py +675 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/response_steps.py +949 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/scoping.py +772 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/templates/__init__.py +56 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/templates/expressions.py +170 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/templates/functions.py +235 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/templates/substitution.py +556 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/userfunc.py +15 -5
- pytest_httpchain-0.16.0/src/pytest_httpchain/utils.py +214 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/__init__.py +24 -3
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/deep.py +100 -36
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/diagnostics.py +20 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/validation/discovery.py +248 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/validation/loader.py +105 -18
- pytest_httpchain-0.16.0/src/pytest_httpchain/validation/semantic.py +969 -0
- pytest_httpchain-0.16.0/src/pytest_httpchain/validation/validate.py +122 -0
- pytest_httpchain-0.15.2/src/pytest_httpchain/carrier.py +0 -720
- pytest_httpchain-0.15.2/src/pytest_httpchain/cli.py +0 -238
- pytest_httpchain-0.15.2/src/pytest_httpchain/constants.py +0 -44
- pytest_httpchain-0.15.2/src/pytest_httpchain/errors.py +0 -47
- pytest_httpchain-0.15.2/src/pytest_httpchain/jsonref/exceptions.py +0 -10
- pytest_httpchain-0.15.2/src/pytest_httpchain/jsonref/loader.py +0 -23
- pytest_httpchain-0.15.2/src/pytest_httpchain/models/entities.py +0 -582
- pytest_httpchain-0.15.2/src/pytest_httpchain/models/types.py +0 -200
- pytest_httpchain-0.15.2/src/pytest_httpchain/plugin.py +0 -448
- pytest_httpchain-0.15.2/src/pytest_httpchain/report_formatter.py +0 -72
- pytest_httpchain-0.15.2/src/pytest_httpchain/request_builder.py +0 -131
- pytest_httpchain-0.15.2/src/pytest_httpchain/response_steps.py +0 -210
- pytest_httpchain-0.15.2/src/pytest_httpchain/scoping.py +0 -423
- pytest_httpchain-0.15.2/src/pytest_httpchain/templates/__init__.py +0 -23
- pytest_httpchain-0.15.2/src/pytest_httpchain/templates/expressions.py +0 -30
- pytest_httpchain-0.15.2/src/pytest_httpchain/templates/substitution.py +0 -200
- pytest_httpchain-0.15.2/src/pytest_httpchain/utils.py +0 -144
- pytest_httpchain-0.15.2/src/pytest_httpchain/validation/semantic.py +0 -550
- pytest_httpchain-0.15.2/src/pytest_httpchain/validation/validate.py +0 -50
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/LICENSE +0 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/__init__.py +0 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/jsonref/plumbing/circular.py +0 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/py.typed +0 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/schema.py +0 -0
- {pytest_httpchain-0.15.2 → pytest_httpchain-0.16.0}/src/pytest_httpchain/templates/exceptions.py +0 -0
- {pytest_httpchain-0.15.2 → 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.
|
|
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,11 +15,14 @@ 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.
|
|
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
|
|
@@ -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** —
|
|
82
|
-
- **
|
|
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": "
|
|
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": "
|
|
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": "{{
|
|
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": "
|
|
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,
|
|
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
|
|
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** —
|
|
48
|
-
- **
|
|
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": "
|
|
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": "
|
|
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": "{{
|
|
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": "
|
|
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,
|
|
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
|
|
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,15 +1,18 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "pytest-httpchain"
|
|
3
|
-
version = "0.
|
|
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.
|
|
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",
|
|
@@ -64,6 +67,7 @@ dev = [
|
|
|
64
67
|
"pytest-datadir>=1.7.2",
|
|
65
68
|
"pytest-order>=1.3.0",
|
|
66
69
|
"pytest-xdist>=3.8.0",
|
|
70
|
+
"socksio>=1.0.0",
|
|
67
71
|
"trustme>=1.1.0",
|
|
68
72
|
]
|
|
69
73
|
docs = [
|
|
@@ -166,9 +170,10 @@ exhaustive = true
|
|
|
166
170
|
layers = [
|
|
167
171
|
"plugin : cli",
|
|
168
172
|
"factory",
|
|
169
|
-
"carrier : dataflow : schema",
|
|
170
|
-
"validation : har_writer : report_formatter : request_builder : response_steps",
|
|
171
|
-
"
|
|
173
|
+
"carrier : dataflow : schema : importers",
|
|
174
|
+
"validation : har_writer : report_formatter : request_builder : response_steps : parallel_stats",
|
|
175
|
+
"body_schema",
|
|
176
|
+
"utils : scoping : redaction",
|
|
172
177
|
"userfunc",
|
|
173
178
|
"models",
|
|
174
179
|
"templates : jsonref",
|
|
@@ -1,16 +1,32 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "pytest-httpchain"
|
|
3
|
-
version = "0.
|
|
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
|
-
|
|
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",
|
|
@@ -56,6 +72,9 @@ dev = [
|
|
|
56
72
|
# the regroup's defense against a user-installed pytest-order.
|
|
57
73
|
"pytest-order>=1.3.0",
|
|
58
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",
|
|
59
78
|
"trustme>=1.1.0",
|
|
60
79
|
]
|
|
61
80
|
docs = [
|
|
@@ -192,9 +211,13 @@ exhaustive = true
|
|
|
192
211
|
layers = [
|
|
193
212
|
"plugin : cli",
|
|
194
213
|
"factory",
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
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",
|
|
198
221
|
"userfunc",
|
|
199
222
|
"models",
|
|
200
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
|
|
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
|
|