pytest-pktbin 0.1.0__py3-none-any.whl
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.
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pytest-pktbin
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: pytest fixtures for pktbin: a new capture for each test, to check the traffic it sends.
|
|
5
|
+
Project-URL: Homepage, https://pktbin.com
|
|
6
|
+
Project-URL: Documentation, https://pktbin.com/docs/
|
|
7
|
+
Author: Pktbin
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: network,packet capture,pcap,pytest,testing
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Framework :: Pytest
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Software Development :: Testing
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.11
|
|
24
|
+
Requires-Dist: pktbin<0.2,>=0.1
|
|
25
|
+
Requires-Dist: pytest>=8
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# pytest-pktbin
|
|
29
|
+
|
|
30
|
+
pytest fixtures for [pktbin](https://pypi.org/project/pktbin/). Each test gets a new capture.
|
|
31
|
+
The test sends requests to the capture, then examines them.
|
|
32
|
+
|
|
33
|
+
Python 3.11 or later.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install pytest-pktbin
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Example
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import httpx
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def test_sends_a_user_agent(pktbin_capture):
|
|
46
|
+
httpx.get(pktbin_capture.url("/hello"))
|
|
47
|
+
|
|
48
|
+
details = pktbin_capture.wait_for_request_details(path="/hello")
|
|
49
|
+
assert details.request["user-agent"].startswith("python-httpx/")
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Fixtures
|
|
53
|
+
|
|
54
|
+
| Fixture | Scope | Value |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `pktbin_capture` | test | A new `CaptureSession`. |
|
|
57
|
+
| `pktbin_async_capture` | test | A new `AsyncCaptureSession`, for async tests. |
|
|
58
|
+
| `pktbin_client` | session | The `Client` that creates the captures. |
|
|
59
|
+
|
|
60
|
+
In async tests, use `pktbin_async_capture`. Its methods run on the test's event loop, so the
|
|
61
|
+
loop can send traffic while a method waits. A blocking method stops the loop. The fixture works
|
|
62
|
+
with pytest-asyncio and with anyio.
|
|
63
|
+
|
|
64
|
+
## Failed tests
|
|
65
|
+
|
|
66
|
+
When a test fails, the report lists the first 10 requests of its capture, each with its link,
|
|
67
|
+
then the link to the capture:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
---------------------------- pktbin ----------------------------
|
|
71
|
+
GET https://<id>.de.pktbin.net/hello -> 503 Service Unavailable https://pktbin.com/ca1b2c3/requests?request=11
|
|
72
|
+
GET https://<id>.de.pktbin.net/hello -> 200 OK https://pktbin.com/ca1b2c3/requests?request=23
|
|
73
|
+
pktbin_capture: https://pktbin.com/ca1b2c3
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A new capture is private. The links open it only in a browser that has the owner token. The
|
|
77
|
+
request links never have the token. To show the capture's owner link, which has the token, set
|
|
78
|
+
`pktbin_owner_links`:
|
|
79
|
+
|
|
80
|
+
```ini
|
|
81
|
+
[pytest]
|
|
82
|
+
pktbin_owner_links = true
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Do not set it if other people can read your test logs. Anyone with the owner link can change
|
|
86
|
+
and delete the capture.
|
|
87
|
+
|
|
88
|
+
## Which captures are kept
|
|
89
|
+
|
|
90
|
+
A failed test's capture is kept until it expires, so its links work. A passing test's capture
|
|
91
|
+
is deleted when the test ends: nobody sees it, and it may hold tokens that the test sent. To
|
|
92
|
+
keep them all, set `pktbin_retention`:
|
|
93
|
+
|
|
94
|
+
```ini
|
|
95
|
+
[pytest]
|
|
96
|
+
pktbin_retention = all
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
If a delete fails, for example because pktbin does not answer, the plugin warns. The test
|
|
100
|
+
does not fail.
|
|
101
|
+
|
|
102
|
+
## Configuration
|
|
103
|
+
|
|
104
|
+
| Setting | Meaning |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `pktbin_owner_links` (ini) | `true` shows the owner link of a failed test's capture. |
|
|
107
|
+
| `pktbin_retention` (ini) | Which captures are kept: `failed` (the default), `all` or `none`, as pytest's `tmp_path_retention_policy`. |
|
|
108
|
+
|
|
109
|
+
## Rate limit
|
|
110
|
+
|
|
111
|
+
pktbin limits how many captures one address creates in one minute. If a test suite
|
|
112
|
+
creates more, the client waits until pktbin allows the next capture, and issues a
|
|
113
|
+
`PktbinRateLimitWarning`. The suite is slower, but it does not fail.
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
pytest_pktbin.py,sha256=pyq-HxVSwwEv3KG0J7V8vkHKtOQkWLgNrKBoAjmH2PQ,6545
|
|
2
|
+
pytest_pktbin-0.1.0.dist-info/METADATA,sha256=vFaii9Ybi9KBr05Xtugyex30vRqI9runFQXJzYCScQw,3832
|
|
3
|
+
pytest_pktbin-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
4
|
+
pytest_pktbin-0.1.0.dist-info/entry_points.txt,sha256=l5q_PE5ivm5FFTkBxdL_jajIUsh701D8ZfqVxpN5KC4,34
|
|
5
|
+
pytest_pktbin-0.1.0.dist-info/licenses/LICENSE,sha256=RUAvPU8STsdjPtPfXrHJLfKxIhv0G5fQdeHeR5uOftQ,1063
|
|
6
|
+
pytest_pktbin-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pktbin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pytest_pktbin.py
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
"""pytest fixtures that give each test a new pktbin capture.
|
|
2
|
+
|
|
3
|
+
pytest loads this plugin in each run. The fixtures import pktbin only when a test uses
|
|
4
|
+
them, because the import takes about 0.1 s.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from collections.abc import Generator, Iterator
|
|
10
|
+
from typing import TYPE_CHECKING
|
|
11
|
+
|
|
12
|
+
import pytest
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from pktbin import AsyncCaptureSession, Capture, CaptureSession, Client, Request
|
|
16
|
+
|
|
17
|
+
_CAPTURES = ("pktbin_capture", "pktbin_async_capture")
|
|
18
|
+
|
|
19
|
+
# Which tests' captures are kept at teardown, as pytest's tmp_path_retention_policy.
|
|
20
|
+
_RETENTIONS = ("all", "failed", "none")
|
|
21
|
+
|
|
22
|
+
# Each test's reports so far, by phase, which teardown reads its outcome from.
|
|
23
|
+
_REPORTS = pytest.StashKey[dict[str | None, pytest.TestReport]]()
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def pytest_addoption(parser: pytest.Parser) -> None:
|
|
27
|
+
parser.addini(
|
|
28
|
+
"pktbin_owner_links",
|
|
29
|
+
"Show the capture's owner link, which holds its token, when a test fails. "
|
|
30
|
+
"The default shows the view link only.",
|
|
31
|
+
type="bool",
|
|
32
|
+
default=False,
|
|
33
|
+
)
|
|
34
|
+
parser.addini(
|
|
35
|
+
"pktbin_retention",
|
|
36
|
+
"Which tests' captures are kept when they end: 'failed' (the default) deletes "
|
|
37
|
+
"those of tests that passed, 'all' keeps every capture, 'none' deletes every "
|
|
38
|
+
"capture.",
|
|
39
|
+
default="failed",
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def pytest_configure(config: pytest.Config) -> None:
|
|
44
|
+
retention = config.getini("pktbin_retention")
|
|
45
|
+
if retention not in _RETENTIONS:
|
|
46
|
+
raise pytest.UsageError(
|
|
47
|
+
f"pktbin_retention must be one of {', '.join(_RETENTIONS)}, not {retention!r}"
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _retire(request: pytest.FixtureRequest, client: Client, capture: Capture) -> None:
|
|
52
|
+
"""Deletes a test's capture unless `pktbin_retention` keeps it. A delete that fails
|
|
53
|
+
warns: it doesn't fail the test."""
|
|
54
|
+
import warnings
|
|
55
|
+
|
|
56
|
+
from pktbin import CaptureSession, PktbinError
|
|
57
|
+
|
|
58
|
+
retention = request.config.getini("pktbin_retention")
|
|
59
|
+
reports = request.node.stash.get(_REPORTS, {})
|
|
60
|
+
failed = any(report.failed for report in reports.values())
|
|
61
|
+
if retention == "all" or (retention == "failed" and failed):
|
|
62
|
+
return
|
|
63
|
+
try:
|
|
64
|
+
CaptureSession(client, capture).delete()
|
|
65
|
+
except PktbinError as e:
|
|
66
|
+
warnings.warn(f"Couldn't delete capture {capture.id}: {e}", stacklevel=1)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@pytest.fixture(scope="session")
|
|
70
|
+
def pktbin_client() -> Iterator[Client]:
|
|
71
|
+
"""The client that creates the captures. All tests of a session use it."""
|
|
72
|
+
from pktbin import Client
|
|
73
|
+
|
|
74
|
+
with Client() as client:
|
|
75
|
+
yield client
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@pytest.fixture
|
|
79
|
+
def pktbin_capture(
|
|
80
|
+
request: pytest.FixtureRequest, pktbin_client: Client
|
|
81
|
+
) -> Iterator[CaptureSession]:
|
|
82
|
+
"""A new capture for the test.
|
|
83
|
+
|
|
84
|
+
Send traffic to its `urls.ingest`, then examine the traffic with the methods of the
|
|
85
|
+
capture. If the test fails, the report shows the link to the capture, which is kept.
|
|
86
|
+
A passing test's capture is deleted, unless `pktbin_retention` says otherwise.
|
|
87
|
+
"""
|
|
88
|
+
capture = pktbin_client.create_capture()
|
|
89
|
+
yield capture
|
|
90
|
+
_retire(request, pktbin_client, capture.metadata)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@pytest.fixture
|
|
94
|
+
def pktbin_async_capture(
|
|
95
|
+
request: pytest.FixtureRequest, pktbin_client: Client
|
|
96
|
+
) -> Iterator[AsyncCaptureSession]:
|
|
97
|
+
"""A new capture with async methods, for async tests.
|
|
98
|
+
|
|
99
|
+
The methods run on the event loop of the test, so the loop can send traffic while a
|
|
100
|
+
method waits. A blocking method stops the loop. The fixture itself is not async, so
|
|
101
|
+
it works with pytest-asyncio and with anyio. Its capture is kept or deleted as
|
|
102
|
+
`pktbin_capture`'s is.
|
|
103
|
+
"""
|
|
104
|
+
import anyio
|
|
105
|
+
import httpx
|
|
106
|
+
|
|
107
|
+
from pktbin import AsyncCaptureSession, AsyncClient
|
|
108
|
+
|
|
109
|
+
capture = pktbin_client.create_capture()
|
|
110
|
+
# The client keeps no connections, because they would belong to the test's event
|
|
111
|
+
# loop, which can be closed before teardown.
|
|
112
|
+
client = AsyncClient(limits=httpx.Limits(max_keepalive_connections=0))
|
|
113
|
+
yield AsyncCaptureSession(client, capture.metadata)
|
|
114
|
+
anyio.run(client.aclose)
|
|
115
|
+
_retire(request, pktbin_client, capture.metadata)
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
# The most requests that the report of a failed test lists for each capture.
|
|
119
|
+
_LISTED = 10
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _describe(request: Request) -> str:
|
|
123
|
+
"""The method, target and status of a request, on one line."""
|
|
124
|
+
status = request.status
|
|
125
|
+
answer = f"{status.code} {status.text}" if status else "no answer"
|
|
126
|
+
return f"{request.method} {request.target} -> {answer}"
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _request_lines(
|
|
130
|
+
client: Client, capture: CaptureSession | AsyncCaptureSession
|
|
131
|
+
) -> list[str]:
|
|
132
|
+
"""A line for each of the capture's first requests, with its link."""
|
|
133
|
+
from pktbin import CaptureSession
|
|
134
|
+
|
|
135
|
+
# Read with the session's client, which is sync, for an async capture too.
|
|
136
|
+
requests = CaptureSession(client, capture.metadata).requests()
|
|
137
|
+
lines = [
|
|
138
|
+
f" {_describe(request)} {capture.link(request)}"
|
|
139
|
+
for request in requests[:_LISTED]
|
|
140
|
+
]
|
|
141
|
+
if len(requests) > _LISTED:
|
|
142
|
+
lines.append(f" and {len(requests) - _LISTED} more")
|
|
143
|
+
return lines
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
@pytest.hookimpl(wrapper=True)
|
|
147
|
+
def pytest_runtest_makereport(
|
|
148
|
+
item: pytest.Item, call: pytest.CallInfo[None]
|
|
149
|
+
) -> Generator[None, pytest.TestReport, pytest.TestReport]:
|
|
150
|
+
"""Adds the capture's requests and its link to the report of a failed test."""
|
|
151
|
+
report = yield
|
|
152
|
+
item.stash.setdefault(_REPORTS, {})[report.when] = report
|
|
153
|
+
if report.failed:
|
|
154
|
+
funcargs = getattr(item, "funcargs", {})
|
|
155
|
+
owner = item.config.getini("pktbin_owner_links")
|
|
156
|
+
client = funcargs.get("pktbin_client")
|
|
157
|
+
for name in _CAPTURES:
|
|
158
|
+
capture = funcargs.get(name)
|
|
159
|
+
if capture is None:
|
|
160
|
+
continue
|
|
161
|
+
lines: list[str] = []
|
|
162
|
+
if client is not None and not _sensor_failed(call):
|
|
163
|
+
try:
|
|
164
|
+
lines = _request_lines(client, capture)
|
|
165
|
+
except Exception:
|
|
166
|
+
# The link alone still helps.
|
|
167
|
+
lines = []
|
|
168
|
+
link = (capture.owner_url if owner else None) or capture.urls.view
|
|
169
|
+
report.sections.append(("pktbin", "\n".join([*lines, f"{name}: {link}"])))
|
|
170
|
+
return report
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _sensor_failed(call: pytest.CallInfo[None]) -> bool:
|
|
174
|
+
"""Whether the test failed because the sensor did not answer. Then listing the
|
|
175
|
+
requests would only wait for the client's retries."""
|
|
176
|
+
if call.excinfo is None:
|
|
177
|
+
return False
|
|
178
|
+
from pktbin import PktbinConnectionError, PktbinTimeoutError
|
|
179
|
+
|
|
180
|
+
return call.excinfo.errisinstance((PktbinConnectionError, PktbinTimeoutError))
|