pytest-parallex 0.1.1__tar.gz

pytest_parallex-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+/dist/
+/build/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.moon/cache/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Local session logs
+logs/

pytest_parallex-0.1.1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The version in `pyproject.toml` is the single source of truth, and merging a version bump
+to `main` publishes it — see "Releasing" in the README.
+
+## 0.1.1 — first release
+
+The first published version is 0.1.1, not 0.1.0: `version-guard` requires a code change to
+carry a version bump, and 0.1.0 never left this repo. Nothing was released as 0.1.0.
+
+### Added
+
+- `--parallel=fork`: collect once in the controller, then fork warm workers that inherit
+  the imported suite and the collected items via copy-on-write.
+- **Controller-side session fixtures.** `scope="session"` runs once, in the controller,
+  before the fork; children inherit the cached result. Under pytest-xdist the same fixture
+  runs once *per worker*. `--parallex-no-session-scope` restores the per-worker behaviour.
+- `--parallel=thread`, `--parallel=async`, `--parallel=process`.
+- `--parallel-workers=N` (default `auto` = CPU count).
+- Fork-safety refusal: the run stops with a message naming the offending thread or event
+  loop rather than forking a process that would deadlock in the child.
+- Logging `QueueListener` threads are stopped and restarted around the fork, so a suite
+  that merely imports litestar (or anything using `QueueHandler`) can still fork.
+- Hooks: `pytest_parallex_setup`, `pytest_parallex_teardown`,
+  `pytest_parallex_auto_num_workers`.
+- Fixtures: `parallex_worker_id`, `parallex_mode`, `parallex_setup_data`.
+- Dynamic work-claiming: workers race for module groups off a shared counter rather than
+  being dealt a static partition, so a slow module can't strand a worker.
+
+### Requires
+
+- **pytest >= 8.1**, not 8.0: `FixtureManager.getfixturedefs` took a nodeid string until
+  8.1 and a `Node` from 8.1 on, and the fork runner passes a `Node`.
+- Tested against pytest 8.1, 8.4, 9.0 and 9.1 across all four modes. CI pins the floor.
+
+### Worker-scoped fixtures
+
+- A `scope="session"` fixture that requests `worker_id` (directly or transitively) is
+  per-worker and is never hoisted to the controller — so `postgres_server` (one container)
+  and `database_url(worker_id)` (one database per worker) can coexist, which is what
+  xdist's filelock recipe exists to fake.
+- `worker_id` is provided by parallex when `--parallel` is active, registered late enough
+  to win the name from pytest-xdist. A plain `pytest -n 4` run keeps xdist's.

pytest_parallex-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Cardona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_parallex-0.1.1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: pytest-parallex
+Version: 0.1.1
+Summary: Parallel test execution for pytest where scope="session" means session — fork-based warm workers that inherit session fixtures, plus thread, async and process modes
+Project-URL: Homepage, https://gitlab.com/jorgeecardona/pytest-parallex
+Project-URL: Repository, https://gitlab.com/jorgeecardona/pytest-parallex
+Project-URL: Changelog, https://gitlab.com/jorgeecardona/pytest-parallex/-/blob/main/CHANGELOG.md
+Author-email: Jorge Cardona <jorgeecardona@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: concurrency,fork,parallel,pytest,session-fixtures,test-speed,testing,xdist
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pytest>=8.1
+Description-Content-Type: text/markdown
+
+# pytest-parallex
+
+Parallel test execution for pytest, with one idea the other plugins can't offer:
+**`scope="session"` means session — once, not once per worker.**
+
+```bash
+pip install pytest-parallex
+pytest --parallel=fork
+```
+
+## The problem it solves
+
+Under pytest-xdist, every worker is a fresh interpreter that runs its own full session, so
+a `scope="session"` fixture executes **once per worker**. Their docs say so plainly, and
+ship a `FileLock`-and-shared-tmpdir recipe as the workaround. It isn't a bug in your test
+suite — their architecture has no moment at which a controller could build something once
+and hand it to everybody.
+
+Forking has that moment.
+
+```python
+@pytest.fixture(scope="session")
+def postgres():
+    with PostgresContainer("postgres:16") as pg:   # boots ONCE
+        yield pg.get_connection_url()              # every worker gets this URL
+```
+
+`--parallel=fork` sets session fixtures up in the controller *before* forking. Children
+inherit the `FixtureDef` — cached result and all — through copy-on-write, so they use it
+and never re-run setup. One container, one compiled asset, one login, shared by every
+worker, with no lockfile.
+
+Same suite, same four workers, counting how many times the fixture body actually ran:
+
+```console
+$ pytest -n 4                                  # pytest-xdist
+8 passed        session fixture booted 4 times
+
+$ pytest --parallel=fork --parallel-workers=4  # pytest-parallex
+8 passed        session fixture booted 1 time
+```
+
+That leaves the scope pytest never had a name for: **the worker**. What xdist calls
+"session" is really per-worker, and conflating the two is what forces the recipe. Here
+they're separate — `session` runs in the controller, and each forked child is a worker.
+
+## Modes
+
+```bash
+pytest --parallel=fork --parallel-workers=8
+```
+
+| mode | isolation | `scope="session"` runs | use when |
+|---|---|---|---|
+| `fork` | process per worker, warm | **once, in the controller** | Linux/macOS, and the process is quiet at fork time |
+| `thread` | shared address space | once | tests are I/O-bound and tolerate sharing globals |
+| `async` | shared address space | once | same as `thread`, dispatched via asyncio |
+| `process` | fresh interpreter per worker | once **per worker** | tests mutate process-global state, or you're on Windows |
+
+`--parallel-workers` defaults to `auto` (CPU count).
+
+## What fork actually costs and buys
+
+Measured, and worth being precise about, because the intuitive pitch is wrong:
+
+- **Removing xdist's worker boot is a flat ~1.5–2.3s.** It does *not* grow with suite size,
+  import weight, or worker count. On a 3s local run that's 1.84x and you feel it; on a 292s
+  CI suite it's under 1% and it's noise. Redundant imports parallelize across idle cores —
+  xdist's N-way collection is wasted *CPU*, not wasted *time*, and you only get paid for
+  removing it if the cores were already busy.
+- **Session-fixture reuse is the part that scales.** A 10s container boot across 8 workers
+  is 80s under xdist and 10s here. That's the reason to reach for this.
+
+Full method, numbers, and three traps that produced convincing wrong answers:
+[docs/benchmarks.md](docs/benchmarks.md).
+
+## Fork safety
+
+`fork()` duplicates only the calling thread. Anything another thread held — a lock, a
+half-written buffer, a connection's state machine — is duplicated mid-flight and belongs
+to nobody in the child. That's how forked children deadlock, and CPython 3.12 warns about
+exactly it.
+
+So parallex refuses rather than warns, and names the offender:
+
+```
+--parallel=fork requires a quiet process at fork time, but 1 non-main thread(s)
+are running (Thread-1 (_monitor)). Move the offending setup into a fixture so it
+runs after the fork, or use --parallel=process.
+```
+
+Logging `QueueListener` threads (which litestar, and anything using `QueueHandler`, starts
+at import) are stopped and restarted around the fork automatically.
+
+The constraint this imposes on a pre-fork session fixture: whatever it builds must survive
+a fork. **An address survives — a URL, a path, a port. A live connection, a thread, or an
+event loop does not.** The natural split is that the controller owns the *server* and each
+worker opens its own *connection* to it:
+
+```python
+@pytest.fixture(scope="session")
+def db_url():                     # controller: owns the server. Forkable.
+    with PostgresContainer("postgres:16") as pg:
+        yield pg.get_connection_url()
+
+@pytest.fixture                   # worker: owns the connection. Not forkable, so per-test.
+def db(db_url):
+    conn = psycopg.connect(db_url)
+    yield conn
+    conn.close()
+```
+
+If a session fixture can't survive the fork, `--parallex-no-session-scope` defers them all
+to the workers (restoring xdist's once-per-worker behaviour).
+
+## The fixture that has to differ per worker
+
+Some `scope="session"` fixtures exist precisely *to* differ between workers — the archetype
+being one that carves a database per worker so tests don't tread on each other. Hoisting
+that one would be actively wrong: every worker gets the same database, and a per-test
+`create_all`/`drop_all` then wipes its siblings' schemas mid-test.
+
+**A fixture that requests `worker_id` — directly or through another fixture — is
+per-worker, and is never hoisted.** Everything else that says `scope="session"` means it.
+No new syntax, because suites already write it this way:
+
+```python
+@pytest.fixture(scope="session")
+def postgres_server():                          # -> controller. One container.
+    with PostgresContainer("postgres:16") as pg:
+        yield pg.get_connection_url()
+
+@pytest.fixture(scope="session")
+def database_url(worker_id, postgres_server):   # -> per worker. Requests worker_id.
+    url = f"{postgres_server}/test_{worker_id}"
+    create_database(url)
+    yield url
+    drop_database(url)
+```
+
+One container for the run, one database per worker on it — which is the thing xdist's
+filelock recipe exists to fake. This names the scope xdist conflates: what it calls
+"session" is really per-worker, and here you can have both.
+
+`worker_id` is also xdist's fixture name, deliberately — it's what makes existing suites
+work unchanged. When both plugins are installed, `--parallel` takes the name so you get a
+real per-worker id; a plain `pytest -n 4` run leaves xdist's alone. `parallex_worker_id`
+is an alias if you'd rather be explicit, and marks a fixture per-worker just the same.
+
+## Fixtures
+
+| fixture | gives you |
+|---|---|
+| `worker_id` | `'f0'`, `'w1'`, `'a2'`… or `'main'`. Requesting it marks a fixture per-worker |
+| `parallex_worker_id` | the same value, under a name xdist can't shadow |
+| `parallex_mode` | the active mode, or `None` |
+| `parallex_setup_data` | whatever `pytest_parallex_setup` returned |
+
+## Hooks
+
+```python
+# conftest.py
+def pytest_parallex_setup(config):
+    """Run once in the controller, before any worker starts. Pre-fork: no I/O handles."""
+    return {"token": build_expensive_thing()}
+
+def pytest_parallex_teardown(config, data):
+    """Run once in the controller, after every worker has finished."""
+
+def pytest_parallex_auto_num_workers(config):
+    """Override --parallel-workers=auto. Default: os.cpu_count()."""
+    return 8
+```
+
+## Known limitations
+
+- **`--maxfail` doesn't stop a fork run early.** Workers run their claimed group to
+  completion and the controller replays the reports afterwards, so the count is right but
+  the run isn't cut short.
+- **Fork parallelizes by module.** A whole suite in one file uses one worker no matter what
+  `--parallel-workers` says.
+- **`fork` is Linux/macOS only.** On Windows, use `--parallel=process`.
+- **`thread`/`async` don't escape the GIL.** They're for suites that wait, not suites that
+  compute.
+
+## Developing
+
+```bash
+uv sync                # toolchain
+make install-hooks     # one-time, after cloning
+make check             # lint + typecheck + test, exactly what CI runs
+```
+
+## Releasing
+
+The version in `pyproject.toml` is the single source of truth, and releases are automated:
+
+1. **`pre-commit` auto-bumps** the patch version whenever a commit touches `src/` (run
+   `make install-hooks` once after cloning). Doc/test/config-only commits don't bump. For
+   an intentional minor/major release, bump deliberately: `make bump TYPE=minor`.
+2. **`version-guard`** (part of `moon run :ci`) enforces the same rule non-bypassably in
+   CI: a push or MR that changes `src/` without a version bump fails the pipeline, catching
+   `--no-verify` and unhooked clones.
+3. **`:release`** runs on a green `main` pipeline: if `pyproject`'s version isn't on PyPI
+   yet, it publishes via OIDC Trusted Publishing. So merging a version bump to `main`
+   releases itself — no second pipeline, no tag required.
+
+## License
+
+MIT

pytest_parallex-0.1.1/README.md

@@ -0,0 +1,210 @@
+# pytest-parallex
+
+Parallel test execution for pytest, with one idea the other plugins can't offer:
+**`scope="session"` means session — once, not once per worker.**
+
+```bash
+pip install pytest-parallex
+pytest --parallel=fork
+```
+
+## The problem it solves
+
+Under pytest-xdist, every worker is a fresh interpreter that runs its own full session, so
+a `scope="session"` fixture executes **once per worker**. Their docs say so plainly, and
+ship a `FileLock`-and-shared-tmpdir recipe as the workaround. It isn't a bug in your test
+suite — their architecture has no moment at which a controller could build something once
+and hand it to everybody.
+
+Forking has that moment.
+
+```python
+@pytest.fixture(scope="session")
+def postgres():
+    with PostgresContainer("postgres:16") as pg:   # boots ONCE
+        yield pg.get_connection_url()              # every worker gets this URL
+```
+
+`--parallel=fork` sets session fixtures up in the controller *before* forking. Children
+inherit the `FixtureDef` — cached result and all — through copy-on-write, so they use it
+and never re-run setup. One container, one compiled asset, one login, shared by every
+worker, with no lockfile.
+
+Same suite, same four workers, counting how many times the fixture body actually ran:
+
+```console
+$ pytest -n 4                                  # pytest-xdist
+8 passed        session fixture booted 4 times
+
+$ pytest --parallel=fork --parallel-workers=4  # pytest-parallex
+8 passed        session fixture booted 1 time
+```
+
+That leaves the scope pytest never had a name for: **the worker**. What xdist calls
+"session" is really per-worker, and conflating the two is what forces the recipe. Here
+they're separate — `session` runs in the controller, and each forked child is a worker.
+
+## Modes
+
+```bash
+pytest --parallel=fork --parallel-workers=8
+```
+
+| mode | isolation | `scope="session"` runs | use when |
+|---|---|---|---|
+| `fork` | process per worker, warm | **once, in the controller** | Linux/macOS, and the process is quiet at fork time |
+| `thread` | shared address space | once | tests are I/O-bound and tolerate sharing globals |
+| `async` | shared address space | once | same as `thread`, dispatched via asyncio |
+| `process` | fresh interpreter per worker | once **per worker** | tests mutate process-global state, or you're on Windows |
+
+`--parallel-workers` defaults to `auto` (CPU count).
+
+## What fork actually costs and buys
+
+Measured, and worth being precise about, because the intuitive pitch is wrong:
+
+- **Removing xdist's worker boot is a flat ~1.5–2.3s.** It does *not* grow with suite size,
+  import weight, or worker count. On a 3s local run that's 1.84x and you feel it; on a 292s
+  CI suite it's under 1% and it's noise. Redundant imports parallelize across idle cores —
+  xdist's N-way collection is wasted *CPU*, not wasted *time*, and you only get paid for
+  removing it if the cores were already busy.
+- **Session-fixture reuse is the part that scales.** A 10s container boot across 8 workers
+  is 80s under xdist and 10s here. That's the reason to reach for this.
+
+Full method, numbers, and three traps that produced convincing wrong answers:
+[docs/benchmarks.md](docs/benchmarks.md).
+
+## Fork safety
+
+`fork()` duplicates only the calling thread. Anything another thread held — a lock, a
+half-written buffer, a connection's state machine — is duplicated mid-flight and belongs
+to nobody in the child. That's how forked children deadlock, and CPython 3.12 warns about
+exactly it.
+
+So parallex refuses rather than warns, and names the offender:
+
+```
+--parallel=fork requires a quiet process at fork time, but 1 non-main thread(s)
+are running (Thread-1 (_monitor)). Move the offending setup into a fixture so it
+runs after the fork, or use --parallel=process.
+```
+
+Logging `QueueListener` threads (which litestar, and anything using `QueueHandler`, starts
+at import) are stopped and restarted around the fork automatically.
+
+The constraint this imposes on a pre-fork session fixture: whatever it builds must survive
+a fork. **An address survives — a URL, a path, a port. A live connection, a thread, or an
+event loop does not.** The natural split is that the controller owns the *server* and each
+worker opens its own *connection* to it:
+
+```python
+@pytest.fixture(scope="session")
+def db_url():                     # controller: owns the server. Forkable.
+    with PostgresContainer("postgres:16") as pg:
+        yield pg.get_connection_url()
+
+@pytest.fixture                   # worker: owns the connection. Not forkable, so per-test.
+def db(db_url):
+    conn = psycopg.connect(db_url)
+    yield conn
+    conn.close()
+```
+
+If a session fixture can't survive the fork, `--parallex-no-session-scope` defers them all
+to the workers (restoring xdist's once-per-worker behaviour).
+
+## The fixture that has to differ per worker
+
+Some `scope="session"` fixtures exist precisely *to* differ between workers — the archetype
+being one that carves a database per worker so tests don't tread on each other. Hoisting
+that one would be actively wrong: every worker gets the same database, and a per-test
+`create_all`/`drop_all` then wipes its siblings' schemas mid-test.
+
+**A fixture that requests `worker_id` — directly or through another fixture — is
+per-worker, and is never hoisted.** Everything else that says `scope="session"` means it.
+No new syntax, because suites already write it this way:
+
+```python
+@pytest.fixture(scope="session")
+def postgres_server():                          # -> controller. One container.
+    with PostgresContainer("postgres:16") as pg:
+        yield pg.get_connection_url()
+
+@pytest.fixture(scope="session")
+def database_url(worker_id, postgres_server):   # -> per worker. Requests worker_id.
+    url = f"{postgres_server}/test_{worker_id}"
+    create_database(url)
+    yield url
+    drop_database(url)
+```
+
+One container for the run, one database per worker on it — which is the thing xdist's
+filelock recipe exists to fake. This names the scope xdist conflates: what it calls
+"session" is really per-worker, and here you can have both.
+
+`worker_id` is also xdist's fixture name, deliberately — it's what makes existing suites
+work unchanged. When both plugins are installed, `--parallel` takes the name so you get a
+real per-worker id; a plain `pytest -n 4` run leaves xdist's alone. `parallex_worker_id`
+is an alias if you'd rather be explicit, and marks a fixture per-worker just the same.
+
+## Fixtures
+
+| fixture | gives you |
+|---|---|
+| `worker_id` | `'f0'`, `'w1'`, `'a2'`… or `'main'`. Requesting it marks a fixture per-worker |
+| `parallex_worker_id` | the same value, under a name xdist can't shadow |
+| `parallex_mode` | the active mode, or `None` |
+| `parallex_setup_data` | whatever `pytest_parallex_setup` returned |
+
+## Hooks
+
+```python
+# conftest.py
+def pytest_parallex_setup(config):
+    """Run once in the controller, before any worker starts. Pre-fork: no I/O handles."""
+    return {"token": build_expensive_thing()}
+
+def pytest_parallex_teardown(config, data):
+    """Run once in the controller, after every worker has finished."""
+
+def pytest_parallex_auto_num_workers(config):
+    """Override --parallel-workers=auto. Default: os.cpu_count()."""
+    return 8
+```
+
+## Known limitations
+
+- **`--maxfail` doesn't stop a fork run early.** Workers run their claimed group to
+  completion and the controller replays the reports afterwards, so the count is right but
+  the run isn't cut short.
+- **Fork parallelizes by module.** A whole suite in one file uses one worker no matter what
+  `--parallel-workers` says.
+- **`fork` is Linux/macOS only.** On Windows, use `--parallel=process`.
+- **`thread`/`async` don't escape the GIL.** They're for suites that wait, not suites that
+  compute.
+
+## Developing
+
+```bash
+uv sync                # toolchain
+make install-hooks     # one-time, after cloning
+make check             # lint + typecheck + test, exactly what CI runs
+```
+
+## Releasing
+
+The version in `pyproject.toml` is the single source of truth, and releases are automated:
+
+1. **`pre-commit` auto-bumps** the patch version whenever a commit touches `src/` (run
+   `make install-hooks` once after cloning). Doc/test/config-only commits don't bump. For
+   an intentional minor/major release, bump deliberately: `make bump TYPE=minor`.
+2. **`version-guard`** (part of `moon run :ci`) enforces the same rule non-bypassably in
+   CI: a push or MR that changes `src/` without a version bump fails the pipeline, catching
+   `--no-verify` and unhooked clones.
+3. **`:release`** runs on a green `main` pipeline: if `pyproject`'s version isn't on PyPI
+   yet, it publishes via OIDC Trusted Publishing. So merging a version bump to `main`
+   releases itself — no second pipeline, no tag required.
+
+## License
+
+MIT

pytest_parallex-0.1.1/docs/benchmarks.md

@@ -0,0 +1,110 @@
+# What fork actually buys — measured, 2026-07-14
+
+Written after a session that produced three wrong answers before a right one. The wrong turns are
+kept here on purpose: each one is a trap that looks exactly like a result.
+
+## Bottom line
+
+**`--parallel=fork` removes xdist's fixed worker-boot cost — a flat ~1.5–2.3s. That is the whole
+win.** It does *not* scale with suite size, import weight, or worker count.
+
+That makes fork mode a **local TDD-loop feature, not a CI feature**:
+
+| suite | xdist | fork | verdict |
+|---|---|---|---|
+| 3s local run | 3.21s | 1.75s | **1.84x — you feel this** |
+| paas CI `api:test` (292s) | — | −2s | **under 1%. noise.** |
+
+## The thesis that died
+
+The pitch was: *xdist re-imports and re-collects in every worker (its own FAQ admits it, and
+[#353](https://github.com/pytest-dev/pytest-xdist/issues/353) reports a 4x collection penalty on a
+16k-test suite), so collect-once-then-fork should scale better the heavier the import.*
+
+Measured, with a CPU-bound import (not a `sleep` — see trap 3), 8 workers on 16 cores:
+
+| import cost | xdist -n8 | fork x8 | ratio | absolute saving |
+|---|---|---|---|---|
+| 0.03s | 3.21s | 1.75s | 1.83x | 1.46s |
+| 0.55s | 3.82s | 2.17s | 1.76x | 1.65s |
+| 2.01s | 5.37s | 3.67s | 1.46x | 1.70s |
+| 4.65s | 8.75s | 6.40s | 1.37x | 2.35s |
+
+**The ratio shrinks as the import grows, and the absolute saving is flat.** The prediction was
+backwards, and the reason is the thing to internalize:
+
+> **Redundant imports parallelize across idle cores.** Eight workers each importing on eight free
+> cores costs ~1x wall time, not 8x. xdist's N-way collection is wasted *CPU*, not wasted *time*.
+> You only get paid for removing it if the cores were already busy.
+
+So xdist's real, addressable overhead is just gateway boot: `subprocess.Popen` of a virgin
+interpreter per worker, plus the execnet handshake. Constant, and small.
+
+## Three traps that produced convincing wrong numbers
+
+**1. The runner silently never ran.** `pytest_runtestloop` is a `firstresult` hook — the first impl
+to return non-None wins. Registering with `trylast=True` handed the loop to pytest's builtin, which
+returned `True`. Every test still passed, serially, and the "fork" benchmarks were plain serial
+pytest for hours. The tell was CPU utilization: **0.9 cores busy on a 16-worker run** (`user 5m44s`
+/ `real 7m14s`), against xdist's 8.9 (`user 18m30s` / `real 2m10s`). *A parallel runner that isn't
+running looks like a slow parallel runner, not like a broken one.* Check `user`/`real` before
+believing any parallel benchmark.
+
+**2. Benchmarking a suite that can't fork.** With the hook fixed, paas's suite refuses outright:
+
+```
+--parallel=fork requires a quiet process at fork time, but 1 non-main thread(s)
+are running (Thread-1 (_monitor)).
+```
+
+`litestar.logging.standard.LoggingQueueListener` starts a logging thread **at import**. This is the
+predicted #1 hazard arriving immediately: you cannot stop threads you don't own. Android's zygote
+only gets away with fork because `ZygoteHooks.preFork()` calls `Daemons.stop()` and restarts them
+after — it owns the entire runtime. A pytest plugin owns none of it.
+
+**3. `time.sleep()` is not an import.** The first synthetic modelled import cost as a sleep. Sleep
+parallelizes perfectly, so it showed fork's advantage *growing* with import weight — the opposite of
+the truth. Model CPU-bound work with CPU-bound work.
+
+## What was actually confirmed
+
+- **xdist cannot fork, and it isn't close.** execnet's `get_execmodel()` closes over
+  `thread`/`main_thread_only`/`eventlet`/`gevent` with an exhaustive `else: raise`; workers are
+  spawned `subprocess.Popen([python, "-u", "-c", bootstrap])`. There is nothing to inherit. The
+  ground is genuinely unoccupied.
+- **The stdlib `random` frozen-seed hazard does not apply to CPython.** `Lib/random.py:992` does
+  `_os.register_at_fork(after_in_child=_inst.seed)` — children reseed automatically. Verified by
+  forking after `random.seed(42)`: children diverge. The Spring
+  [#113](https://github.com/rails/spring/issues/113) precedent that froze a test seed for five years
+  is *Ruby*, whose `Random` has no such hook. Libraries that seed their own state (numpy, faker)
+  still need checking; stdlib does not.
+- **The zygote effect is real but narrow.** Forking a parent that has already paid a 904ms
+  `create_app()` costs **1.56ms/child, flat out to 248 children**. Whether that is worth anything
+  depends entirely on whether the suite is CPU-bound — see below.
+- **Dynamic scheduling beat static by only 6%** on the paas suite (411.5s → 386.5s), far under the
+  1.43x predicted from per-module costs. Both numbers are void anyway (trap 1), but the
+  claim-counter queue is the right design regardless: a static deal must guess a group's cost from
+  its test *count*, and on a suite whose modules ranged 0.1s–167s that guess is bad.
+
+## Where this leaves the project
+
+Fork mode is worth shipping for the **inner loop** — the same niche Discord's pytest daemon targets
+(median 20s → 2s) without inheriting their hard problem (correct incremental reload of a long-lived
+dirty process; a forked child is a throwaway copy and the parent is never mutated).
+
+It is **not** a CI play, and the prior art says so too: DHH removed Spring from Rails defaults in
+[rails/rails#42997](https://github.com/rails/rails/pull/42997) with the reason *"Faster computers
+have meant that most apps won't see a big benefit... the pain of dealing with the occasional spring
+issue is no longer warranted by default."* The cost of a preloader is constant; the benefit shrinks
+with hardware. That is the same shape as the flat 1.5–2.3s measured above.
+
+Open questions, in order:
+1. **Can a suite be made forkable?** paas can't fork because of one third-party logging thread. A
+   `pytest_parallex_pre_fork` / `post_fork` hook pair would let the suite author quiesce and restart
+   what the plugin can't know about (Android's `Daemons.stop()`, Passenger's
+   `:starting_worker_process`, Spring's `after_fork` — every prior system converged on this).
+2. **Is the inner-loop win defensible against `--lf`/`-k`?** A dev rerunning one module already
+   pays only that module's import. Measure fork against the workflows people actually use, not
+   against a full-suite run.
+3. **Does the zygote matter for anyone?** It only pays where per-test setup is expensive AND
+   CPU-bound. paas's setup is expensive but I/O-bound (Postgres), so it wouldn't have helped there.