pytest-timing 0.1.0__tar.gz

pytest_timing-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: py${{ matrix.python }} / pytest ${{ matrix.pytest }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        pytest: ["latest"]
+        include:
+          - { os: ubuntu-latest, python: "3.10", pytest: "7.3" }
+          - { os: ubuntu-latest, python: "3.11", pytest: "7.4" }
+          - { os: ubuntu-latest, python: "3.12", pytest: "8.0" }
+          - { os: windows-latest, python: "3.12", pytest: "latest" }
+          - { os: macos-latest, python: "3.13", pytest: "latest" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: |
+          uv sync --no-dev
+          uv pip install pytest-xdist pytest-rerunfailures hypothesis
+          if [ "${{ matrix.pytest }}" != "latest" ]; then uv pip install "pytest~=${{ matrix.pytest }}.0"; fi
+        shell: bash
+      - name: Test
+        run: uv run --no-sync pytest -v -p no:cacheprovider
+
+  no-xdist:
+    name: without pytest-xdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --no-dev
+      - run: uv pip install hypothesis
+      - run: uv run --no-sync pytest -v -p no:cacheprovider
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy

pytest_timing-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,17 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

pytest_timing-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+pytest-timing.html
+pytest-timing.json
+pytest-timing.trace.json

pytest_timing-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Output options are boolean flags (`--timing-json`) with separate `--timing-json-file PATH`
+  options, so an output flag can never swallow a test path.
+- Runs record their termination (`finished`, `interrupted`, `aborted`, ...) explicitly.
+- Initial release: controller-side timing capture with and without pytest-xdist,
+  ASCII Gantt chart in the terminal summary, self-contained HTML report, JSON output,
+  Chrome trace output, and a `pytest-timing` CLI with `render` and `merge` commands.

pytest_timing-0.1.0/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.

pytest_timing-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,135 @@
+# 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/examples/test_demo.py

@@ -0,0 +1,41 @@
+"""Small demo suite for trying pytest-timing. Run it with:
+
+    uv run pytest examples -n 3 --timing --timing-html
+"""
+
+import time
+
+import pytest
+
+
+@pytest.fixture(scope="module")
+def database():
+    time.sleep(0.3)  # expensive module fixture: shows up as setup on the first test per worker
+    yield
+
+
+@pytest.fixture
+def client(database):
+    time.sleep(0.05)
+    yield
+    time.sleep(0.02)
+
+
+@pytest.mark.parametrize("i", range(12))
+def test_api(client, i):
+    time.sleep(0.02 * (i % 4 + 1))
+
+
+@pytest.mark.parametrize("i", range(3))
+def test_slow(i):
+    time.sleep(0.2 + 0.1 * i)
+
+
+def test_fails():
+    time.sleep(0.05)
+    assert 1 == 2
+
+
+@pytest.mark.skip(reason="demo")
+def test_skipped():
+    pass

pytest_timing-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytest-timing"
+version = "0.1.0"
+description = "Record test timings under pytest-xdist and render cargo-style timing reports (ASCII Gantt and HTML)."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "messense", email = "messense@icloud.com" }]
+keywords = ["pytest", "xdist", "timing", "gantt", "profiling"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Pytest",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = ["pytest>=7.3"]
+
+[project.optional-dependencies]
+xdist = ["pytest-xdist>=3.0"]
+
+[project.urls]
+Homepage = "https://github.com/messense/pytest-timing"
+
+[project.entry-points.pytest11]
+timing = "pytest_timing.plugin"
+
+[project.scripts]
+pytest-timing = "pytest_timing.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest-xdist>=3.0",
+  "pytest-rerunfailures>=12",
+  "hypothesis>=6",
+  "ruff>=0.6",
+  "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_timing"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p pytester"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src"]

pytest_timing-0.1.0/src/pytest_timing/__init__.py

@@ -0,0 +1,5 @@
+"""pytest-timing: record test timings under pytest-xdist and render timing reports."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"