pytest-timing 0.1.0__py3-none-any.whl

pytest_timing/plugin.py

@@ -0,0 +1,382 @@
+"""pytest hooks: capture timings on the controller process and emit reports.
+
+Two rules keep this adapter honest:
+
+* Options are unambiguous. Boolean flags turn an output on; ``*-file`` options take a
+  required path. Nothing has an optional value, so argparse can never mistake a test
+  path for a report path however the plugin is loaded.
+* Termination is recorded as it happens (``pytest_keyboard_interrupt``,
+  ``pytest_internalerror``, xdist's stop and abort reasons) and ``complete`` is derived
+  from that record, never from counting tests.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from pytest_timing import xdist_compat
+from pytest_timing.collector import Collector, PhaseReport
+from pytest_timing.model import Run, RunInfo
+from pytest_timing.outputs import OUTPUTS, write_output
+from pytest_timing.render.ascii import render_ascii
+
+MAIN_LANE = "main"
+DEFAULT_TOP = 10
+DEFAULT_MIN = 0.0
+ASCII_STYLES = ("unicode", "ascii")
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("timing", "test timing reports (pytest-timing)")
+    group.addoption(
+        "--timing",
+        action="store_true",
+        default=False,
+        help="Record test timings and print an ASCII Gantt chart in the terminal summary.",
+    )
+    for kind, output in OUTPUTS.items():
+        group.addoption(
+            f"--timing-{kind}",
+            action="store_true",
+            default=False,
+            help=f"Write the {output.label} to {output.default}. Implies --timing.",
+        )
+        group.addoption(
+            f"--timing-{kind}-file",
+            metavar="PATH",
+            default=None,
+            help=f"Write the {output.label} to PATH. Implies --timing-{kind}.",
+        )
+    group.addoption(
+        "--timing-top",
+        type=int,
+        default=None,
+        metavar="N",
+        help=f"Rows in the slowest-tests section of the ASCII chart (default: {DEFAULT_TOP}, "
+        "0 hides the section).",
+    )
+    group.addoption(
+        "--timing-min",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help="Hide tests shorter than this in the slowest-tests section (default: 0).",
+    )
+    group.addoption(
+        "--timing-ascii-style",
+        choices=ASCII_STYLES,
+        default=None,
+        help="Characters used for the ASCII chart: unicode (default) or ascii.",
+    )
+    group.addoption(
+        "--timing-width",
+        type=int,
+        default=None,
+        metavar="COLUMNS",
+        help="Override the terminal width used for the ASCII chart.",
+    )
+    parser.addini("timing", "Enable pytest-timing (same as --timing).", type="bool", default=False)
+    for kind, output in OUTPUTS.items():
+        parser.addini(
+            f"timing_{kind}",
+            f"Path for the {output.label} (implies timing); 'true' uses {output.default}.",
+            default="",
+        )
+    parser.addini("timing_top", "Rows in the slowest-tests section.", default="")
+    parser.addini("timing_min", "Minimum duration for the slowest-tests section.", default="")
+    parser.addini("timing_ascii_style", "unicode or ascii.", default="")
+
+
+_TRUE = ("1", "true", "yes", "on")
+
+
+class Settings:
+    """Resolved configuration: command line, then environment, then ini."""
+
+    def __init__(self, config: pytest.Config) -> None:
+        self.outputs: dict[str, Path] = {}
+        for kind, output in OUTPUTS.items():
+            path = self._output_path(config, kind, output.default)
+            if path is not None:
+                self.outputs[kind] = path
+        top = self._value(config, "timing_top", "PYTEST_TIMING_TOP")
+        self.top = int(top) if top is not None else DEFAULT_TOP
+        minimum = self._value(config, "timing_min", "PYTEST_TIMING_MIN")
+        self.min_duration = float(minimum) if minimum is not None else DEFAULT_MIN
+        style = self._value(config, "timing_ascii_style", "PYTEST_TIMING_ASCII_STYLE")
+        if style is not None and style not in ASCII_STYLES:
+            raise pytest.UsageError(
+                f"timing_ascii_style must be one of {', '.join(ASCII_STYLES)}, not {style!r}"
+            )
+        self.ascii_style = str(style) if style is not None else "unicode"
+        width = config.getoption("timing_width", None)
+        self.width = int(width) if width else None
+        env = os.environ.get("PYTEST_TIMING", "").lower()
+        self.enabled = bool(
+            config.getoption("timing", False)
+            or env in _TRUE
+            or config.getini("timing")
+            or self.outputs
+        )
+
+    @staticmethod
+    def _value(config: pytest.Config, name: str, env: str, ini: str | None = None) -> Any:
+        """One precedence rule for every setting: option, then environment, then ini."""
+        value = config.getoption(name, None)
+        if value is not None:
+            return value
+        if os.environ.get(env):
+            return os.environ[env]
+        value = config.getini(ini or name)
+        return value if value not in ("", None) else None
+
+    @classmethod
+    def _output_path(cls, config: pytest.Config, kind: str, default: str) -> Path | None:
+        """``--timing-<kind>-file`` wins, then the flag, then env / ini values.
+
+        Env and ini values are paths, or ``true`` for the default file name.
+        """
+        explicit = config.getoption(f"timing_{kind}_file", None)
+        if explicit:
+            value = str(explicit)  # a path, verbatim: never a boolean alias
+        elif config.getoption(f"timing_{kind}", False):
+            value = default
+        else:
+            env = os.environ.get(f"PYTEST_TIMING_{kind.upper()}") or config.getini(f"timing_{kind}")
+            if not env:
+                return None
+            value = default if str(env).lower() in _TRUE else str(env)
+        path = Path(value)
+        return path if path.is_absolute() else Path(config.rootpath, path)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    if xdist_compat.is_worker(config):
+        return  # xdist worker: everything happens on the controller
+    settings = Settings(config)
+    if settings.enabled:
+        config.pluginmanager.register(TimingPlugin(config, settings), "pytest_timing")
+
+
+class TimingPlugin:
+    def __init__(self, config: pytest.Config, settings: Settings) -> None:
+        self.config = config
+        self.settings = settings
+        self.collector = Collector(self._run_info())
+        self.result: Run | None = None
+        self.written: list[str] = []
+        self.errors: list[str] = []
+        # Lifecycle evidence, recorded as it happens.
+        self.termination: str | None = None
+        self.reason: str | None = None
+        self._collections = xdist_compat.CollectionWatch()
+        self._stop_observing: Callable[[], None] | None = None
+
+    @property
+    def distributed(self) -> bool:
+        return xdist_compat.is_distributed(self.config)
+
+    # ---- session -------------------------------------------------------------------
+
+    def _run_info(self) -> RunInfo:
+        config = self.config
+        return RunInfo(
+            start=time.time(),
+            stop=0.0,
+            argv=list(config.invocation_params.args),
+            rootdir=str(config.rootpath),
+            python=platform.python_version(),
+            pytest=pytest.__version__,
+            xdist=xdist_compat.version() if config.pluginmanager.hasplugin("xdist") else None,
+        )
+
+    @pytest.hookimpl(tryfirst=True)
+    def pytest_sessionstart(self) -> None:
+        """Runs before xdist launches its workers, so their start events have a home."""
+        config = self.config
+        if self.distributed:
+            dist = config.getoption("dist", None)
+            numprocesses = config.getoption("numprocesses", None)
+            self.collector.run.dist = str(dist) if dist else None
+            self.collector.run.numprocesses = (
+                int(numprocesses) if isinstance(numprocesses, int) else None
+            )
+        else:
+            now = time.time()
+            self.collector.worker_started(MAIN_LANE, self.collector.run.start)
+            self.collector.worker_ready(MAIN_LANE, now)
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_collection_finish(self, session: pytest.Session) -> None:
+        if not self.distributed:
+            self.collector.worker_collected(MAIN_LANE, time.time(), len(session.items))
+
+    def pytest_collectreport(self, report: Any) -> None:
+        if self.distributed:
+            reason = self._collections.mismatch_reason(report)
+            if reason:
+                self._record("aborted", reason)
+
+    # ---- termination evidence ------------------------------------------------------
+
+    def pytest_keyboard_interrupt(self, excinfo: Any) -> None:
+        """Fired for KeyboardInterrupt, ``pytest.exit()`` (any return code) and xdist's
+        ``Interrupted``; the run loop did not finish on its own."""
+        self._record("interrupted", _describe(excinfo))
+
+    def pytest_internalerror(self, excrepr: Any) -> None:
+        lines = str(excrepr).strip().splitlines()
+        self._record("internal_error", lines[-1] if lines else None)
+
+    def _record(self, termination: str, reason: Any) -> None:
+        if self.termination is None:
+            self.termination = termination
+            self.reason = reason if isinstance(reason, str) or reason is None else str(reason)
+
+    def _termination(self, session: pytest.Session) -> tuple[str, str | None]:
+        if self.termination is not None:
+            return self.termination, self.reason
+        if self.config.getoption("collectonly", False):
+            return "collect_only", None
+        for attr in ("shouldfail", "shouldstop"):
+            value = getattr(session, attr, False)
+            if value:
+                return "interrupted", str(value)
+        if self.distributed:
+            reason = xdist_compat.stop_reason(self.config)
+            if reason:
+                return "interrupted", reason
+            reason = xdist_compat.abort_reason(self.config)
+            if reason:
+                return "aborted", reason
+        return "finished", None
+
+    # ---- xdist worker lifecycle (optionalhook: xdist may not be installed) -----------
+
+    @pytest.hookimpl(optionalhook=True)
+    def pytest_xdist_setupnodes(self) -> None:
+        """Before any gateway exists: time each creation as it happens."""
+        self._stop_observing = xdist_compat.observe_gateway_creation(
+            self.config, self.collector.worker_started
+        )
+        if self._stop_observing is not None:
+            # Also at unconfigure: a failed worker start-up never reaches sessionfinish.
+            self.config.add_cleanup(self._stop_observing_now)
+
+    @pytest.hookimpl(optionalhook=True)
+    def pytest_xdist_newgateway(self, gateway: Any) -> None:
+        """Fallback when the creation call could not be observed: the gateway exists
+        now, and nothing earlier is known."""
+        if self._stop_observing is None:
+            self.collector.worker_started(xdist_compat.gateway_id(gateway), time.time())
+
+    @pytest.hookimpl(optionalhook=True)
+    def pytest_testnodeready(self, node: Any) -> None:
+        self.collector.worker_ready(xdist_compat.node_id(node), time.time())
+
+    @pytest.hookimpl(optionalhook=True)
+    def pytest_xdist_node_collection_finished(self, node: Any, ids: Any) -> None:
+        worker = xdist_compat.node_id(node)
+        self._collections.collected(worker, ids)
+        self.collector.worker_collected(worker, time.time(), len(ids))
+
+    @pytest.hookimpl(optionalhook=True)
+    def pytest_testnodedown(self, node: Any, error: object) -> None:
+        message = None if error is None else str(error)
+        self.collector.worker_down(xdist_compat.node_id(node), time.time(), message)
+
+    # ---- reports -------------------------------------------------------------------
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        # Called three times per test: keep it to attribute reads and one object.
+        start = getattr(report, "start", 0.0)
+        stop = getattr(report, "stop", 0.0)
+        self.collector.add_report(
+            PhaseReport(
+                nodeid=report.nodeid,
+                when=report.when,
+                outcome=report.outcome,
+                start=start,
+                stop=stop,
+                duration=report.duration,
+                worker=xdist_compat.worker_id(report) or MAIN_LANE,
+                wasxfail=hasattr(report, "wasxfail"),
+                # Receipt time is only needed when the report carries no clock of its own.
+                received=time.time() if not (start and stop) else 0.0,
+            )
+        )
+
+    # ---- finish and output ---------------------------------------------------------
+
+    def _stop_observing_now(self) -> None:
+        if self._stop_observing is not None:
+            self._stop_observing()
+            self._stop_observing = None
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        self._stop_observing_now()
+        now = time.time()
+        if not self.distributed:
+            self.collector.worker_down(MAIN_LANE, now, None)
+        termination, reason = self._termination(session)
+        self.collector.run.exit_status = int(exitstatus)
+        self.result = self.collector.finish(now, termination=termination, reason=reason)
+        self._write_outputs(self.result)
+
+    def _write_outputs(self, run: Run) -> None:
+        if not self.settings.outputs:
+            return
+        doc = run.to_dict()  # serialised once, shared by every output
+        for kind, path in self.settings.outputs.items():
+            output = OUTPUTS[kind]
+            try:
+                self.written.append(write_output(output, path, run, doc))
+            except Exception as exc:  # pragma: no cover - reported, never fatal
+                self.errors.append(f"could not write {output.label} to {path}: {exc}")
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_terminal_summary(self, terminalreporter: Any) -> None:
+        run = self.result
+        if run is None:
+            return
+        tr = terminalreporter
+        width = self.settings.width or _terminal_width(tr)
+        tr.write_sep("=", "timing report")
+        text = render_ascii(
+            run,
+            width=width,
+            top=self.settings.top,
+            min_duration=self.settings.min_duration,
+            style=self.settings.ascii_style,
+            color=bool(getattr(tr, "hasmarkup", False)),
+        )
+        for line in text.splitlines():
+            tr.write_line(line)
+        for line in self.written:
+            tr.write_line(line.replace(str(self.config.rootpath) + os.sep, "", 1))
+        for error in self.errors:
+            tr.write_line(error, red=True)
+
+
+def _describe(excinfo: Any) -> str:
+    value = getattr(excinfo, "value", excinfo)
+    text = str(getattr(value, "msg", "") or value or "").strip()
+    name = type(value).__name__
+    return f"{name}: {text}" if text else name
+
+
+def _terminal_width(terminalreporter: Any) -> int:
+    writer = getattr(terminalreporter, "_tw", None)
+    width = getattr(writer, "fullwidth", None)
+    if isinstance(width, int) and width > 0:
+        return width
+    return shutil.get_terminal_size().columns

pytest_timing/render/__init__.py

@@ -0,0 +1 @@
+"""Renderers that turn a :class:`pytest_timing.model.Run` into a report."""

pytest_timing/render/ascii.py

@@ -0,0 +1,283 @@
+"""Terminal renderer: worker lanes plus a slowest-tests Gantt on a shared axis."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from itertools import groupby
+
+from pytest_timing.model import BAD_OUTCOMES, Lane, Run, TestSpan
+
+MIN_CHART = 20
+TICK_STEPS = (0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 1800, 3600)
+
+
+@dataclass(frozen=True)
+class Glyphs:
+    boot: str
+    collect: str
+    idle: str
+    test: str
+    partial: str
+    bad: str
+    setup: str
+    call: str
+    teardown: str
+    ellipsis: str
+
+
+STYLES: dict[str, Glyphs] = {
+    "unicode": Glyphs(
+        boot="░",
+        collect="▒",
+        idle=" ",
+        test="█",
+        partial="▄",
+        bad="X",
+        setup="░",
+        call="█",
+        teardown="▒",
+        ellipsis="…",
+    ),
+    "ascii": Glyphs(
+        boot=".",
+        collect=":",
+        idle=" ",
+        test="#",
+        partial="+",
+        bad="X",
+        setup="-",
+        call="#",
+        teardown="=",
+        ellipsis="...",
+    ),
+}
+
+_RED = "\x1b[31m"
+_BOLD = "\x1b[1m"
+_DIM = "\x1b[2m"
+_RESET = "\x1b[0m"
+
+
+def format_seconds(seconds: float) -> str:
+    if seconds < 0:
+        seconds = 0.0
+    if seconds < 10:
+        return f"{seconds:.2f}s"
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes, rest = divmod(seconds, 60)
+    if seconds < 3600:
+        return f"{int(minutes)}m{rest:02.0f}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{int(hours)}h{int(minutes):02d}m"
+
+
+def render_ascii(
+    run: Run,
+    *,
+    width: int = 80,
+    top: int = 10,
+    min_duration: float = 0.0,
+    style: str = "unicode",
+    color: bool = False,
+) -> str:
+    glyphs = STYLES.get(style, STYLES["unicode"])
+    lanes = run.lanes()
+    label_width = max([len(lane.id) for lane in lanes] + [6])
+    suffix_width = 8  # "  99.9%"
+    chart = max(MIN_CHART, width - label_width - 1 - suffix_width)
+    total = max(run.wall, 1e-9)
+    scale = Scale(total, chart)
+
+    lines: list[str] = [_header(run, lanes, color)]
+    if not run.tests and not run.workers:
+        lines.append("no tests recorded")
+        return "\n".join(lines)
+
+    axis, labels = _axis(scale)
+    lines.append(f"{'worker':<{label_width}} {axis}  busy%")
+    for lane in lanes:
+        row, busy = _lane_row(lane, scale, glyphs)
+        lines.append(f"{lane.id:<{label_width}} {_colorize(row, glyphs, color)}  {busy:5.1f}%")
+    lines.append(f"{'':<{label_width}} {labels}")
+    lines.append(
+        f"{'':<{label_width}} legend: {glyphs.boot} boot  {glyphs.collect} collect  "
+        f"{glyphs.test} tests  {glyphs.partial} <50% busy  {glyphs.bad} failure"
+    )
+
+    if top:
+        candidates = [t for t in run.tests if t.duration >= min_duration]
+        candidates.sort(key=lambda t: t.duration, reverse=True)
+        slowest = candidates[:top]
+        if slowest:
+            lines.append("")
+            lines.append(
+                f"slowest {len(slowest)} tests (setup {glyphs.setup} / call {glyphs.call} / "
+                f"teardown {glyphs.teardown}):"
+            )
+            for test in slowest:
+                bar = _test_bar(test, scale, glyphs)
+                if color and test.is_bad:
+                    bar = f"{_RED}{bar}{_RESET}"
+                duration = f"{format_seconds(test.duration):>7}"
+                lines.append(f"{test.worker:<{label_width}} {bar} {duration}")
+                nodeid = _fit_nodeid(test.nodeid, width - label_width - 1, glyphs.ellipsis)
+                lines.append(f"{'':<{label_width}} {nodeid}")
+    return "\n".join(lines)
+
+
+class Scale:
+    def __init__(self, total: float, columns: int) -> None:
+        self.total = total
+        self.columns = columns
+        self.per_column = total / columns
+
+    def col(self, seconds: float) -> int:
+        value = int(seconds / self.total * self.columns)
+        return min(self.columns - 1, max(0, value))
+
+    def span(self, start: float, stop: float) -> tuple[int, int]:
+        """Half-open column range that a [start, stop] interval covers, at least one wide."""
+        first = self.col(start)
+        last = max(first + 1, min(self.columns, int(round(stop / self.total * self.columns))))
+        return first, last
+
+    def overlaps(self, start: float, stop: float, *targets: list[float]) -> None:
+        """Add the seconds that [start, stop] overlaps each column into every target."""
+        if stop <= start:
+            return
+        first = self.col(start)
+        last = min(self.columns, max(first + 1, math.ceil(stop / self.per_column)))
+        for column in range(first, last):
+            lo = column * self.per_column
+            hi = lo + self.per_column
+            overlap = max(0.0, min(stop, hi) - max(start, lo))
+            for target in targets:
+                target[column] += overlap
+
+
+def _header(run: Run, lanes: list[Lane], color: bool) -> str:
+    counts = run.outcome_counts()
+    bad = {k: v for k, v in counts.items() if k in BAD_OUTCOMES}
+    tests = f"{len(run.tests)} tests"
+    if bad:
+        detail = ", ".join(f"{n} {k}" for k, n in sorted(bad.items()))
+        detail = f"{_RED}{detail}{_RESET}" if color else detail
+        tests += f" ({detail})"
+    from pytest_timing.model import _utilisation
+
+    workers = len(lanes)
+    lane = "worker" if workers == 1 else "workers"
+    parts = [
+        f"pytest-timing: {tests}",
+        f"{workers} {lane}",
+        f"wall {format_seconds(run.wall)}",
+        f"busy {_utilisation(lanes) * 100:.1f}%",
+    ]
+    if not run.run.complete:
+        ended = f"ended: {run.run.termination_label}"
+        if run.run.reason:
+            ended += f" ({run.run.reason})"
+        parts.append(f"{_RED}{ended}{_RESET}" if color else ended)
+    return ", ".join(parts)
+
+
+def _axis(scale: Scale) -> tuple[str, str]:
+    step = next((s for s in TICK_STEPS if s / scale.per_column >= 8), TICK_STEPS[-1])
+    axis = ["-"] * scale.columns
+    labels = [" "] * scale.columns
+    tick = 0.0
+    while tick < scale.total:
+        column = int(tick / scale.per_column)
+        if column >= scale.columns:
+            break
+        axis[column] = "|"
+        text = format_seconds(tick) if tick else "0s"
+        if column + len(text) <= scale.columns and all(
+            labels[i] == " " for i in range(column, column + len(text))
+        ):
+            for i, ch in enumerate(text):
+                labels[column + i] = ch
+        tick += step
+    end = format_seconds(scale.total)
+    start = scale.columns - len(end)
+    if start > 0 and all(labels[i] == " " for i in range(start - 1, scale.columns)):
+        for i, ch in enumerate(end):
+            labels[start + i] = ch
+    return "".join(axis), "".join(labels).rstrip()
+
+
+def _lane_row(lane: Lane, scale: Scale, glyphs: Glyphs) -> tuple[str, float]:
+    columns = scale.columns
+    test_time = [0.0] * columns
+    bad_time = [0.0] * columns
+    for span in lane.spans:
+        if span.is_bad:
+            scale.overlaps(span.start, span.stop, test_time, bad_time)
+        else:
+            scale.overlaps(span.start, span.stop, test_time)
+
+    boot_time = [0.0] * columns
+    collect_time = [0.0] * columns
+    if lane.boot:
+        scale.overlaps(*lane.boot, boot_time)
+    if lane.collect:
+        scale.overlaps(*lane.collect, collect_time)
+
+    row: list[str] = []
+    for i in range(columns):
+        lo = i * scale.per_column
+        hi = lo + scale.per_column
+        in_window = max(0.0, min(lane.down, hi) - max(0.0, lo)) > 0
+        if bad_time[i] > 0:
+            row.append(glyphs.bad)
+        elif test_time[i] >= scale.per_column * 0.5:
+            row.append(glyphs.test)
+        elif test_time[i] > 0:
+            row.append(glyphs.partial)
+        elif boot_time[i] > 0 and boot_time[i] >= collect_time[i]:
+            row.append(glyphs.boot)
+        elif collect_time[i] > 0:
+            row.append(glyphs.collect)
+        elif in_window:
+            row.append(glyphs.idle)
+        else:
+            row.append(" ")
+    window = max(lane.down - lane.ready, 1e-9)
+    return "".join(row), min(100.0, lane.busy / window * 100)
+
+
+def _test_bar(test: TestSpan, scale: Scale, glyphs: Glyphs) -> str:
+    row = [" "] * scale.columns
+    phase_glyphs = (("setup", glyphs.setup), ("call", glyphs.call), ("teardown", glyphs.teardown))
+    for name, glyph in phase_glyphs:
+        phase = test.phases.get(name)
+        if phase is None:
+            continue
+        first, last = scale.span(phase.start, phase.stop)
+        for i in range(first, last):
+            row[i] = glyph
+    if not test.phases:
+        first, last = scale.span(test.start, test.stop)
+        for i in range(first, last):
+            row[i] = glyphs.bad if test.is_bad else glyphs.call
+    return "".join(row)
+
+
+def _fit_nodeid(nodeid: str, room: int, ellipsis: str) -> str:
+    if room >= len(nodeid) or room < 8 + len(ellipsis):
+        return nodeid
+    return ellipsis + nodeid[-(room - len(ellipsis)) :]
+
+
+def _colorize(row: str, glyphs: Glyphs, color: bool) -> str:
+    if not color:
+        return row
+    styles = {glyphs.bad: f"{_RED}{_BOLD}", glyphs.boot: _DIM, glyphs.collect: _DIM}
+    out: list[str] = []
+    for ch, group in groupby(row):
+        run = "".join(group)
+        style = styles.get(ch)
+        out.append(f"{style}{run}{_RESET}" if style else run)
+    return "".join(out)

pytest_timing/render/html.py

@@ -0,0 +1,32 @@
+"""Self-contained HTML report: the static template with the run JSON embedded."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any
+
+from pytest_timing.model import Run
+
+PLACEHOLDER = "__PYTEST_TIMING_DATA__"
+
+
+def load_template() -> str:
+    return resources.files("pytest_timing.static").joinpath("report.html").read_text("utf-8")
+
+
+def embed_json(doc: dict[str, Any]) -> str:
+    """Compact JSON that is safe inside a ``<script type="application/json">`` element."""
+    text = json.dumps(doc, separators=(",", ":"), ensure_ascii=False)
+    return text.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
+
+
+def render_html_doc(run: Run, doc: dict[str, Any]) -> str:
+    template = load_template()
+    if PLACEHOLDER not in template:
+        raise RuntimeError("report template is missing the data placeholder")
+    return template.replace(PLACEHOLDER, embed_json(doc), 1)
+
+
+def render_html(run: Run) -> str:
+    return render_html_doc(run, run.to_dict())