pytest-timing 0.1.0__py3-none-any.whl

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"

pytest_timing/cli.py

@@ -0,0 +1,150 @@
+"""``pytest-timing`` command line: re-render or merge saved JSON runs."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from pytest_timing.model import Run, RunInfo, TestSpan, Worker
+from pytest_timing.outputs import OUTPUTS, write_output
+from pytest_timing.render.ascii import render_ascii
+
+
+def _load(path: str) -> Run:
+    return Run.from_json(Path(path).read_text("utf-8"))
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    run = _load(args.run)
+    wrote = False
+    doc = None
+    for kind, output in OUTPUTS.items():
+        path = getattr(args, kind)
+        if path:
+            doc = doc or run.to_dict()
+            print(write_output(output, Path(path), run, doc))
+            wrote = True
+    if args.ascii or not wrote:
+        print(
+            render_ascii(
+                run,
+                width=args.width,
+                top=args.top,
+                min_duration=args.min,
+                style=args.style,
+                color=sys.stdout.isatty() and not args.no_color,
+            )
+        )
+    return 0
+
+
+def _uniquify(candidate: str, used: set[str]) -> str:
+    """``candidate``, or ``candidate#2``, ``#3``... until it is not in ``used``."""
+    name, n = candidate, 1
+    while name in used:
+        n += 1
+        name = f"{candidate}#{n}"
+    used.add(name)
+    return name
+
+
+def merge_runs(runs: list[Run], names: list[str]) -> Run:
+    """Place several runs on one shared axis.
+
+    Each run is rebased to the earliest start (``Run.rebased`` moves every time
+    together, so durations survive), and workers are relabelled so every input worker
+    stays a distinct lane. This function is the single owner of worker relabelling.
+    """
+    if not runs:
+        raise ValueError("nothing to merge")
+    if len(names) != len(runs):
+        raise ValueError("one name per run is required")
+    base = min(r.run.start for r in runs)
+    first = runs[0].run
+    info = RunInfo(
+        start=base,
+        stop=max(r.run.stop for r in runs),
+        termination=_merged_termination(runs),
+        reason=None,
+        exit_status=max((r.run.exit_status or 0) for r in runs),
+        argv=list(first.argv),
+        rootdir=first.rootdir,
+        python=first.python,
+        pytest=first.pytest,
+        xdist=first.xdist,
+        dist=first.dist,
+        numprocesses=sum(r.run.numprocesses or 0 for r in runs) or None,
+    )
+    distinct = {w for r in runs for w in r.worker_ids()}
+    collide = len(distinct) < sum(len(r.worker_ids()) for r in runs)
+    used: set[str] = set()
+    workers: list[Worker] = []
+    tests: list[TestSpan] = []
+    for run, name in zip(runs, names, strict=True):
+        mapping = {
+            wid: _uniquify(f"{name}/{wid}" if collide else wid, used) for wid in run.worker_ids()
+        }
+        placed = run.rebased(base).relabelled(mapping)
+        workers.extend(placed.workers)
+        tests.extend(placed.tests)
+    return Run(run=info, workers=workers, tests=tests)
+
+
+def _merged_termination(runs: list[Run]) -> str:
+    if all(r.run.complete for r in runs):
+        return "finished"
+    for candidate in ("internal_error", "aborted", "interrupted", "unknown"):
+        if any(r.run.termination == candidate for r in runs):
+            return candidate
+    return "unknown"
+
+
+def unique_names(paths: list[str]) -> list[str]:
+    """Short, distinct labels for input files: stems, then paths, then a counter."""
+    names = [Path(p).stem for p in paths]
+    if len(set(names)) == len(names):
+        return names
+    used: set[str] = set()
+    return [_uniquify(Path(p).with_suffix("").as_posix().lstrip("./"), used) for p in paths]
+
+
+def cmd_merge(args: argparse.Namespace) -> int:
+    runs = [_load(p) for p in args.runs]
+    merged = merge_runs(runs, unique_names(args.runs))
+    Path(args.output).write_text(merged.to_json(), encoding="utf-8")
+    print(f"merged {len(runs)} runs into {args.output}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pytest-timing", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    render = sub.add_parser("render", help="render a saved run (JSON) as ASCII, HTML or trace")
+    render.add_argument("run", help="pytest-timing JSON file")
+    for kind, output in OUTPUTS.items():
+        render.add_argument(f"--{kind}", metavar="PATH", help=f"write the {output.label}")
+    render.add_argument("--ascii", action="store_true", help="print the ASCII chart")
+    render.add_argument("--width", type=int, default=100)
+    render.add_argument("--top", type=int, default=10)
+    render.add_argument("--min", type=float, default=0.0, help="min duration for slowest tests")
+    render.add_argument("--style", choices=("unicode", "ascii"), default="unicode")
+    render.add_argument("--no-color", action="store_true")
+    render.set_defaults(func=cmd_render)
+
+    merge = sub.add_parser("merge", help="merge several runs (e.g. CI shards) onto one axis")
+    merge.add_argument("runs", nargs="+", help="pytest-timing JSON files")
+    merge.add_argument("-o", "--output", required=True, metavar="PATH")
+    merge.set_defaults(func=cmd_merge)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    result: int = args.func(args)
+    return result
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

pytest_timing/collector.py

@@ -0,0 +1,210 @@
+"""Fold pytest phase reports and xdist worker events into a :class:`Run`.
+
+The collector knows nothing about pytest objects; :mod:`pytest_timing.plugin`
+extracts plain values from reports and feeds them in. That keeps this module
+trivially unit-testable, and every operation here is O(1) per report.
+
+Identity is inferred, and the inference is deliberately narrow: reports carry only
+a nodeid and a worker, so when a ``setup`` report arrives for a nodeid whose previous
+span on that worker is closed, it is a new *attempt* of the same occurrence if that
+span was retried (outcome ``rerun``), and otherwise a new *occurrence* (a duplicate
+selection). Nothing else about identity is guessed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pytest_timing.model import PHASES, Phase, Run, RunInfo, TestSpan, Worker
+
+CRASH_WHEN = "???"  # xdist synthesises a report with this ``when`` for crashed items
+RETRIED = "rerun"
+
+
+@dataclass(slots=True)
+class PhaseReport:
+    """The subset of a pytest ``TestReport`` the collector needs."""
+
+    nodeid: str
+    when: str
+    outcome: str  # passed / failed / skipped / rerun as pytest (or a plugin) reports it
+    start: float  # epoch seconds, 0.0 when unknown
+    stop: float
+    duration: float
+    worker: str
+    wasxfail: bool = False
+    received: float = 0.0  # epoch seconds when the controller saw the report
+
+
+class Collector:
+    def __init__(self, run: RunInfo) -> None:
+        self.run = run
+        self.workers: dict[str, Worker] = {}
+        self.tests: list[TestSpan] = []
+        self._open: dict[tuple[str, str], TestSpan] = {}
+        self._last: dict[tuple[str, str], TestSpan] = {}
+        self._last_stop: dict[str, float] = {}  # when each worker's latest span closed
+
+    # ---- worker lifecycle ----------------------------------------------------------
+
+    def _worker(self, worker_id: str) -> Worker:
+        worker = self.workers.get(worker_id)
+        if worker is None:
+            worker = self.workers[worker_id] = Worker(id=worker_id)
+        return worker
+
+    def _rel(self, epoch: float) -> float:
+        return epoch - self.run.start
+
+    def worker_started(self, worker_id: str, epoch: float) -> None:
+        """The controller began launching this worker (also for replacements)."""
+        self._worker(worker_id).start = self._rel(epoch)
+
+    def worker_ready(self, worker_id: str, epoch: float) -> None:
+        self._worker(worker_id).ready = self._rel(epoch)
+
+    def worker_collected(self, worker_id: str, epoch: float, items: int) -> None:
+        worker = self._worker(worker_id)
+        worker.collected = self._rel(epoch)
+        worker.items = items
+
+    def worker_down(self, worker_id: str, epoch: float, error: str | None) -> None:
+        worker = self._worker(worker_id)
+        worker.down = self._rel(epoch)
+        if error:
+            worker.error = error
+        # Anything still open on this worker will never get a teardown.
+        for span in [s for s in self._open.values() if s.worker == worker_id]:
+            span.stop = max(span.stop, worker.down)
+            span.outcome = "crashed"
+            self._close(span)
+
+    # ---- phase reports -------------------------------------------------------------
+
+    def add_report(self, report: PhaseReport) -> None:
+        key = (report.worker, report.nodeid)
+        if report.worker not in self.workers:
+            self._worker(report.worker)
+
+        if report.when == CRASH_WHEN:
+            self._crash(key, report)
+            return
+
+        if report.start > 0 and report.stop > 0:
+            base = self.run.start
+            start, stop = report.start - base, report.stop - base
+        else:
+            start, stop = self._times(report)
+        span = self._open.get(key)
+        if report.when == "setup" or span is None:
+            if span is not None:
+                self._close(span)
+            span = self._new_span(key, start, stop)
+
+        span.phases[report.when] = Phase(start=start, stop=stop, duration=report.duration)
+        span.start = min(span.start, start)
+        span.stop = max(span.stop, stop)
+        self._apply_outcome(span, report)
+
+        if report.when == "teardown":
+            self._close(span)
+
+    def _new_span(self, key: tuple[str, str], start: float, stop: float) -> TestSpan:
+        worker, nodeid = key
+        previous = self._last.get(key)
+        if previous is None:
+            occurrence, attempt = 0, 0
+        elif previous.outcome == RETRIED:
+            occurrence, attempt = previous.occurrence, previous.attempt + 1
+        else:
+            occurrence, attempt = previous.occurrence + 1, 0
+        span = TestSpan(
+            nodeid=nodeid,
+            worker=worker,
+            occurrence=occurrence,
+            attempt=attempt,
+            outcome="passed",
+            start=start,
+            stop=stop,
+        )
+        self._open[key] = span
+        self._last[key] = span
+        self.tests.append(span)
+        return span
+
+    def _times(self, report: PhaseReport) -> tuple[float, float]:
+        if report.start > 0 and report.stop > 0:
+            return self._rel(report.start), self._rel(report.stop)
+        # pytest < 7.3 or a synthetic report: anchor on receipt time.
+        stop = self._rel(report.received) if report.received > 0 else 0.0
+        return max(0.0, stop - report.duration), stop
+
+    def _crash(self, key: tuple[str, str], report: PhaseReport) -> None:
+        now = self._rel(report.received) if report.received > 0 else None
+        span = self._open.get(key)
+        if span is None:
+            last = self._last.get(key)
+            if last is not None and last.outcome == "crashed":
+                # worker_down already closed it; the crash report only refines the end.
+                if now is not None:
+                    last.stop = max(last.stop, now)
+                return
+            # No phase report ever arrived: the test began when this lane last went idle.
+            start = self._last_stop.get(report.worker)
+            if start is None:
+                worker = self.workers[report.worker]
+                start = worker.collected if worker.collected is not None else worker.ready
+            span = self._new_span(key, start or 0.0, start or 0.0)
+        if now is not None:
+            span.stop = max(span.stop, now)
+        span.outcome = "crashed"
+        self._close(span)
+
+    @staticmethod
+    def _apply_outcome(span: TestSpan, report: PhaseReport) -> None:
+        if span.outcome in ("crashed", RETRIED):
+            return
+        if report.outcome == RETRIED:
+            # pytest-rerunfailures: this attempt failed and will be retried.
+            span.outcome = RETRIED
+        elif report.outcome == "failed":
+            span.outcome = "failed" if report.when == "call" else "error"
+        elif report.outcome == "skipped" and span.outcome == "passed":
+            span.outcome = "xfailed" if report.wasxfail else "skipped"
+        elif report.wasxfail and report.when == "call" and span.outcome == "passed":
+            span.outcome = "xpassed"
+
+    def _close(self, span: TestSpan) -> None:
+        self._open.pop((span.worker, span.nodeid), None)
+        previous = self._last_stop.get(span.worker, 0.0)
+        self._last_stop[span.worker] = max(previous, span.stop)
+
+    # ---- finish --------------------------------------------------------------------
+
+    def finish(self, epoch: float, *, termination: str, reason: str | None = None) -> Run:
+        self.run.stop = epoch
+        self.run.termination = termination
+        self.run.reason = reason
+        complete = self.run.complete
+        for span in list(self._open.values()):
+            if not complete:
+                # Still running when the session was interrupted.
+                span.stop = max(span.stop, self._rel(epoch))
+                if "teardown" not in span.phases:
+                    span.outcome = "crashed"
+            self._close(span)
+        # Give every span a stable phase order for serialisation.
+        for span in self.tests:
+            span.phases = {p: span.phases[p] for p in PHASES if p in span.phases} | {
+                p: v for p, v in span.phases.items() if p not in PHASES
+            }
+        workers = sorted(self.workers.values(), key=_worker_sort_key)
+        return Run(run=self.run, workers=workers, tests=list(self.tests))
+
+
+def _worker_sort_key(worker: Worker) -> tuple[int, int, str]:
+    """Sort gw0, gw1, ... gw10 numerically, anything else after."""
+    wid = worker.id
+    if wid.startswith("gw") and wid[2:].isdigit():
+        return (0, int(wid[2:]), wid)
+    return (1, 0, wid)