pytest-api-core 1.1.0__tar.gz → 1.2.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 (36) hide show
  1. {pytest_api_core-1.1.0/src/pytest_api_core.egg-info → pytest_api_core-1.2.0}/PKG-INFO +120 -8
  2. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/README.md +116 -5
  3. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/pyproject.toml +6 -5
  4. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/__init__.py +1 -1
  5. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/soft.py +32 -17
  6. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/client/api_client.py +121 -10
  7. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/config/base_settings.py +7 -0
  8. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/config/config_manager.py +36 -0
  9. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/fixtures/api_fixtures.py +23 -4
  10. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/plugin.py +33 -4
  11. pytest_api_core-1.2.0/src/pytest_api_core/reporters/html_reporter.py +817 -0
  12. pytest_api_core-1.2.0/src/pytest_api_core/reporters/templates/report.html +1147 -0
  13. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/security/redaction.py +11 -1
  14. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0/src/pytest_api_core.egg-info}/PKG-INFO +120 -8
  15. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/requires.txt +1 -0
  16. pytest_api_core-1.1.0/src/pytest_api_core/reporters/html_reporter.py +0 -395
  17. pytest_api_core-1.1.0/src/pytest_api_core/reporters/templates/report.html +0 -644
  18. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/LICENSE +0 -0
  19. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/MANIFEST.in +0 -0
  20. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/setup.cfg +0 -0
  21. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/__init__.py +0 -0
  22. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/assert_utils.py +0 -0
  23. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/response_assertions.py +0 -0
  24. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/auth/__init__.py +0 -0
  25. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/auth/auth_handlers.py +0 -0
  26. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/client/__init__.py +0 -0
  27. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/client/api_response.py +0 -0
  28. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/config/__init__.py +0 -0
  29. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/config/env_loader.py +0 -0
  30. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/fixtures/__init__.py +0 -0
  31. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/reporters/__init__.py +0 -0
  32. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core/security/__init__.py +0 -0
  33. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/SOURCES.txt +0 -0
  34. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/dependency_links.txt +0 -0
  35. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/entry_points.txt +0 -0
  36. {pytest_api_core-1.1.0 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pytest-api-core
3
- Version: 1.1.0
3
+ Version: 1.2.0
4
4
  Summary: Pytest API automation framework with custom HTML reporting, reusable fixtures, and fluent assertions
5
5
  Author: QA Platform Team
6
6
  License: MIT License
@@ -30,6 +30,7 @@ Project-URL: Repository, https://github.com/sksingh329/pytest-api-core-framework
30
30
  Project-URL: Documentation, https://github.com/sksingh329/pytest-api-core-framework/blob/develop/README.md
31
31
  Project-URL: Bug Tracker, https://github.com/sksingh329/pytest-api-core-framework/issues
32
32
  Project-URL: Changelog, https://github.com/sksingh329/pytest-api-core-framework/blob/develop/CHANGELOG.md
33
+ Project-URL: Template Project, https://github.com/sksingh329/pytest-api-core-template
33
34
  Keywords: pytest,api,testing,automation,html-report
34
35
  Classifier: Development Status :: 5 - Production/Stable
35
36
  Classifier: Framework :: Pytest
@@ -37,14 +38,13 @@ Classifier: Intended Audience :: Developers
37
38
  Classifier: License :: OSI Approved :: MIT License
38
39
  Classifier: Topic :: Software Development :: Testing
39
40
  Classifier: Programming Language :: Python :: 3
40
- Classifier: Programming Language :: Python :: 3.9
41
41
  Classifier: Programming Language :: Python :: 3.10
42
42
  Classifier: Programming Language :: Python :: 3.11
43
43
  Classifier: Programming Language :: Python :: 3.12
44
44
  Classifier: Programming Language :: Python :: 3.13
45
45
  Classifier: Programming Language :: Python :: 3.14
46
46
  Classifier: Operating System :: OS Independent
47
- Requires-Python: >=3.9
47
+ Requires-Python: >=3.10
48
48
  Description-Content-Type: text/markdown
49
49
  License-File: LICENSE
50
50
  Requires-Dist: pytest<10.0,>=7.4
@@ -57,6 +57,7 @@ Requires-Dist: python-dotenv>=1.0; extra == "dotenv"
57
57
  Provides-Extra: dev
58
58
  Requires-Dist: pytest-mock>=3.12; extra == "dev"
59
59
  Requires-Dist: responses>=0.25; extra == "dev"
60
+ Requires-Dist: pytest-xdist>=3.5; extra == "dev"
60
61
  Requires-Dist: black>=24.0; extra == "dev"
61
62
  Requires-Dist: isort>=5.13; extra == "dev"
62
63
  Requires-Dist: mypy>=1.8; extra == "dev"
@@ -81,27 +82,51 @@ Dynamic: license-file
81
82
  - **Auth strategies** — Bearer token, Basic, API Key (header/query), OAuth2 client credentials
82
83
  (need something else, like an OAuth2 refresh-token flow or signed requests? subclass `AuthBase` — see [docs/QUICKSTART.md](docs/QUICKSTART.md#custom-auth-handlers))
83
84
  - **Standalone assertion helpers** — `assert_equal`, `assert_contains`, `assert_matches`, `assert_matches_schema`, etc. for values outside an `APIResponse` — see [docs/QUICKSTART.md](docs/QUICKSTART.md#standalone-assertion-helpers)
84
- - **Configurable retry policy** — max attempts, backoff factor, and retryable methods, overridable per environment (see below)
85
+ - **Configurable retry policy** — max attempts, backoff factor, retryable methods and status codes, overridable per environment; every retried attempt is shown in the report (see below)
85
86
  - **Environment config** — Python `settings.py` classes + `.env` file + env var overrides
86
87
  - **Soft assertions** — `with soft_assertions():` runs every check and fails once with all the failures listed — see [docs/QUICKSTART.md](docs/QUICKSTART.md#soft-assertions)
87
88
  - **Custom HTML report** — self-contained file with charts, filterable table, and request/response details,
88
89
  a "Copy cURL" button per request (secrets stay redacted), an ERROR banner for timeouts / connection errors,
89
- and a per-endpoint latency table (min/p50/p95/max)
90
+ a "↻ N attempts" chip and Attempts tab for calls that were retried, and a per-endpoint latency table
91
+ (min/p50/p95/max, errors, retried)
90
92
  - **Secret redaction** — tokens, passwords, API keys and cookies are masked in logs, assertion messages, and the HTML report (see [Secret redaction](#secret-redaction))
91
93
  - **Auto-registered fixtures** — zero boilerplate in consuming projects
92
94
 
93
95
  ---
94
96
 
97
+ ## Report preview
98
+
99
+ One self-contained HTML file per run (`--api-html-report=reports/report_{timestamp}.html`).
100
+ Browse real ones from this repo's CI on the [live reports dashboard](https://githubreports.apicore.subodhsingh.in/).
101
+
102
+ **Run summary and per-endpoint latency**
103
+
104
+ ![Report overview: pass/fail summary, endpoint performance table with p50/p95 latency, and the filterable results table](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-overview.png)
105
+
106
+ **Every assertion as its own row** — here inside `soft_assertions()`, so all three failures are reported in one run, as one error pointing at the test's own code
107
+
108
+ ![Expanded failed test showing a PATCH request banner, assertion rows with path, expected and actual values, and a single combined soft-assertion failure](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-assertions.png)
109
+
110
+ **Request details, redacted secrets, Copy cURL, and timeouts shown as ERROR**
111
+
112
+ ![Expanded tests showing a token response with the access token redacted, and a request that timed out shown with a red ERROR banner](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-requests.png)
113
+
114
+ **Retries are never hidden** — a call that returned 503 and then passed on retry is flagged with "↻ 2 attempts", the Attempts tab lists every try, and the summary and endpoint table count retried calls so flaky endpoints stand out
115
+
116
+ ![Report showing a Retried calls count, a Retried column in the endpoint table, and an expanded GET request with a 2 attempts chip and an Attempts tab listing 503 retried then 200 final](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-retries.png)
117
+
118
+ ---
119
+
95
120
  ## Installation
96
121
 
97
122
  ```bash
98
- pip install pytest-api-core==1.1.0
123
+ pip install pytest-api-core==1.2.0
99
124
  ```
100
125
 
101
126
  With `.env` file support (recommended):
102
127
 
103
128
  ```bash
104
- pip install "pytest-api-core[dotenv]==1.1.0"
129
+ pip install "pytest-api-core[dotenv]==1.2.0"
105
130
  ```
106
131
 
107
132
  ---
@@ -128,6 +153,10 @@ pytest tests/ --api-env=staging
128
153
 
129
154
  For full setup instructions — including `pytest.ini`, `config/settings.py`, `conftest.py` auth overrides, and CI integration — see **[docs/QUICKSTART.md](docs/QUICKSTART.md)**.
130
155
 
156
+ ### Template project
157
+
158
+ Prefer to start from a working example? **[pytest-api-core-template](https://github.com/sksingh329/pytest-api-core-template)** is a ready-to-use consumer project showing the recommended layout — environment settings, `conftest.py` overrides, sample tests, and report configuration. Clone it (or click **Use this template** on GitHub) and point it at your API.
159
+
131
160
  ---
132
161
 
133
162
  ## Configuration
@@ -144,7 +173,7 @@ For full setup instructions — including `pytest.ini`, `config/settings.py`, `c
144
173
  ### Retry policy
145
174
 
146
175
  `APIClient` retries idempotent requests (`GET`, `HEAD`, `OPTIONS`) on `500/502/503/504`
147
- responses using `urllib3.Retry`. All three knobs follow the same env var → CLI flag →
176
+ responses and on connection errors, using `urllib3.Retry`. All four knobs follow the same env var → CLI flag →
148
177
  `settings_module` → built-in default precedence as `base_url`:
149
178
 
150
179
  | Setting | `settings_module` attribute | CLI flag | Env var | Default |
@@ -152,9 +181,31 @@ responses using `urllib3.Retry`. All three knobs follow the same env var → CLI
152
181
  | Max retry attempts | `api_retry_total` | `--api-retry-total` | `API_RETRY_TOTAL` | `3` |
153
182
  | Backoff factor | `api_retry_backoff_factor` | `--api-retry-backoff-factor` | `API_RETRY_BACKOFF_FACTOR` | `0.3` |
154
183
  | Retryable methods | `api_retry_methods` | `--api-retry-methods` (comma-separated) | `API_RETRY_METHODS` (comma-separated) | `GET,HEAD,OPTIONS` |
184
+ | Retryable status codes | `api_retry_statuses` | `--api-retry-statuses` (comma-separated) | `API_RETRY_STATUSES` (comma-separated) | `500,502,503,504` |
155
185
 
156
186
  Backoff factor `0.3` produces sleeps of `0s, 0.3s, 0.6s, 1.2s, ...` between attempts.
157
187
 
188
+ **When is a request retried?**
189
+
190
+ - A response is retried only when **both** its method is in `api_retry_methods` **and** its
191
+ status is in `api_retry_statuses`.
192
+ - Connection errors (the request never reached the server) are retried for any method, up to
193
+ `api_retry_total`. Read timeouts are retried only for methods in `api_retry_methods`.
194
+ - `429` is not retried by default. Add it to `api_retry_statuses` to retry rate-limited calls;
195
+ urllib3 waits for the `Retry-After` header on `413`/`429`/`503`.
196
+ - Only add `POST`/`PATCH` to `api_retry_methods` if the API makes repeats safe (e.g. an
197
+ `Idempotency-Key` header). Otherwise a retry can create duplicate records.
198
+ - Avoid adding client errors such as `400`/`404` to `api_retry_statuses`. Retrying them hides
199
+ real bugs instead of reporting them.
200
+
201
+ **Retries are never hidden.** A call that fails and then passes on a retry is still reported:
202
+
203
+ - each retried attempt logs a WARNING line, e.g. `↻ GET https://…/orders 503 — attempt 1 failed, retrying`
204
+ - the call's banner in the HTML report shows a `↻ 2 attempts` chip, and an **Attempts** tab lists
205
+ each attempt's status (or connection error) and when it ended
206
+ - the summary shows a **Retried calls** count and the endpoint table a **Retried** column, so
207
+ flaky endpoints stand out even when every test passed
208
+
158
209
  Example — a flakier staging environment gets more retries and a longer backoff:
159
210
 
160
211
  ```python
@@ -163,18 +214,76 @@ class StagingSettings(BaseSettings):
163
214
  base_url = "https://api.staging.mycompany.com"
164
215
  api_retry_total = 5
165
216
  api_retry_backoff_factor = 1.0
217
+ api_retry_statuses = [429, 502, 503, 504] # also retry rate limiting
218
+ api_retry_methods = ["GET", "HEAD", "OPTIONS", "PUT"] # default: GET, HEAD, OPTIONS
166
219
  ```
167
220
 
221
+ `api_retry_methods` replaces the default list rather than adding to it, so keep `GET`, `HEAD`
222
+ and `OPTIONS` in it if you still want them retried. With the settings above, a `PUT` that gets
223
+ `503` is retried, but a `POST` that gets `503` is not, because `POST` isn't in the list.
224
+
168
225
  Or per-run, without touching code:
169
226
 
170
227
  ```bash
171
228
  pytest tests/ --api-env=staging --api-retry-total=5 --api-retry-backoff-factor=1.0
229
+ pytest tests/ --api-retry-methods=GET,HEAD,OPTIONS,PUT --api-retry-statuses=429,502,503,504
230
+ ```
231
+
232
+ Or in CI, with env vars (these override everything else):
233
+
234
+ ```bash
235
+ export API_RETRY_METHODS=GET,HEAD,OPTIONS,PUT
236
+ export API_RETRY_STATUSES=429,502,503,504
237
+ ```
238
+
239
+ **Different policy for one group of endpoints.** The policy applies to a whole client, not
240
+ to single requests. If some endpoints need different rules, build a second client in your
241
+ `conftest.py`:
242
+
243
+ ```python
244
+ import pytest
245
+ from pytest_api_core.client.api_client import APIClient
246
+
247
+ @pytest.fixture(scope="session")
248
+ def payments_client(api_config, auth_provider):
249
+ client = APIClient(
250
+ base_url=api_config["base_url"],
251
+ auth=auth_provider,
252
+ retry_methods=["GET", "POST"], # POST is safe here: the API honours Idempotency-Key
253
+ retry_statuses=[503],
254
+ retry_total=2,
255
+ )
256
+ yield client
257
+ client.close()
172
258
  ```
173
259
 
260
+ For full control, pass a urllib3 policy as `retry=Retry(...)`. A plain `Retry` is converted
261
+ automatically, so its attempts still appear in the report. To keep that for a `Retry` subclass,
262
+ subclass `pytest_api_core.client.api_client.RecordingRetry` instead.
263
+
174
264
  To disable retries entirely, pass `retry=None` directly when constructing an
175
265
  `APIClient` yourself (not available as a config option, since "no retries" isn't
176
266
  something you'd want to toggle per environment).
177
267
 
268
+ ### Report body capture
269
+
270
+ The HTML report keeps the first 2000 characters of each request and response body. A cut-off
271
+ body is marked in the report with its full length. To capture bodies in full, set the limit to
272
+ `0` (or `unlimited`):
273
+
274
+ | `settings_module` attribute | CLI flag | Env var | `APIClient` argument | Default |
275
+ |---|---|---|---|---|
276
+ | `api_body_limit` | `--api-body-limit` | `API_BODY_LIMIT` | `body_limit=` | `2000` (`0` = no limit) |
277
+
278
+ ```bash
279
+ pytest --api-body-limit=0 # this run only
280
+ export API_BODY_LIMIT=unlimited # e.g. in CI
281
+ ```
282
+
283
+ Bodies are redacted before they are cut, whatever the limit. With no limit, report files grow
284
+ with your payloads; JSON bodies over 500,000 characters are shown as raw text rather than the
285
+ collapsible view, to keep the report quick to open.
286
+
178
287
  ### Key `pytest.ini` options
179
288
 
180
289
  | Option | Description | Default |
@@ -184,6 +293,7 @@ something you'd want to toggle per environment).
184
293
  | `api_dotenv_file` | Path to `.env` file | `.env` |
185
294
  | `api_log_level` | Framework log level | `WARNING` |
186
295
  | `api_html_report` | HTML report path (supports `{env}`, `{timestamp}`) | — |
296
+ | `api_html_report_url` | Base URL reports are published under (e.g. in CI). The log then shows `<url>/<report file>` instead of a local `file://` path. The `API_HTML_REPORT_URL` env var overrides it | — |
187
297
  | `api_html_theme` | Report theme: `light` or `dark` | `dark` |
188
298
  | `api_html_title` | Report browser tab title | `API Test Report` |
189
299
  | `api_html_header` | Report page header text | `API Test Report` |
@@ -200,6 +310,8 @@ something you'd want to toggle per environment).
200
310
  | `--api-retry-total` | Override max retry attempts (default: `3`) |
201
311
  | `--api-retry-backoff-factor` | Override retry backoff factor (default: `0.3`) |
202
312
  | `--api-retry-methods` | Override retryable HTTP methods, comma-separated (default: `GET,HEAD,OPTIONS`) |
313
+ | `--api-retry-statuses` | Override retryable response status codes, comma-separated (default: `500,502,503,504`) |
314
+ | `--api-body-limit` | Max characters of each body captured in the report; `0` or `unlimited` = full bodies (default: `2000`) |
203
315
 
204
316
  ---
205
317
 
@@ -15,27 +15,51 @@
15
15
  - **Auth strategies** — Bearer token, Basic, API Key (header/query), OAuth2 client credentials
16
16
  (need something else, like an OAuth2 refresh-token flow or signed requests? subclass `AuthBase` — see [docs/QUICKSTART.md](docs/QUICKSTART.md#custom-auth-handlers))
17
17
  - **Standalone assertion helpers** — `assert_equal`, `assert_contains`, `assert_matches`, `assert_matches_schema`, etc. for values outside an `APIResponse` — see [docs/QUICKSTART.md](docs/QUICKSTART.md#standalone-assertion-helpers)
18
- - **Configurable retry policy** — max attempts, backoff factor, and retryable methods, overridable per environment (see below)
18
+ - **Configurable retry policy** — max attempts, backoff factor, retryable methods and status codes, overridable per environment; every retried attempt is shown in the report (see below)
19
19
  - **Environment config** — Python `settings.py` classes + `.env` file + env var overrides
20
20
  - **Soft assertions** — `with soft_assertions():` runs every check and fails once with all the failures listed — see [docs/QUICKSTART.md](docs/QUICKSTART.md#soft-assertions)
21
21
  - **Custom HTML report** — self-contained file with charts, filterable table, and request/response details,
22
22
  a "Copy cURL" button per request (secrets stay redacted), an ERROR banner for timeouts / connection errors,
23
- and a per-endpoint latency table (min/p50/p95/max)
23
+ a "↻ N attempts" chip and Attempts tab for calls that were retried, and a per-endpoint latency table
24
+ (min/p50/p95/max, errors, retried)
24
25
  - **Secret redaction** — tokens, passwords, API keys and cookies are masked in logs, assertion messages, and the HTML report (see [Secret redaction](#secret-redaction))
25
26
  - **Auto-registered fixtures** — zero boilerplate in consuming projects
26
27
 
27
28
  ---
28
29
 
30
+ ## Report preview
31
+
32
+ One self-contained HTML file per run (`--api-html-report=reports/report_{timestamp}.html`).
33
+ Browse real ones from this repo's CI on the [live reports dashboard](https://githubreports.apicore.subodhsingh.in/).
34
+
35
+ **Run summary and per-endpoint latency**
36
+
37
+ ![Report overview: pass/fail summary, endpoint performance table with p50/p95 latency, and the filterable results table](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-overview.png)
38
+
39
+ **Every assertion as its own row** — here inside `soft_assertions()`, so all three failures are reported in one run, as one error pointing at the test's own code
40
+
41
+ ![Expanded failed test showing a PATCH request banner, assertion rows with path, expected and actual values, and a single combined soft-assertion failure](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-assertions.png)
42
+
43
+ **Request details, redacted secrets, Copy cURL, and timeouts shown as ERROR**
44
+
45
+ ![Expanded tests showing a token response with the access token redacted, and a request that timed out shown with a red ERROR banner](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-requests.png)
46
+
47
+ **Retries are never hidden** — a call that returned 503 and then passed on retry is flagged with "↻ 2 attempts", the Attempts tab lists every try, and the summary and endpoint table count retried calls so flaky endpoints stand out
48
+
49
+ ![Report showing a Retried calls count, a Retried column in the endpoint table, and an expanded GET request with a 2 attempts chip and an Attempts tab listing 503 retried then 200 final](https://raw.githubusercontent.com/sksingh329/pytest-api-core-framework/develop/docs/images/report-retries.png)
50
+
51
+ ---
52
+
29
53
  ## Installation
30
54
 
31
55
  ```bash
32
- pip install pytest-api-core==1.1.0
56
+ pip install pytest-api-core==1.2.0
33
57
  ```
34
58
 
35
59
  With `.env` file support (recommended):
36
60
 
37
61
  ```bash
38
- pip install "pytest-api-core[dotenv]==1.1.0"
62
+ pip install "pytest-api-core[dotenv]==1.2.0"
39
63
  ```
40
64
 
41
65
  ---
@@ -62,6 +86,10 @@ pytest tests/ --api-env=staging
62
86
 
63
87
  For full setup instructions — including `pytest.ini`, `config/settings.py`, `conftest.py` auth overrides, and CI integration — see **[docs/QUICKSTART.md](docs/QUICKSTART.md)**.
64
88
 
89
+ ### Template project
90
+
91
+ Prefer to start from a working example? **[pytest-api-core-template](https://github.com/sksingh329/pytest-api-core-template)** is a ready-to-use consumer project showing the recommended layout — environment settings, `conftest.py` overrides, sample tests, and report configuration. Clone it (or click **Use this template** on GitHub) and point it at your API.
92
+
65
93
  ---
66
94
 
67
95
  ## Configuration
@@ -78,7 +106,7 @@ For full setup instructions — including `pytest.ini`, `config/settings.py`, `c
78
106
  ### Retry policy
79
107
 
80
108
  `APIClient` retries idempotent requests (`GET`, `HEAD`, `OPTIONS`) on `500/502/503/504`
81
- responses using `urllib3.Retry`. All three knobs follow the same env var → CLI flag →
109
+ responses and on connection errors, using `urllib3.Retry`. All four knobs follow the same env var → CLI flag →
82
110
  `settings_module` → built-in default precedence as `base_url`:
83
111
 
84
112
  | Setting | `settings_module` attribute | CLI flag | Env var | Default |
@@ -86,9 +114,31 @@ responses using `urllib3.Retry`. All three knobs follow the same env var → CLI
86
114
  | Max retry attempts | `api_retry_total` | `--api-retry-total` | `API_RETRY_TOTAL` | `3` |
87
115
  | Backoff factor | `api_retry_backoff_factor` | `--api-retry-backoff-factor` | `API_RETRY_BACKOFF_FACTOR` | `0.3` |
88
116
  | Retryable methods | `api_retry_methods` | `--api-retry-methods` (comma-separated) | `API_RETRY_METHODS` (comma-separated) | `GET,HEAD,OPTIONS` |
117
+ | Retryable status codes | `api_retry_statuses` | `--api-retry-statuses` (comma-separated) | `API_RETRY_STATUSES` (comma-separated) | `500,502,503,504` |
89
118
 
90
119
  Backoff factor `0.3` produces sleeps of `0s, 0.3s, 0.6s, 1.2s, ...` between attempts.
91
120
 
121
+ **When is a request retried?**
122
+
123
+ - A response is retried only when **both** its method is in `api_retry_methods` **and** its
124
+ status is in `api_retry_statuses`.
125
+ - Connection errors (the request never reached the server) are retried for any method, up to
126
+ `api_retry_total`. Read timeouts are retried only for methods in `api_retry_methods`.
127
+ - `429` is not retried by default. Add it to `api_retry_statuses` to retry rate-limited calls;
128
+ urllib3 waits for the `Retry-After` header on `413`/`429`/`503`.
129
+ - Only add `POST`/`PATCH` to `api_retry_methods` if the API makes repeats safe (e.g. an
130
+ `Idempotency-Key` header). Otherwise a retry can create duplicate records.
131
+ - Avoid adding client errors such as `400`/`404` to `api_retry_statuses`. Retrying them hides
132
+ real bugs instead of reporting them.
133
+
134
+ **Retries are never hidden.** A call that fails and then passes on a retry is still reported:
135
+
136
+ - each retried attempt logs a WARNING line, e.g. `↻ GET https://…/orders 503 — attempt 1 failed, retrying`
137
+ - the call's banner in the HTML report shows a `↻ 2 attempts` chip, and an **Attempts** tab lists
138
+ each attempt's status (or connection error) and when it ended
139
+ - the summary shows a **Retried calls** count and the endpoint table a **Retried** column, so
140
+ flaky endpoints stand out even when every test passed
141
+
92
142
  Example — a flakier staging environment gets more retries and a longer backoff:
93
143
 
94
144
  ```python
@@ -97,18 +147,76 @@ class StagingSettings(BaseSettings):
97
147
  base_url = "https://api.staging.mycompany.com"
98
148
  api_retry_total = 5
99
149
  api_retry_backoff_factor = 1.0
150
+ api_retry_statuses = [429, 502, 503, 504] # also retry rate limiting
151
+ api_retry_methods = ["GET", "HEAD", "OPTIONS", "PUT"] # default: GET, HEAD, OPTIONS
100
152
  ```
101
153
 
154
+ `api_retry_methods` replaces the default list rather than adding to it, so keep `GET`, `HEAD`
155
+ and `OPTIONS` in it if you still want them retried. With the settings above, a `PUT` that gets
156
+ `503` is retried, but a `POST` that gets `503` is not, because `POST` isn't in the list.
157
+
102
158
  Or per-run, without touching code:
103
159
 
104
160
  ```bash
105
161
  pytest tests/ --api-env=staging --api-retry-total=5 --api-retry-backoff-factor=1.0
162
+ pytest tests/ --api-retry-methods=GET,HEAD,OPTIONS,PUT --api-retry-statuses=429,502,503,504
163
+ ```
164
+
165
+ Or in CI, with env vars (these override everything else):
166
+
167
+ ```bash
168
+ export API_RETRY_METHODS=GET,HEAD,OPTIONS,PUT
169
+ export API_RETRY_STATUSES=429,502,503,504
170
+ ```
171
+
172
+ **Different policy for one group of endpoints.** The policy applies to a whole client, not
173
+ to single requests. If some endpoints need different rules, build a second client in your
174
+ `conftest.py`:
175
+
176
+ ```python
177
+ import pytest
178
+ from pytest_api_core.client.api_client import APIClient
179
+
180
+ @pytest.fixture(scope="session")
181
+ def payments_client(api_config, auth_provider):
182
+ client = APIClient(
183
+ base_url=api_config["base_url"],
184
+ auth=auth_provider,
185
+ retry_methods=["GET", "POST"], # POST is safe here: the API honours Idempotency-Key
186
+ retry_statuses=[503],
187
+ retry_total=2,
188
+ )
189
+ yield client
190
+ client.close()
106
191
  ```
107
192
 
193
+ For full control, pass a urllib3 policy as `retry=Retry(...)`. A plain `Retry` is converted
194
+ automatically, so its attempts still appear in the report. To keep that for a `Retry` subclass,
195
+ subclass `pytest_api_core.client.api_client.RecordingRetry` instead.
196
+
108
197
  To disable retries entirely, pass `retry=None` directly when constructing an
109
198
  `APIClient` yourself (not available as a config option, since "no retries" isn't
110
199
  something you'd want to toggle per environment).
111
200
 
201
+ ### Report body capture
202
+
203
+ The HTML report keeps the first 2000 characters of each request and response body. A cut-off
204
+ body is marked in the report with its full length. To capture bodies in full, set the limit to
205
+ `0` (or `unlimited`):
206
+
207
+ | `settings_module` attribute | CLI flag | Env var | `APIClient` argument | Default |
208
+ |---|---|---|---|---|
209
+ | `api_body_limit` | `--api-body-limit` | `API_BODY_LIMIT` | `body_limit=` | `2000` (`0` = no limit) |
210
+
211
+ ```bash
212
+ pytest --api-body-limit=0 # this run only
213
+ export API_BODY_LIMIT=unlimited # e.g. in CI
214
+ ```
215
+
216
+ Bodies are redacted before they are cut, whatever the limit. With no limit, report files grow
217
+ with your payloads; JSON bodies over 500,000 characters are shown as raw text rather than the
218
+ collapsible view, to keep the report quick to open.
219
+
112
220
  ### Key `pytest.ini` options
113
221
 
114
222
  | Option | Description | Default |
@@ -118,6 +226,7 @@ something you'd want to toggle per environment).
118
226
  | `api_dotenv_file` | Path to `.env` file | `.env` |
119
227
  | `api_log_level` | Framework log level | `WARNING` |
120
228
  | `api_html_report` | HTML report path (supports `{env}`, `{timestamp}`) | — |
229
+ | `api_html_report_url` | Base URL reports are published under (e.g. in CI). The log then shows `<url>/<report file>` instead of a local `file://` path. The `API_HTML_REPORT_URL` env var overrides it | — |
121
230
  | `api_html_theme` | Report theme: `light` or `dark` | `dark` |
122
231
  | `api_html_title` | Report browser tab title | `API Test Report` |
123
232
  | `api_html_header` | Report page header text | `API Test Report` |
@@ -134,6 +243,8 @@ something you'd want to toggle per environment).
134
243
  | `--api-retry-total` | Override max retry attempts (default: `3`) |
135
244
  | `--api-retry-backoff-factor` | Override retry backoff factor (default: `0.3`) |
136
245
  | `--api-retry-methods` | Override retryable HTTP methods, comma-separated (default: `GET,HEAD,OPTIONS`) |
246
+ | `--api-retry-statuses` | Override retryable response status codes, comma-separated (default: `500,502,503,504`) |
247
+ | `--api-body-limit` | Max characters of each body captured in the report; `0` or `unlimited` = full bodies (default: `2000`) |
137
248
 
138
249
  ---
139
250
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pytest-api-core"
7
- version = "1.1.0"
7
+ version = "1.2.0"
8
8
  description = "Pytest API automation framework with custom HTML reporting, reusable fixtures, and fluent assertions"
9
9
  readme = "README.md"
10
10
  license = { file = "LICENSE" }
@@ -17,7 +17,6 @@ classifiers = [
17
17
  "License :: OSI Approved :: MIT License",
18
18
  "Topic :: Software Development :: Testing",
19
19
  "Programming Language :: Python :: 3",
20
- "Programming Language :: Python :: 3.9",
21
20
  "Programming Language :: Python :: 3.10",
22
21
  "Programming Language :: Python :: 3.11",
23
22
  "Programming Language :: Python :: 3.12",
@@ -25,7 +24,7 @@ classifiers = [
25
24
  "Programming Language :: Python :: 3.14",
26
25
  "Operating System :: OS Independent",
27
26
  ]
28
- requires-python = ">=3.9"
27
+ requires-python = ">=3.10"
29
28
  dependencies = [
30
29
  "pytest>=7.4,<10.0",
31
30
  "requests>=2.31,<3.0",
@@ -41,6 +40,7 @@ dotenv = [
41
40
  dev = [
42
41
  "pytest-mock>=3.12",
43
42
  "responses>=0.25",
43
+ "pytest-xdist>=3.5",
44
44
  "black>=24.0",
45
45
  "isort>=5.13",
46
46
  "mypy>=1.8",
@@ -57,6 +57,7 @@ Repository = "https://github.com/sksingh329/pytest-api-core-framework"
57
57
  Documentation = "https://github.com/sksingh329/pytest-api-core-framework/blob/develop/README.md"
58
58
  "Bug Tracker" = "https://github.com/sksingh329/pytest-api-core-framework/issues"
59
59
  Changelog = "https://github.com/sksingh329/pytest-api-core-framework/blob/develop/CHANGELOG.md"
60
+ "Template Project" = "https://github.com/sksingh329/pytest-api-core-template"
60
61
 
61
62
  [tool.setuptools.packages.find]
62
63
  where = ["src"]
@@ -66,13 +67,13 @@ pytest_api_core = ["reporters/templates/*.html"]
66
67
 
67
68
  [tool.black]
68
69
  line-length = 100
69
- target-version = ["py39"]
70
+ target-version = ["py310"]
70
71
 
71
72
  [tool.isort]
72
73
  profile = "black"
73
74
  line_length = 100
74
75
 
75
76
  [tool.mypy]
76
- python_version = "3.9"
77
+ python_version = "3.10"
77
78
  strict = true
78
79
  ignore_missing_imports = true
@@ -24,7 +24,7 @@ from pytest_api_core.client.api_client import APIClient
24
24
  from pytest_api_core.client.api_response import APIResponse
25
25
  from pytest_api_core.security.redaction import add_sensitive_keys, register_secret
26
26
 
27
- __version__ = "1.1.0"
27
+ __version__ = "1.2.0"
28
28
  __all__ = [
29
29
  "APIClient",
30
30
  "APIResponse",
@@ -21,9 +21,8 @@ If the block raises some other exception, that exception propagates unchanged.
21
21
 
22
22
  from __future__ import annotations
23
23
 
24
- from contextlib import contextmanager
25
- from contextvars import ContextVar
26
- from typing import Iterator
24
+ from contextvars import ContextVar, Token
25
+ from types import TracebackType
27
26
 
28
27
  _collector: ContextVar[list[str] | None] = ContextVar("pytest_api_core_soft", default=None)
29
28
 
@@ -48,17 +47,33 @@ def _format(failures: list[str]) -> str:
48
47
  return "\n".join(lines)
49
48
 
50
49
 
51
- @contextmanager
52
- def soft_assertions() -> Iterator[None]:
53
- """Collect assertion failures in the block and raise one combined AssertionError."""
54
- if _collector.get() is not None:
55
- yield # nested: the outer block collects and raises
56
- return
57
- failures: list[str] = []
58
- token = _collector.set(failures)
59
- try:
60
- yield
61
- finally:
62
- _collector.reset(token)
63
- if failures:
64
- raise AssertionError(_format(failures))
50
+ class soft_assertions: # noqa: N801 — used like a function: ``with soft_assertions():``
51
+ """Collect assertion failures in the block and raise one combined AssertionError.
52
+
53
+ A class rather than ``@contextmanager`` so the raising frame can be hidden
54
+ from pytest tracebacks: the failure then points at the test's ``with`` line
55
+ instead of framework / ``contextlib`` internals.
56
+ """
57
+
58
+ def __init__(self) -> None:
59
+ self._failures: list[str] = []
60
+ self._token: Token[list[str] | None] | None = None
61
+
62
+ def __enter__(self) -> None:
63
+ if _collector.get() is None: # nested blocks report through the outermost one
64
+ self._failures = []
65
+ self._token = _collector.set(self._failures)
66
+
67
+ def __exit__(
68
+ self,
69
+ exc_type: type[BaseException] | None,
70
+ exc: BaseException | None,
71
+ tb: TracebackType | None,
72
+ ) -> None: # None: never swallows an exception raised inside the block
73
+ __tracebackhide__ = True # noqa: F841 — read by pytest
74
+ if self._token is None:
75
+ return
76
+ _collector.reset(self._token)
77
+ self._token = None
78
+ if exc_type is None and self._failures:
79
+ raise AssertionError(_format(self._failures))