pytest-state-guard 0.1.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_state_guard-0.1.0/LICENSE +21 -0
- pytest_state_guard-0.1.0/PKG-INFO +275 -0
- pytest_state_guard-0.1.0/README.md +253 -0
- pytest_state_guard-0.1.0/pyproject.toml +44 -0
- pytest_state_guard-0.1.0/setup.cfg +4 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/__init__.py +4 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/executor.py +208 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/ledger.py +413 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/models.py +220 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/owners.py +93 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/plugin.py +678 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/policy.py +434 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/py.typed +0 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard/reporting.py +138 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard.egg-info/PKG-INFO +275 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard.egg-info/SOURCES.txt +18 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard.egg-info/dependency_links.txt +1 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard.egg-info/entry_points.txt +2 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard.egg-info/requires.txt +1 -0
- pytest_state_guard-0.1.0/src/pytest_state_guard.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 bitbyrizbit
|
|
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.
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pytest-state-guard
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Deterministic concurrency auditor for ThreadPoolExecutor task lifetimes against pytest owners
|
|
5
|
+
Author: pytest-state-guard contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://github.com/bitbyrizbit/pytest-state-guard
|
|
8
|
+
Project-URL: Issues, https://github.com/bitbyrizbit/pytest-state-guard/issues
|
|
9
|
+
Classifier: Framework :: Pytest
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Classifier: Topic :: Software Development :: Testing
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: pytest>=9.1.1
|
|
21
|
+
Dynamic: license-file
|
|
22
|
+
|
|
23
|
+
# pytest-state-guard
|
|
24
|
+
|
|
25
|
+
[](https://opensource.org/licenses/MIT)
|
|
26
|
+
|
|
27
|
+
A pytest plugin auditing `ThreadPoolExecutor` task lifetimes against fixture and test owner boundaries.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## The test passed. The work didn't stop.
|
|
32
|
+
|
|
33
|
+
Pytest evaluates assertions, executes fixture teardowns, and moves smoothly to the next test in the suite. But if a test function or fixture submitted a callable to a `concurrent.futures.ThreadPoolExecutor` and did not explicitly wait on `Future.result()` or shut down the executor with `wait=True`, the submitted work may remain queued or actively executing past the owner's boundary.
|
|
34
|
+
|
|
35
|
+
Depending on operating system scheduling, the submitted callable may have completed unnoticed, may still be queued waiting for a worker, or may be actively mutating process-level state while a subsequent test assumes a clean environment.
|
|
36
|
+
|
|
37
|
+
Consider an illustrative scenario: a test submits background work and exits cleanly in mere milliseconds. Several tests later, an intermittent flake occurs because an orphaned thread from that earlier test was still executing and wrote into shared memory.
|
|
38
|
+
|
|
39
|
+
`pytest-state-guard` identifies this lifecycle mismatch. It instruments `ThreadPoolExecutor.submit` to capture task provenance, records observed lifecycle transitions into an append-only event ledger with monotonic sequence numbers, and evaluates task lifetimes against owner finalization boundaries using a formal policy engine.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## What It Does — and What It Does Not Do
|
|
44
|
+
|
|
45
|
+
### What State Guard Does
|
|
46
|
+
- **Instruments Task Submission:** Intercepts `ThreadPoolExecutor.submit` dynamically during the pytest session to bind task provenance to the active owner context.
|
|
47
|
+
- **Enforces Monotonic Ordering:** Commits every observed, tracked submission, start, exit, and finalization event to a thread-safe, append-only in-memory ledger.
|
|
48
|
+
- **Classifies Against Boundaries:** Evaluates whether submitted callables completed before their submitter was finalized, remained outstanding, or started execution after owner teardown.
|
|
49
|
+
- **Surfaces Failures Without Masking:** Reports violations in test teardowns (`=== ERRORS ===`) and the session summary without overwriting original call assertions (`=== FAILURES ===`) or swallowing upstream exceptions.
|
|
50
|
+
|
|
51
|
+
### What State Guard Deliberately Does Not Do
|
|
52
|
+
- **It does not terminate threads:** State Guard is an auditor, not an execution sandbox. It will not forcibly kill threads, cancel running callables, or shut down executors.
|
|
53
|
+
- **It does not isolate memory or prevent races:** It does not intercept memory writes or prevent data races in shared state. It does not detect every concurrency defect.
|
|
54
|
+
- **It does not instrument other concurrency primitives:** Raw `threading.Thread`, `multiprocessing`, `asyncio` loops, and third-party thread pools are out of scope.
|
|
55
|
+
- **Physical scheduling is non-deterministic; auditing is not:** State Guard does not claim that physical thread scheduling is deterministic. It guarantees that ledger event commitment, boundary snapshots, and policy classifications are strictly deterministic for any observed event sequence.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Task Provenance: The Submitter Owns the Task
|
|
60
|
+
|
|
61
|
+
In concurrent systems, an executor is merely an execution mechanism—often a shared, long-lived resource configured across multiple tests or fixtures. The entity responsible for the existence and lifetime of a task is the submitter.
|
|
62
|
+
|
|
63
|
+
State Guard establishes ownership through two primary scopes:
|
|
64
|
+
|
|
65
|
+
1. **Test Call Owners:** Bound to the test item during its `pytest_runtest_call` phase and finalized by the `pytest_runtest_teardown` hookwrapper after teardown processing (including fixture teardown finalizers).
|
|
66
|
+
2. **Fixture Owners:** Bound to fixture invocations during `pytest_fixture_setup` across all fixture scopes (`function`, `class`, `module`, `package`, and `session`), and finalized through `pytest_fixture_post_finalizer` after that fixture's teardown logic has completed. State Guard does not track arbitrary teardown code beyond this hook-defined boundary.
|
|
67
|
+
|
|
68
|
+
Ownership is propagated via context-local storage (`contextvars.ContextVar`). When a test or fixture calls `executor.submit(fn, *args, **kwargs)`, State Guard captures the active owner ID, issues a UUID for the task, and commits a submission reservation event before delegating to the real executor.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## The Event Ledger & Committed Ordering
|
|
73
|
+
|
|
74
|
+
Physical time is unreliable for concurrent auditing. State Guard relies on monotonic event sequence IDs assigned under an atomic lock. All sequence identifiers ($S_*$) represent **committed ledger sequence numbers**, not physical timestamps or hardware clock readings. State Guard establishes the deterministic order in which observations were committed, not the exact physical instants a thread started or completed.
|
|
75
|
+
|
|
76
|
+
The ledger records the lifecycle evidence State Guard observes:
|
|
77
|
+
|
|
78
|
+
- **Owner Finalization Boundary ($S_F$):** The sequence ID committed at the owner's teardown boundary (in `pytest_runtest_teardown` for test items, or `pytest_fixture_post_finalizer` for fixtures).
|
|
79
|
+
- **Submission Window ($S_{inv} \to S_{ret}$ / $S_{raise}$):** $S_{inv}$ is the submission-reservation sequence ID committed before delegating to the real executor; $S_{ret}$ or $S_{raise}$ is committed when `submit()` returns a `Future` or raises an exception.
|
|
80
|
+
- **Callable Lifecycle ($S_{start} \to S_{exit}$):** Committed when the wrapper begins executing the user callable and when it exits (by return or exception).
|
|
81
|
+
- **Future Observations ($S_{done}$ / $S_{cancel}$):** Committed when done-callbacks or cancellation were observed (noting that callback observation is not the exact physical settlement instant).
|
|
82
|
+
|
|
83
|
+
Policy evaluation compares observed evidence against the committed finalization boundary $S_F$.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Policy Classifications & Severity
|
|
88
|
+
|
|
89
|
+
Every task tracked by State Guard is classified according to its committed sequence history:
|
|
90
|
+
|
|
91
|
+
| Classification | Severity | Semantic Description |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| `NO_OUTSTANDING_TASKS` | `CLEAN` | No task remains outstanding at the owner finalization boundary (tasks may have completed or been cancelled prior to finalization). |
|
|
94
|
+
| `COMPLETED_BEFORE_FINALIZATION` | `CLEAN` | Callable started and exited before owner finalization ($S_{exit} < S_F$). |
|
|
95
|
+
| `CANCELLED_BEFORE_START` | `CLEAN` | Future cancellation committed before finalization and before callable started. |
|
|
96
|
+
| `OUTSTANDING_TASK` | `VIOLATION` | Submission returned before finalization, but callable never started ($S_{ret} < S_F$). |
|
|
97
|
+
| `CALLABLE_NOT_EXITED` | `VIOLATION` | Callable started before finalization but did not exit before finalization. |
|
|
98
|
+
| `EXECUTION_AFTER_OWNER_FINALIZATION` | `VIOLATION` | Callable began execution after owner finalization ($S_{start} > S_F$). |
|
|
99
|
+
| `EXIT_COMMITTED_AFTER_FINALIZATION` | `VIOLATION` | Callable started before finalization but exited after finalization ($S_{exit} > S_F$). |
|
|
100
|
+
| `POST_LIFETIME_SUBMISSION` | `VIOLATION` | Task submitted after owner was already finalized ($S_{inv} > S_F$). |
|
|
101
|
+
| `SUBMISSION_UNRESOLVED` | `UNCERTAIN` | `submit()` did not return or raise before finalization. |
|
|
102
|
+
| `SUBMISSION_FAILED_UNVERIFIED` | `UNCERTAIN` | `submit()` raised before finalization; work item enqueue state unverified. |
|
|
103
|
+
|
|
104
|
+
### Preserving Boundary Evidence
|
|
105
|
+
- **Uncertainty is Advisory:** Submissions that were in flight when an owner finalized remain `SUBMISSION_UNRESOLVED` even if `submit()` subsequently returns. Uncertain findings are advisory: they are rendered in an advisory section of the terminal summary and do not automatically cause test failures.
|
|
106
|
+
- **Finding Identity Stability:** If an unresolved task subsequently begins execution after finalization, its classification evolves to `EXECUTION_AFTER_OWNER_FINALIZATION` while retaining its stable finding identifier.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Reporting Architecture
|
|
111
|
+
|
|
112
|
+
### 1. Per-Test Teardown Errors
|
|
113
|
+
Findings originating from test functions or function-scoped fixtures are attributed directly to that test item:
|
|
114
|
+
- **Test Passed:** Marked failed in teardown, appearing under `=== ERRORS ===` as `ERROR at teardown of <nodeid>`.
|
|
115
|
+
- **Test Failed:** If the test call itself failed (for example, an assertion failure), the call failure remains visible under `=== FAILURES ===` with its complete traceback, while concurrency violations appear under `=== ERRORS ===`.
|
|
116
|
+
- **Teardown Already Failed:** If the test teardown already failed (for example, an exception in a fixture finalizer), State Guard preserves the original teardown error representation and chains its violation details using a chained terminal representation (`ChainedTerminalRepr`) without overwriting the fixture error.
|
|
117
|
+
|
|
118
|
+
### 2. Session Audit Summary
|
|
119
|
+
Class, module, package, and session-scoped fixtures cannot be attributed to an arbitrary single test. Their findings are audited at session finish and rendered in the terminal summary by `pytest_terminal_summary`.
|
|
120
|
+
|
|
121
|
+
### 3. Exit Code Promotion
|
|
122
|
+
If all test assertions passed but State Guard detected concurrency violations, the session exit code is promoted to `pytest.ExitCode.TESTS_FAILED` (`1`). Pre-existing nonzero exit codes (such as assertion failures or interrupts) are preserved.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Usage Example
|
|
127
|
+
|
|
128
|
+
### An Illustrative Leaky Test
|
|
129
|
+
The following test submits work to a `ThreadPoolExecutor` and uses synchronization to guarantee that the worker callable has started before the test call finishes. In the illustrated execution, this demonstrates a worker remaining active across the owner finalization boundary.
|
|
130
|
+
|
|
131
|
+
*(Note: The bounded timeout on `release.wait(timeout=2.0)` ensures that worker threads safely terminate without hanging the test process, but it also means that under arbitrary operating system scheduling—such as thread suspension—this specific outcome is not guaranteed. This example deliberately demonstrates an unjoined background worker to illustrate State Guard's detection; it is an anti-pattern for production test suites.)*
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
import threading
|
|
135
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
136
|
+
|
|
137
|
+
started = threading.Event()
|
|
138
|
+
release = threading.Event()
|
|
139
|
+
|
|
140
|
+
def worker():
|
|
141
|
+
started.set()
|
|
142
|
+
# Bounded wait allows the thread to safely terminate if release is never set:
|
|
143
|
+
release.wait(timeout=2.0)
|
|
144
|
+
|
|
145
|
+
def test_background_worker():
|
|
146
|
+
executor = ThreadPoolExecutor(max_workers=1)
|
|
147
|
+
executor.submit(worker)
|
|
148
|
+
|
|
149
|
+
# Synchronize: guarantee the worker callable has started execution
|
|
150
|
+
assert started.wait(timeout=1.0), "Worker failed to start"
|
|
151
|
+
|
|
152
|
+
# The test passes assertions, but the worker is still active:
|
|
153
|
+
assert True
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Pytest Output (Illustrative)
|
|
157
|
+
Because physical thread scheduling is non-deterministic, the sample output below represents one possible illustrative execution. If scheduling delays the test thread until the worker timeout expires, an alternate classification (such as `COMPLETED_BEFORE_FINALIZATION`) could be observed instead. Total process duration may reflect background workers concluding before process exit.
|
|
158
|
+
|
|
159
|
+
```text
|
|
160
|
+
==================================== ERRORS ====================================
|
|
161
|
+
_______________________ ERROR at teardown of test_background_worker _______________________
|
|
162
|
+
---------------- State Guard Teardown Violation: TEST_CALL [test_demo.py::test_background_worker] ----------------
|
|
163
|
+
Owner ID: 3b9a1c4e-6e8d-4f1a-b2c3-9d8e7f6a5b4c
|
|
164
|
+
Owner Finalized Sequence: 42 (created at seq 38)
|
|
165
|
+
|
|
166
|
+
* Finding: f-3b9a1c4e-001
|
|
167
|
+
Classification: CALLABLE_NOT_EXITED
|
|
168
|
+
Task ID: t-8a7b6c5d-1122-3344
|
|
169
|
+
Evidence: Callable started at seq 40 but did not exit before owner finalization (seq 42).
|
|
170
|
+
Sequences: 40, 42
|
|
171
|
+
|
|
172
|
+
=========================== short test summary info ============================
|
|
173
|
+
ERROR test_demo.py::test_background_worker - State Guard Teardown Violation: TEST_CALL
|
|
174
|
+
============================== 1 error in 0.12s ===============================
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### The Fix
|
|
178
|
+
To prevent task leakage, ensure executors are joined or futures are waited on within the owner's scope:
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
def test_background_worker_fixed():
|
|
182
|
+
with ThreadPoolExecutor(max_workers=1) as executor:
|
|
183
|
+
future = executor.submit(lambda: 42)
|
|
184
|
+
assert future.result() == 42
|
|
185
|
+
# Context manager exit shuts down the executor and joins worker threads
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Installation & Plugin Discovery
|
|
191
|
+
|
|
192
|
+
### Public Release (PyPI)
|
|
193
|
+
|
|
194
|
+
Following initial release publication to PyPI:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
pip install pytest-state-guard
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
*(Note: Prior to the initial release publication on PyPI, use the local development installation below.)*
|
|
201
|
+
|
|
202
|
+
### Local / Development Installation
|
|
203
|
+
|
|
204
|
+
During development and local validation prior to public release, install State Guard from your local repository root or from a pre-built wheel:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
# Install from local repository root:
|
|
208
|
+
pip install .
|
|
209
|
+
|
|
210
|
+
# Or install from a previously built wheel:
|
|
211
|
+
pip install dist/pytest_state_guard-0.1.0-py3-none-any.whl
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Automatic Discovery
|
|
215
|
+
|
|
216
|
+
Once installed, State Guard is automatically discovered by pytest via its standard `pytest11` entry point (`state_guard = "pytest_state_guard.plugin"`).
|
|
217
|
+
|
|
218
|
+
### Disabling the Plugin
|
|
219
|
+
|
|
220
|
+
To temporarily deactivate State Guard for a specific test run without uninstalling it:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
pytest -p no:state_guard
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Compatibility & Verification
|
|
229
|
+
|
|
230
|
+
- **Python Requirements:** `>= 3.11`
|
|
231
|
+
- *Verified Environments:* Python 3.11.9, Python 3.14.0
|
|
232
|
+
- **Pytest Requirements:** `>= 9.1.1` (direct runtime dependency)
|
|
233
|
+
- *Verified Environments:* pytest 9.1.1, pytest 9.2.0
|
|
234
|
+
- **Pluggy Requirements:** `>= 1.5.0` (transitive dependency via pytest)
|
|
235
|
+
- *Verified Environments:* pluggy 1.5.0, pluggy 1.6.0, pluggy 1.7.0
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## Development & Test Suite
|
|
240
|
+
|
|
241
|
+
To run the complete test suite across adversarial, unit, and lifecycle integration tests:
|
|
242
|
+
|
|
243
|
+
**PowerShell:**
|
|
244
|
+
```powershell
|
|
245
|
+
$env:PYTHONPATH = "src"
|
|
246
|
+
pytest
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
**Command Prompt:**
|
|
250
|
+
```cmd
|
|
251
|
+
set PYTHONPATH=src
|
|
252
|
+
pytest
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
To build a standalone distribution wheel:
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
pip wheel . --no-deps -w dist/
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Scope & Limitations
|
|
264
|
+
|
|
265
|
+
- **ThreadPoolExecutor Exclusivity:** Only `concurrent.futures.ThreadPoolExecutor` is instrumented. Custom worker implementations relying on `threading.Thread` directly are uninstrumented.
|
|
266
|
+
- **Process Boundaries:** Each pytest process maintains its own independent in-memory ledger. Cross-process ledger aggregation and distributed ownership correlation (such as across `pytest-xdist` worker processes) are not provided.
|
|
267
|
+
- **Audit, Not Intervention:** State Guard reports concurrency boundary violations; it does not alter thread execution, terminate running threads, or enforce shutdown.
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## License
|
|
272
|
+
|
|
273
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
274
|
+
|
|
275
|
+
Copyright (c) 2026 bitbyrizbit
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
# pytest-state-guard
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
|
|
5
|
+
A pytest plugin auditing `ThreadPoolExecutor` task lifetimes against fixture and test owner boundaries.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## The test passed. The work didn't stop.
|
|
10
|
+
|
|
11
|
+
Pytest evaluates assertions, executes fixture teardowns, and moves smoothly to the next test in the suite. But if a test function or fixture submitted a callable to a `concurrent.futures.ThreadPoolExecutor` and did not explicitly wait on `Future.result()` or shut down the executor with `wait=True`, the submitted work may remain queued or actively executing past the owner's boundary.
|
|
12
|
+
|
|
13
|
+
Depending on operating system scheduling, the submitted callable may have completed unnoticed, may still be queued waiting for a worker, or may be actively mutating process-level state while a subsequent test assumes a clean environment.
|
|
14
|
+
|
|
15
|
+
Consider an illustrative scenario: a test submits background work and exits cleanly in mere milliseconds. Several tests later, an intermittent flake occurs because an orphaned thread from that earlier test was still executing and wrote into shared memory.
|
|
16
|
+
|
|
17
|
+
`pytest-state-guard` identifies this lifecycle mismatch. It instruments `ThreadPoolExecutor.submit` to capture task provenance, records observed lifecycle transitions into an append-only event ledger with monotonic sequence numbers, and evaluates task lifetimes against owner finalization boundaries using a formal policy engine.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## What It Does — and What It Does Not Do
|
|
22
|
+
|
|
23
|
+
### What State Guard Does
|
|
24
|
+
- **Instruments Task Submission:** Intercepts `ThreadPoolExecutor.submit` dynamically during the pytest session to bind task provenance to the active owner context.
|
|
25
|
+
- **Enforces Monotonic Ordering:** Commits every observed, tracked submission, start, exit, and finalization event to a thread-safe, append-only in-memory ledger.
|
|
26
|
+
- **Classifies Against Boundaries:** Evaluates whether submitted callables completed before their submitter was finalized, remained outstanding, or started execution after owner teardown.
|
|
27
|
+
- **Surfaces Failures Without Masking:** Reports violations in test teardowns (`=== ERRORS ===`) and the session summary without overwriting original call assertions (`=== FAILURES ===`) or swallowing upstream exceptions.
|
|
28
|
+
|
|
29
|
+
### What State Guard Deliberately Does Not Do
|
|
30
|
+
- **It does not terminate threads:** State Guard is an auditor, not an execution sandbox. It will not forcibly kill threads, cancel running callables, or shut down executors.
|
|
31
|
+
- **It does not isolate memory or prevent races:** It does not intercept memory writes or prevent data races in shared state. It does not detect every concurrency defect.
|
|
32
|
+
- **It does not instrument other concurrency primitives:** Raw `threading.Thread`, `multiprocessing`, `asyncio` loops, and third-party thread pools are out of scope.
|
|
33
|
+
- **Physical scheduling is non-deterministic; auditing is not:** State Guard does not claim that physical thread scheduling is deterministic. It guarantees that ledger event commitment, boundary snapshots, and policy classifications are strictly deterministic for any observed event sequence.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Task Provenance: The Submitter Owns the Task
|
|
38
|
+
|
|
39
|
+
In concurrent systems, an executor is merely an execution mechanism—often a shared, long-lived resource configured across multiple tests or fixtures. The entity responsible for the existence and lifetime of a task is the submitter.
|
|
40
|
+
|
|
41
|
+
State Guard establishes ownership through two primary scopes:
|
|
42
|
+
|
|
43
|
+
1. **Test Call Owners:** Bound to the test item during its `pytest_runtest_call` phase and finalized by the `pytest_runtest_teardown` hookwrapper after teardown processing (including fixture teardown finalizers).
|
|
44
|
+
2. **Fixture Owners:** Bound to fixture invocations during `pytest_fixture_setup` across all fixture scopes (`function`, `class`, `module`, `package`, and `session`), and finalized through `pytest_fixture_post_finalizer` after that fixture's teardown logic has completed. State Guard does not track arbitrary teardown code beyond this hook-defined boundary.
|
|
45
|
+
|
|
46
|
+
Ownership is propagated via context-local storage (`contextvars.ContextVar`). When a test or fixture calls `executor.submit(fn, *args, **kwargs)`, State Guard captures the active owner ID, issues a UUID for the task, and commits a submission reservation event before delegating to the real executor.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## The Event Ledger & Committed Ordering
|
|
51
|
+
|
|
52
|
+
Physical time is unreliable for concurrent auditing. State Guard relies on monotonic event sequence IDs assigned under an atomic lock. All sequence identifiers ($S_*$) represent **committed ledger sequence numbers**, not physical timestamps or hardware clock readings. State Guard establishes the deterministic order in which observations were committed, not the exact physical instants a thread started or completed.
|
|
53
|
+
|
|
54
|
+
The ledger records the lifecycle evidence State Guard observes:
|
|
55
|
+
|
|
56
|
+
- **Owner Finalization Boundary ($S_F$):** The sequence ID committed at the owner's teardown boundary (in `pytest_runtest_teardown` for test items, or `pytest_fixture_post_finalizer` for fixtures).
|
|
57
|
+
- **Submission Window ($S_{inv} \to S_{ret}$ / $S_{raise}$):** $S_{inv}$ is the submission-reservation sequence ID committed before delegating to the real executor; $S_{ret}$ or $S_{raise}$ is committed when `submit()` returns a `Future` or raises an exception.
|
|
58
|
+
- **Callable Lifecycle ($S_{start} \to S_{exit}$):** Committed when the wrapper begins executing the user callable and when it exits (by return or exception).
|
|
59
|
+
- **Future Observations ($S_{done}$ / $S_{cancel}$):** Committed when done-callbacks or cancellation were observed (noting that callback observation is not the exact physical settlement instant).
|
|
60
|
+
|
|
61
|
+
Policy evaluation compares observed evidence against the committed finalization boundary $S_F$.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Policy Classifications & Severity
|
|
66
|
+
|
|
67
|
+
Every task tracked by State Guard is classified according to its committed sequence history:
|
|
68
|
+
|
|
69
|
+
| Classification | Severity | Semantic Description |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `NO_OUTSTANDING_TASKS` | `CLEAN` | No task remains outstanding at the owner finalization boundary (tasks may have completed or been cancelled prior to finalization). |
|
|
72
|
+
| `COMPLETED_BEFORE_FINALIZATION` | `CLEAN` | Callable started and exited before owner finalization ($S_{exit} < S_F$). |
|
|
73
|
+
| `CANCELLED_BEFORE_START` | `CLEAN` | Future cancellation committed before finalization and before callable started. |
|
|
74
|
+
| `OUTSTANDING_TASK` | `VIOLATION` | Submission returned before finalization, but callable never started ($S_{ret} < S_F$). |
|
|
75
|
+
| `CALLABLE_NOT_EXITED` | `VIOLATION` | Callable started before finalization but did not exit before finalization. |
|
|
76
|
+
| `EXECUTION_AFTER_OWNER_FINALIZATION` | `VIOLATION` | Callable began execution after owner finalization ($S_{start} > S_F$). |
|
|
77
|
+
| `EXIT_COMMITTED_AFTER_FINALIZATION` | `VIOLATION` | Callable started before finalization but exited after finalization ($S_{exit} > S_F$). |
|
|
78
|
+
| `POST_LIFETIME_SUBMISSION` | `VIOLATION` | Task submitted after owner was already finalized ($S_{inv} > S_F$). |
|
|
79
|
+
| `SUBMISSION_UNRESOLVED` | `UNCERTAIN` | `submit()` did not return or raise before finalization. |
|
|
80
|
+
| `SUBMISSION_FAILED_UNVERIFIED` | `UNCERTAIN` | `submit()` raised before finalization; work item enqueue state unverified. |
|
|
81
|
+
|
|
82
|
+
### Preserving Boundary Evidence
|
|
83
|
+
- **Uncertainty is Advisory:** Submissions that were in flight when an owner finalized remain `SUBMISSION_UNRESOLVED` even if `submit()` subsequently returns. Uncertain findings are advisory: they are rendered in an advisory section of the terminal summary and do not automatically cause test failures.
|
|
84
|
+
- **Finding Identity Stability:** If an unresolved task subsequently begins execution after finalization, its classification evolves to `EXECUTION_AFTER_OWNER_FINALIZATION` while retaining its stable finding identifier.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Reporting Architecture
|
|
89
|
+
|
|
90
|
+
### 1. Per-Test Teardown Errors
|
|
91
|
+
Findings originating from test functions or function-scoped fixtures are attributed directly to that test item:
|
|
92
|
+
- **Test Passed:** Marked failed in teardown, appearing under `=== ERRORS ===` as `ERROR at teardown of <nodeid>`.
|
|
93
|
+
- **Test Failed:** If the test call itself failed (for example, an assertion failure), the call failure remains visible under `=== FAILURES ===` with its complete traceback, while concurrency violations appear under `=== ERRORS ===`.
|
|
94
|
+
- **Teardown Already Failed:** If the test teardown already failed (for example, an exception in a fixture finalizer), State Guard preserves the original teardown error representation and chains its violation details using a chained terminal representation (`ChainedTerminalRepr`) without overwriting the fixture error.
|
|
95
|
+
|
|
96
|
+
### 2. Session Audit Summary
|
|
97
|
+
Class, module, package, and session-scoped fixtures cannot be attributed to an arbitrary single test. Their findings are audited at session finish and rendered in the terminal summary by `pytest_terminal_summary`.
|
|
98
|
+
|
|
99
|
+
### 3. Exit Code Promotion
|
|
100
|
+
If all test assertions passed but State Guard detected concurrency violations, the session exit code is promoted to `pytest.ExitCode.TESTS_FAILED` (`1`). Pre-existing nonzero exit codes (such as assertion failures or interrupts) are preserved.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Usage Example
|
|
105
|
+
|
|
106
|
+
### An Illustrative Leaky Test
|
|
107
|
+
The following test submits work to a `ThreadPoolExecutor` and uses synchronization to guarantee that the worker callable has started before the test call finishes. In the illustrated execution, this demonstrates a worker remaining active across the owner finalization boundary.
|
|
108
|
+
|
|
109
|
+
*(Note: The bounded timeout on `release.wait(timeout=2.0)` ensures that worker threads safely terminate without hanging the test process, but it also means that under arbitrary operating system scheduling—such as thread suspension—this specific outcome is not guaranteed. This example deliberately demonstrates an unjoined background worker to illustrate State Guard's detection; it is an anti-pattern for production test suites.)*
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
import threading
|
|
113
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
114
|
+
|
|
115
|
+
started = threading.Event()
|
|
116
|
+
release = threading.Event()
|
|
117
|
+
|
|
118
|
+
def worker():
|
|
119
|
+
started.set()
|
|
120
|
+
# Bounded wait allows the thread to safely terminate if release is never set:
|
|
121
|
+
release.wait(timeout=2.0)
|
|
122
|
+
|
|
123
|
+
def test_background_worker():
|
|
124
|
+
executor = ThreadPoolExecutor(max_workers=1)
|
|
125
|
+
executor.submit(worker)
|
|
126
|
+
|
|
127
|
+
# Synchronize: guarantee the worker callable has started execution
|
|
128
|
+
assert started.wait(timeout=1.0), "Worker failed to start"
|
|
129
|
+
|
|
130
|
+
# The test passes assertions, but the worker is still active:
|
|
131
|
+
assert True
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Pytest Output (Illustrative)
|
|
135
|
+
Because physical thread scheduling is non-deterministic, the sample output below represents one possible illustrative execution. If scheduling delays the test thread until the worker timeout expires, an alternate classification (such as `COMPLETED_BEFORE_FINALIZATION`) could be observed instead. Total process duration may reflect background workers concluding before process exit.
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
==================================== ERRORS ====================================
|
|
139
|
+
_______________________ ERROR at teardown of test_background_worker _______________________
|
|
140
|
+
---------------- State Guard Teardown Violation: TEST_CALL [test_demo.py::test_background_worker] ----------------
|
|
141
|
+
Owner ID: 3b9a1c4e-6e8d-4f1a-b2c3-9d8e7f6a5b4c
|
|
142
|
+
Owner Finalized Sequence: 42 (created at seq 38)
|
|
143
|
+
|
|
144
|
+
* Finding: f-3b9a1c4e-001
|
|
145
|
+
Classification: CALLABLE_NOT_EXITED
|
|
146
|
+
Task ID: t-8a7b6c5d-1122-3344
|
|
147
|
+
Evidence: Callable started at seq 40 but did not exit before owner finalization (seq 42).
|
|
148
|
+
Sequences: 40, 42
|
|
149
|
+
|
|
150
|
+
=========================== short test summary info ============================
|
|
151
|
+
ERROR test_demo.py::test_background_worker - State Guard Teardown Violation: TEST_CALL
|
|
152
|
+
============================== 1 error in 0.12s ===============================
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### The Fix
|
|
156
|
+
To prevent task leakage, ensure executors are joined or futures are waited on within the owner's scope:
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
def test_background_worker_fixed():
|
|
160
|
+
with ThreadPoolExecutor(max_workers=1) as executor:
|
|
161
|
+
future = executor.submit(lambda: 42)
|
|
162
|
+
assert future.result() == 42
|
|
163
|
+
# Context manager exit shuts down the executor and joins worker threads
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Installation & Plugin Discovery
|
|
169
|
+
|
|
170
|
+
### Public Release (PyPI)
|
|
171
|
+
|
|
172
|
+
Following initial release publication to PyPI:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
pip install pytest-state-guard
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
*(Note: Prior to the initial release publication on PyPI, use the local development installation below.)*
|
|
179
|
+
|
|
180
|
+
### Local / Development Installation
|
|
181
|
+
|
|
182
|
+
During development and local validation prior to public release, install State Guard from your local repository root or from a pre-built wheel:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
# Install from local repository root:
|
|
186
|
+
pip install .
|
|
187
|
+
|
|
188
|
+
# Or install from a previously built wheel:
|
|
189
|
+
pip install dist/pytest_state_guard-0.1.0-py3-none-any.whl
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Automatic Discovery
|
|
193
|
+
|
|
194
|
+
Once installed, State Guard is automatically discovered by pytest via its standard `pytest11` entry point (`state_guard = "pytest_state_guard.plugin"`).
|
|
195
|
+
|
|
196
|
+
### Disabling the Plugin
|
|
197
|
+
|
|
198
|
+
To temporarily deactivate State Guard for a specific test run without uninstalling it:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
pytest -p no:state_guard
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Compatibility & Verification
|
|
207
|
+
|
|
208
|
+
- **Python Requirements:** `>= 3.11`
|
|
209
|
+
- *Verified Environments:* Python 3.11.9, Python 3.14.0
|
|
210
|
+
- **Pytest Requirements:** `>= 9.1.1` (direct runtime dependency)
|
|
211
|
+
- *Verified Environments:* pytest 9.1.1, pytest 9.2.0
|
|
212
|
+
- **Pluggy Requirements:** `>= 1.5.0` (transitive dependency via pytest)
|
|
213
|
+
- *Verified Environments:* pluggy 1.5.0, pluggy 1.6.0, pluggy 1.7.0
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Development & Test Suite
|
|
218
|
+
|
|
219
|
+
To run the complete test suite across adversarial, unit, and lifecycle integration tests:
|
|
220
|
+
|
|
221
|
+
**PowerShell:**
|
|
222
|
+
```powershell
|
|
223
|
+
$env:PYTHONPATH = "src"
|
|
224
|
+
pytest
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
**Command Prompt:**
|
|
228
|
+
```cmd
|
|
229
|
+
set PYTHONPATH=src
|
|
230
|
+
pytest
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
To build a standalone distribution wheel:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
pip wheel . --no-deps -w dist/
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Scope & Limitations
|
|
242
|
+
|
|
243
|
+
- **ThreadPoolExecutor Exclusivity:** Only `concurrent.futures.ThreadPoolExecutor` is instrumented. Custom worker implementations relying on `threading.Thread` directly are uninstrumented.
|
|
244
|
+
- **Process Boundaries:** Each pytest process maintains its own independent in-memory ledger. Cross-process ledger aggregation and distributed ownership correlation (such as across `pytest-xdist` worker processes) are not provided.
|
|
245
|
+
- **Audit, Not Intervention:** State Guard reports concurrency boundary violations; it does not alter thread execution, terminate running threads, or enforce shutdown.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## License
|
|
250
|
+
|
|
251
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
252
|
+
|
|
253
|
+
Copyright (c) 2026 bitbyrizbit
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "pytest-state-guard"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Deterministic concurrency auditor for ThreadPoolExecutor task lifetimes against pytest owners"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "pytest-state-guard contributors" }
|
|
15
|
+
]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Framework :: Pytest",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Programming Language :: Python :: 3.14",
|
|
24
|
+
"Topic :: Software Development :: Testing",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"pytest>=9.1.1",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Repository = "https://github.com/bitbyrizbit/pytest-state-guard"
|
|
32
|
+
Issues = "https://github.com/bitbyrizbit/pytest-state-guard/issues"
|
|
33
|
+
|
|
34
|
+
[project.entry-points.pytest11]
|
|
35
|
+
state_guard = "pytest_state_guard.plugin"
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.packages.find]
|
|
38
|
+
where = ["src"]
|
|
39
|
+
|
|
40
|
+
[tool.setuptools.package-data]
|
|
41
|
+
pytest_state_guard = ["py.typed"]
|
|
42
|
+
|
|
43
|
+
[tool.setuptools.dynamic]
|
|
44
|
+
version = { attr = "pytest_state_guard.__version__" }
|