pytest-api-core 1.1.1__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.1/src/pytest_api_core.egg-info → pytest_api_core-1.2.0}/PKG-INFO +101 -8
  2. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/README.md +97 -5
  3. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/pyproject.toml +6 -5
  4. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/__init__.py +1 -1
  5. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/client/api_client.py +121 -10
  6. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/base_settings.py +7 -0
  7. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/config_manager.py +36 -0
  8. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/fixtures/api_fixtures.py +23 -4
  9. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/plugin.py +33 -4
  10. pytest_api_core-1.2.0/src/pytest_api_core/reporters/html_reporter.py +817 -0
  11. pytest_api_core-1.2.0/src/pytest_api_core/reporters/templates/report.html +1147 -0
  12. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0/src/pytest_api_core.egg-info}/PKG-INFO +101 -8
  13. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/requires.txt +1 -0
  14. pytest_api_core-1.1.1/src/pytest_api_core/reporters/html_reporter.py +0 -395
  15. pytest_api_core-1.1.1/src/pytest_api_core/reporters/templates/report.html +0 -645
  16. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/LICENSE +0 -0
  17. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/MANIFEST.in +0 -0
  18. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/setup.cfg +0 -0
  19. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/__init__.py +0 -0
  20. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/assert_utils.py +0 -0
  21. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/response_assertions.py +0 -0
  22. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/soft.py +0 -0
  23. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/auth/__init__.py +0 -0
  24. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/auth/auth_handlers.py +0 -0
  25. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/client/__init__.py +0 -0
  26. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/client/api_response.py +0 -0
  27. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/__init__.py +0 -0
  28. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/env_loader.py +0 -0
  29. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/fixtures/__init__.py +0 -0
  30. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/reporters/__init__.py +0 -0
  31. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/security/__init__.py +0 -0
  32. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/security/redaction.py +0 -0
  33. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/SOURCES.txt +0 -0
  34. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/dependency_links.txt +0 -0
  35. {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/entry_points.txt +0 -0
  36. {pytest_api_core-1.1.1 → 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.1
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,12 +82,13 @@ 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
 
@@ -109,18 +111,22 @@ Browse real ones from this repo's CI on the [live reports dashboard](https://git
109
111
 
110
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)
111
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
+
112
118
  ---
113
119
 
114
120
  ## Installation
115
121
 
116
122
  ```bash
117
- pip install pytest-api-core==1.1.1
123
+ pip install pytest-api-core==1.2.0
118
124
  ```
119
125
 
120
126
  With `.env` file support (recommended):
121
127
 
122
128
  ```bash
123
- pip install "pytest-api-core[dotenv]==1.1.1"
129
+ pip install "pytest-api-core[dotenv]==1.2.0"
124
130
  ```
125
131
 
126
132
  ---
@@ -147,6 +153,10 @@ pytest tests/ --api-env=staging
147
153
 
148
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)**.
149
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
+
150
160
  ---
151
161
 
152
162
  ## Configuration
@@ -163,7 +173,7 @@ For full setup instructions — including `pytest.ini`, `config/settings.py`, `c
163
173
  ### Retry policy
164
174
 
165
175
  `APIClient` retries idempotent requests (`GET`, `HEAD`, `OPTIONS`) on `500/502/503/504`
166
- 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 →
167
177
  `settings_module` → built-in default precedence as `base_url`:
168
178
 
169
179
  | Setting | `settings_module` attribute | CLI flag | Env var | Default |
@@ -171,9 +181,31 @@ responses using `urllib3.Retry`. All three knobs follow the same env var → CLI
171
181
  | Max retry attempts | `api_retry_total` | `--api-retry-total` | `API_RETRY_TOTAL` | `3` |
172
182
  | Backoff factor | `api_retry_backoff_factor` | `--api-retry-backoff-factor` | `API_RETRY_BACKOFF_FACTOR` | `0.3` |
173
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` |
174
185
 
175
186
  Backoff factor `0.3` produces sleeps of `0s, 0.3s, 0.6s, 1.2s, ...` between attempts.
176
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
+
177
209
  Example — a flakier staging environment gets more retries and a longer backoff:
178
210
 
179
211
  ```python
@@ -182,18 +214,76 @@ class StagingSettings(BaseSettings):
182
214
  base_url = "https://api.staging.mycompany.com"
183
215
  api_retry_total = 5
184
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
185
219
  ```
186
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
+
187
225
  Or per-run, without touching code:
188
226
 
189
227
  ```bash
190
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
191
237
  ```
192
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()
258
+ ```
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
+
193
264
  To disable retries entirely, pass `retry=None` directly when constructing an
194
265
  `APIClient` yourself (not available as a config option, since "no retries" isn't
195
266
  something you'd want to toggle per environment).
196
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
+
197
287
  ### Key `pytest.ini` options
198
288
 
199
289
  | Option | Description | Default |
@@ -203,6 +293,7 @@ something you'd want to toggle per environment).
203
293
  | `api_dotenv_file` | Path to `.env` file | `.env` |
204
294
  | `api_log_level` | Framework log level | `WARNING` |
205
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 | — |
206
297
  | `api_html_theme` | Report theme: `light` or `dark` | `dark` |
207
298
  | `api_html_title` | Report browser tab title | `API Test Report` |
208
299
  | `api_html_header` | Report page header text | `API Test Report` |
@@ -219,6 +310,8 @@ something you'd want to toggle per environment).
219
310
  | `--api-retry-total` | Override max retry attempts (default: `3`) |
220
311
  | `--api-retry-backoff-factor` | Override retry backoff factor (default: `0.3`) |
221
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`) |
222
315
 
223
316
  ---
224
317
 
@@ -15,12 +15,13 @@
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
 
@@ -43,18 +44,22 @@ Browse real ones from this repo's CI on the [live reports dashboard](https://git
43
44
 
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)
45
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
+
46
51
  ---
47
52
 
48
53
  ## Installation
49
54
 
50
55
  ```bash
51
- pip install pytest-api-core==1.1.1
56
+ pip install pytest-api-core==1.2.0
52
57
  ```
53
58
 
54
59
  With `.env` file support (recommended):
55
60
 
56
61
  ```bash
57
- pip install "pytest-api-core[dotenv]==1.1.1"
62
+ pip install "pytest-api-core[dotenv]==1.2.0"
58
63
  ```
59
64
 
60
65
  ---
@@ -81,6 +86,10 @@ pytest tests/ --api-env=staging
81
86
 
82
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)**.
83
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
+
84
93
  ---
85
94
 
86
95
  ## Configuration
@@ -97,7 +106,7 @@ For full setup instructions — including `pytest.ini`, `config/settings.py`, `c
97
106
  ### Retry policy
98
107
 
99
108
  `APIClient` retries idempotent requests (`GET`, `HEAD`, `OPTIONS`) on `500/502/503/504`
100
- 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 →
101
110
  `settings_module` → built-in default precedence as `base_url`:
102
111
 
103
112
  | Setting | `settings_module` attribute | CLI flag | Env var | Default |
@@ -105,9 +114,31 @@ responses using `urllib3.Retry`. All three knobs follow the same env var → CLI
105
114
  | Max retry attempts | `api_retry_total` | `--api-retry-total` | `API_RETRY_TOTAL` | `3` |
106
115
  | Backoff factor | `api_retry_backoff_factor` | `--api-retry-backoff-factor` | `API_RETRY_BACKOFF_FACTOR` | `0.3` |
107
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` |
108
118
 
109
119
  Backoff factor `0.3` produces sleeps of `0s, 0.3s, 0.6s, 1.2s, ...` between attempts.
110
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
+
111
142
  Example — a flakier staging environment gets more retries and a longer backoff:
112
143
 
113
144
  ```python
@@ -116,18 +147,76 @@ class StagingSettings(BaseSettings):
116
147
  base_url = "https://api.staging.mycompany.com"
117
148
  api_retry_total = 5
118
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
119
152
  ```
120
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
+
121
158
  Or per-run, without touching code:
122
159
 
123
160
  ```bash
124
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
125
170
  ```
126
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()
191
+ ```
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
+
127
197
  To disable retries entirely, pass `retry=None` directly when constructing an
128
198
  `APIClient` yourself (not available as a config option, since "no retries" isn't
129
199
  something you'd want to toggle per environment).
130
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
+
131
220
  ### Key `pytest.ini` options
132
221
 
133
222
  | Option | Description | Default |
@@ -137,6 +226,7 @@ something you'd want to toggle per environment).
137
226
  | `api_dotenv_file` | Path to `.env` file | `.env` |
138
227
  | `api_log_level` | Framework log level | `WARNING` |
139
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 | — |
140
230
  | `api_html_theme` | Report theme: `light` or `dark` | `dark` |
141
231
  | `api_html_title` | Report browser tab title | `API Test Report` |
142
232
  | `api_html_header` | Report page header text | `API Test Report` |
@@ -153,6 +243,8 @@ something you'd want to toggle per environment).
153
243
  | `--api-retry-total` | Override max retry attempts (default: `3`) |
154
244
  | `--api-retry-backoff-factor` | Override retry backoff factor (default: `0.3`) |
155
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`) |
156
248
 
157
249
  ---
158
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.1"
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.1"
27
+ __version__ = "1.2.0"
28
28
  __all__ = [
29
29
  "APIClient",
30
30
  "APIResponse",