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

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

|
|
109
|
+
|
|
110
|
+
**Request details, redacted secrets, Copy cURL, and timeouts shown as ERROR**
|
|
111
|
+
|
|
112
|
+

|
|
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
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
95
120
|
## Installation
|
|
96
121
|
|
|
97
122
|
```bash
|
|
98
|
-
pip install pytest-api-core==1.
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
|
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
|
+

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

|
|
42
|
+
|
|
43
|
+
**Request details, redacted secrets, Copy cURL, and timeouts shown as ERROR**
|
|
44
|
+
|
|
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
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
29
53
|
## Installation
|
|
30
54
|
|
|
31
55
|
```bash
|
|
32
|
-
pip install pytest-api-core==1.
|
|
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.
|
|
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
|
|
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.
|
|
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",
|
|
@@ -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
|
|
25
|
-
from
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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))
|