pytest-timing 0.1.0__py3-none-any.whl

pytest_timing/xdist_compat.py

@@ -0,0 +1,158 @@
+"""Everything that touches pytest-xdist internals, in one place.
+
+xdist has no public API for "why did the controller stop?", so this module reads the
+few attributes the controller session (``DSession``) exposes. Keep every such lookup
+here so a change in xdist has exactly one place to break.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+import pytest
+
+
+def is_distributed(config: pytest.Config) -> bool:
+    """True on a controller that is actually distributing tests (``-n`` > 0)."""
+    return config.pluginmanager.hasplugin("dsession")
+
+
+def is_worker(config: pytest.Config) -> bool:
+    return hasattr(config, "workerinput")
+
+
+def worker_id(report: pytest.TestReport) -> str | None:
+    """The gateway id (``gw0``) xdist attaches to reports on the controller."""
+    node = getattr(report, "node", None)
+    if node is None:
+        return None
+    gateway = getattr(node, "gateway", None)
+    ident = getattr(gateway, "id", None)
+    return str(ident) if ident is not None else None
+
+
+def node_id(node: Any) -> str:
+    return str(node.gateway.id)
+
+
+def gateway_id(gateway: Any) -> str:
+    return str(gateway.id)
+
+
+_ABSENT = object()
+
+
+def observe_gateway_creation(
+    config: pytest.Config, on_created: Callable[[str, float], None]
+) -> Callable[[], None] | None:
+    """Time every gateway creation on the controller's execnet group.
+
+    ``pytest_xdist_newgateway`` fires only after a gateway exists, and every hook-based
+    marker before it sits ahead of some of xdist's own work (hook wrappers' post-yield
+    code, preparing the remote module), so inferring a launch time from neighbouring
+    events always leaks the previous worker's work into the next boot span. Instead,
+    wrap the node manager's ``group.makegateway`` for the session: the timestamp is
+    taken immediately before the call and associated with the gateway it returns.
+    Covers initial workers and replacements alike. Returns a function that removes the
+    observer, or ``None`` when the group is not reachable (then nothing is patched).
+    """
+    dsession = config.pluginmanager.getplugin("dsession")
+    group = getattr(getattr(dsession, "nodemanager", None), "group", None)
+    original = getattr(group, "makegateway", None)
+    if group is None or original is None:
+        return None
+    # Another observer may already sit on the instance; keep it and put it back later.
+    previous = group.__dict__.get("makegateway", _ABSENT)
+
+    def makegateway(*args: Any, **kwargs: Any) -> Any:
+        started = time.time()
+        gateway = original(*args, **kwargs)
+        on_created(gateway_id(gateway), started)
+        return gateway
+
+    group.makegateway = makegateway
+
+    def restore() -> None:
+        if group.__dict__.get("makegateway") is not makegateway:
+            return  # someone else replaced it after us; not ours to touch
+        if previous is _ABSENT:
+            del group.__dict__["makegateway"]
+        else:
+            group.makegateway = previous
+
+    return restore
+
+
+class CollectionWatch:
+    """Observe what each worker collected, to recognise a genuine mismatch abort.
+
+    xdist's load-style schedulers abort when workers collect different node ids. They
+    announce it with a failed ``CollectReport`` whose nodeid is the disagreeing worker's
+    gateway id; but a worker can be given any id (``--tx popen//id=test_x.py``), so that
+    shape alone is ambiguous with a forwarded collection error from a file of the same
+    name. The abort is recognised only when this watch has itself seen two workers
+    collect different ids.
+    """
+
+    def __init__(self) -> None:
+        self._digests: dict[str, str] = {}
+
+    def collected(self, worker_id: str, ids: Any) -> None:
+        import hashlib
+
+        digest = hashlib.sha1("\0".join(str(i) for i in ids).encode("utf-8")).hexdigest()
+        self._digests[worker_id] = digest
+
+    @property
+    def differs(self) -> bool:
+        return len(set(self._digests.values())) > 1
+
+    def mismatch_reason(self, report: Any) -> str | None:
+        """The abort reason if ``report`` is the scheduler's mismatch announcement."""
+        if not self.differs:
+            return None
+        if getattr(report, "outcome", None) != "failed":
+            return None
+        nodeid = getattr(report, "nodeid", None)
+        if nodeid not in self._digests:
+            return None
+        longrepr = getattr(report, "longrepr", None)
+        if not isinstance(longrepr, str):
+            return None  # the scheduler's announcement is a plain message
+        first = longrepr.strip().splitlines()[0] if longrepr.strip() else "collections differ"
+        return f"{nodeid}: {first}"
+
+
+def stop_reason(config: pytest.Config) -> str | None:
+    """Why the controller decided to stop scheduling, if it did.
+
+    Covers ``-x`` / ``--maxfail`` relayed from workers and a worker keyboard interrupt.
+    A stop raises ``Interrupted`` out of the run loop, so it usually also surfaces as
+    ``pytest_keyboard_interrupt``; this is the fallback when it does not.
+    """
+    dsession = config.pluginmanager.getplugin("dsession")
+    value = getattr(dsession, "shouldstop", None)
+    return str(value) if value else None
+
+
+def abort_reason(config: pytest.Config) -> str | None:
+    """Why the controller shut down early without raising, if it did.
+
+    When a worker crashes and restarts are exhausted, ``DSession`` records the message
+    it prints in the terminal summary and triggers a quiet shutdown. A crash that was
+    recovered by restarting the worker leaves no such record, and the run completes.
+    """
+    dsession = config.pluginmanager.getplugin("dsession")
+    value = getattr(dsession, "_summary_report", None)
+    return str(value) if value else None
+
+
+def version() -> str | None:
+    import importlib.metadata
+
+    try:
+        return importlib.metadata.version("pytest-xdist")
+    except importlib.metadata.PackageNotFoundError:
+        return None

pytest_timing-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: pytest-timing
+Version: 0.1.0
+Summary: Record test timings under pytest-xdist and render cargo-style timing reports (ASCII Gantt and HTML).
+Project-URL: Homepage, https://github.com/messense/pytest-timing
+Author-email: messense <messense@icloud.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gantt,profiling,pytest,timing,xdist
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7.3
+Provides-Extra: xdist
+Requires-Dist: pytest-xdist>=3.0; extra == 'xdist'
+Description-Content-Type: text/markdown
+
+# pytest-timing
+
+Record when every test ran, on which [pytest-xdist](https://github.com/pytest-dev/pytest-xdist)
+worker, and for how long, then render the run as a timing report in the spirit of
+`cargo build --timings`: an ASCII Gantt chart in the terminal and a self-contained
+HTML report with worker lanes, a concurrency graph and a sortable table.
+
+```
+pytest -n 4 --timing --timing-html
+```
+
+```
+================================ timing report =================================
+pytest-timing: 129 tests (1 error, 1 failed), 4 workers, wall 1.37s, busy 95.4%
+worker |-----------|-----------|------------|-----------|-----------|--------  busy%
+gw0    ░░░░░░   ▄███████████████▄███████████████████████████████████████████    93.6%
+gw1    ░░░░░░░  ▄██████████████████████████████████████████████████X            94.1%
+gw2    ░░░░░░░░▒▄███████████████████████████████████████████████████▄           96.2%
+gw3    ░░░░░░░░░▄████████████████████████████████▄███████████XXXXX             98.2%
+       0s          0.20s       0.40s        0.60s       0.80s       1.00s 1.37s
+       legend: ░ boot  ▒ collect  █ tests  ▄ <50% busy  X failure
+
+slowest 3 tests (setup ░ / call █ / teardown ▒):
+gw0                                                    ████████████████████▒    0.36s
+       test_big.py::test_slow[5]
+gw2                                               ████████████████▒            0.30s
+       test_big.py::test_slow[4]
+gw1               ░░░░░░░░░░░░░▒                                               0.21s
+       test_big.py::test_many[8]
+HTML report written to pytest-timing.html
+```
+
+Works with and without `-n`. Without xdist the run is a single `main` lane.
+
+Each lane shows worker boot, collection, tests (`▄` marks a column that is under half busy,
+so idle gaps stand out) and failures. The slowest tests are drawn on the same axis with
+their setup / call / teardown split; note how the module-scoped fixture above lands in the
+setup phase of the first test on each worker.
+
+The HTML report has the same data with a zoomable lane Gantt, a concurrency graph, filters,
+hover details, and a sortable table:
+
+![HTML report](docs/report.png)
+
+## Install
+
+```
+pip install pytest-timing            # plugin only
+pip install "pytest-timing[xdist]"   # with pytest-xdist
+```
+
+Python 3.10+, pytest 7.3+ (the version that added wall-clock `start`/`stop` to test reports).
+
+## Usage
+
+| Option | Effect |
+|---|---|
+| `--timing` | Record timings and print the ASCII chart in the terminal summary. |
+| `--timing-html` | Write a self-contained HTML report to `pytest-timing.html`. |
+| `--timing-json` | Write the recorded run to `pytest-timing.json`. |
+| `--timing-trace` | Write a Chrome trace file for [Perfetto](https://ui.perfetto.dev) to `pytest-timing.trace.json`. |
+| `--timing-html-file PATH`, `--timing-json-file PATH`, `--timing-trace-file PATH` | Same, to an explicit path. |
+| `--timing-top=N` | Rows in the slowest-tests section (default 10, `0` hides it). |
+| `--timing-min=SECONDS` | Hide tests shorter than this from the slowest-tests section. |
+| `--timing-ascii-style=unicode\|ascii` | Chart glyphs. |
+| `--timing-width=N` | Override the terminal width for the chart. |
+
+Any output option implies `--timing`. The output flags are plain booleans and the `-file`
+options always take a path, so `pytest --timing-json test_x.py` runs exactly `test_x.py`.
+
+The same settings are accepted as ini keys (`timing`, `timing_html`, `timing_json`,
+`timing_trace` as paths or `true`, plus `timing_top`, `timing_min`, `timing_ascii_style`)
+and environment variables (`PYTEST_TIMING=1`, `PYTEST_TIMING_HTML=path`, ...), so CI can
+enable it without touching the command line.
+
+Every JSON run records how the session ended (`finished`, `collect_only`, `interrupted`,
+`aborted`, `internal_error`) with the reason pytest gave, and `complete` is derived from that.
+
+### View the trace
+
+`--timing-trace` writes a Chrome Trace Event file. Open it in
+[Perfetto UI](https://ui.perfetto.dev) with "Open trace file", or in `chrome://tracing`.
+Each worker is a track, every test is a bar, and the setup / call / teardown phases nest
+underneath it. Zoom with W/A/S/D and select a range to aggregate durations.
+
+### Re-render or merge saved runs
+
+```
+pytest-timing render pytest-timing.json --html report.html --ascii
+pytest-timing merge shard1.json shard2.json -o all.json
+```
+
+`merge` places several runs (for example CI shards) on one shared time axis using their
+absolute start times.
+
+## How it works
+
+Since pytest 7.3 every `TestReport` carries wall-clock `start` and `stop` timestamps. xdist
+serialises those to the controller unchanged and attaches the worker to the report, so the
+plugin only needs controller-side hooks: `pytest_runtest_logreport` for the setup / call /
+teardown phases, plus xdist's node-ready, collection-finished and node-down hooks for the
+worker lifecycle. Nothing runs inside the workers and nothing touches the execnet channel.
+
+Each lane in the report shows boot (worker start-up until it is ready), collection, tests,
+idle gaps and the point the worker shut down. Session-scoped fixture setup is attributed to
+the first test's setup phase and its teardown to the last test's teardown phase, exactly as
+pytest reports it.
+
+## Overhead
+
+Nothing runs inside the workers: the plugin only listens to the reports xdist already
+sends to the controller, and each of the three phase reports per test costs a few
+microseconds of bookkeeping. Rendering happens once, at the end of the session.
+
+Measured on 5,000 trivial tests (a worst case, since the per-test cost is fixed while the
+tests themselves take almost nothing), best of five runs:
+
+| Configuration | Wall time | Overhead |
+|---|---|---|
+| single process, plugin disabled | 1.29 s | |
+| single process, `--timing` | 1.38 s | +0.09 s |
+| single process, `--timing` plus JSON, HTML and trace files | 1.45 s | +0.16 s |
+| `-n 4`, plugin disabled | 1.18 s | |
+| `-n 4`, `--timing` | 1.25 s | +0.07 s |
+| `-n 4`, `--timing` plus all three files | 1.32 s | +0.14 s |
+
+That is under 20 microseconds per test for recording, plus a fixed serialisation cost per
+output file of roughly 10 ms per thousand tests. Output size is about 250 bytes per test
+for the JSON and HTML files and 600 bytes for the trace. Memory held during the run is on
+the same order as the JSON. The plugin registers nothing at all unless one of its options
+is enabled.
+
+## License
+
+MIT

pytest_timing-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+pytest_timing/__init__.py,sha256=XqvwgGSYCEapcf0BaHvba9XJuOoorW4ess_UNnumltY,146
+pytest_timing/cli.py,sha256=1LU-Sx2OmU-FAUM6oA_-ya_7bGqaZxwmNE21QWBkZ5o,5417
+pytest_timing/collector.py,sha256=YBxL2ELS7m2VIt_PTgKkfluNqbLjG2a5AG2KaTpImJs,8643
+pytest_timing/model.py,sha256=f8NXCoFMQ-IPn2z4QEv3dYYLQpgutUNRkv8PwfOWhok,18494
+pytest_timing/outputs.py,sha256=tRyRA2wR3U99ToTWqot0KJBntdnki2pGoCHivL_7mBY,1671
+pytest_timing/plugin.py,sha256=UJYAsgjpx7mD-BziZVF3kwD_x3IFYFYFrS7MtsdwSCo,15443
+pytest_timing/xdist_compat.py,sha256=iUT-vuOA77SxTvLlxSF677hs0UR_awotlac1fnsInhU,5993
+pytest_timing/render/__init__.py,sha256=oHRYmicsmVDtBkuH8330F9J8WIvHQJuwGdVN4ItSE_c,76
+pytest_timing/render/ascii.py,sha256=oAfQmpxu3EGFp52Ye3VpAkKtekMgkxwmtVwMSE-t0cc,9322
+pytest_timing/render/html.py,sha256=MNnXOW_w5_lRYE993n4UAnl-LYyNxZgTD-_THD22NZE,1032
+pytest_timing/render/trace.py,sha256=zTwPxFCMQyGCCJZnvAU2JtYLnWsifpS2GMYcJLHJ9D0,3881
+pytest_timing/static/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_timing/static/report.html,sha256=2q_WoeekdyNKD8hKlEoV8IhOxglMbZLb7lqduHkjQy8,38606
+pytest_timing-0.1.0.dist-info/METADATA,sha256=XJPSW7AmZedz16skF8gydecbFPn__d58t3j9C-Zgrg8,8077
+pytest_timing-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pytest_timing-0.1.0.dist-info/entry_points.txt,sha256=DCRyOBo-gKQW2s0SY5a_lW9Zzya49sVde-vklRBxDLo,99
+pytest_timing-0.1.0.dist-info/licenses/LICENSE,sha256=3Cd2jLg5VJrONe-6tuTRguU6hr5h7fniBENwTGIhZLg,1086
+pytest_timing-0.1.0.dist-info/RECORD,,

pytest_timing-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_timing-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+pytest-timing = pytest_timing.cli:main
+
+[pytest11]
+timing = pytest_timing.plugin

pytest_timing-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present Messense Lv
+
+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.