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.
@@ -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
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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__" }
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """pytest-state-guard: ThreadPoolExecutor task lifetime auditor for pytest."""
2
+
3
+ __version__ = "0.1.0"
4
+ __all__ = ["__version__"]