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.
- {pytest_api_core-1.1.1/src/pytest_api_core.egg-info → pytest_api_core-1.2.0}/PKG-INFO +101 -8
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/README.md +97 -5
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/pyproject.toml +6 -5
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/__init__.py +1 -1
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/client/api_client.py +121 -10
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/base_settings.py +7 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/config_manager.py +36 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/fixtures/api_fixtures.py +23 -4
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/plugin.py +33 -4
- pytest_api_core-1.2.0/src/pytest_api_core/reporters/html_reporter.py +817 -0
- pytest_api_core-1.2.0/src/pytest_api_core/reporters/templates/report.html +1147 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0/src/pytest_api_core.egg-info}/PKG-INFO +101 -8
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/requires.txt +1 -0
- pytest_api_core-1.1.1/src/pytest_api_core/reporters/html_reporter.py +0 -395
- pytest_api_core-1.1.1/src/pytest_api_core/reporters/templates/report.html +0 -645
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/LICENSE +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/MANIFEST.in +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/setup.cfg +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/assert_utils.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/response_assertions.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/assertions/soft.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/auth/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/auth/auth_handlers.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/client/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/client/api_response.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/config/env_loader.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/fixtures/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/reporters/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/security/__init__.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core/security/redaction.py +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/SOURCES.txt +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/dependency_links.txt +0 -0
- {pytest_api_core-1.1.1 → pytest_api_core-1.2.0}/src/pytest_api_core.egg-info/entry_points.txt +0 -0
- {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.
|
|
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.
|
|
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
|
|
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
|
|
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
|

|
|
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
|
+

|
|
117
|
+
|
|
112
118
|
---
|
|
113
119
|
|
|
114
120
|
## Installation
|
|
115
121
|
|
|
116
122
|
```bash
|
|
117
|
-
pip install pytest-api-core==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.
|
|
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
|
|
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
|
|
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
|
|
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
|

|
|
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
|
+

|
|
50
|
+
|
|
46
51
|
---
|
|
47
52
|
|
|
48
53
|
## Installation
|
|
49
54
|
|
|
50
55
|
```bash
|
|
51
|
-
pip install pytest-api-core==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.
|
|
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
|
|
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.
|
|
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.
|
|
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 = ["
|
|
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.
|
|
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.
|
|
27
|
+
__version__ = "1.2.0"
|
|
28
28
|
__all__ = [
|
|
29
29
|
"APIClient",
|
|
30
30
|
"APIResponse",
|