feat: plot -o exports an image when the suffix is static (png/svg/pdf/...)

`plot -o out.png` always wrote HTML regardless of the extension. Branch on the
output suffix instead: .png/.svg/.pdf/.jpg/.jpeg/.webp go through kaleido's
write_image, .html (or a bare name) stays interactive HTML, and an unrecognised
suffix is rejected rather than silently written as HTML.

kaleido lives in a new optional [plot-static] extra so interactive-HTML [plot]
stays lightweight; a missing-kaleido image export fails with a clear Exit(2)
naming the install.

Closes #145

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FBumann

docs/reference.md

@@ -181,6 +181,10 @@ live from the typer app as it actually renders in a terminal:
     :width: 100
     :scheme: osx
 
+`plot -o` picks the writer from the suffix: `.html` (the default) is an interactive plotly
+page, while `.png` / `.svg` / `.pdf` / `.jpg` / `.webp` export a static image for a PR comment,
+README, or docs page. Static export needs kaleido — install `pytest-benchmem[plot-static]`.
+
 ## Public Python API
 
 Light to import — `pytest_benchmem` re-exports only the engine and the readers;

pyproject.toml

@@ -27,6 +27,9 @@ dependencies = [
 
 [project.optional-dependencies]
 plot = ["pandas", "plotly>=5", "typer>=0.12"]
+# kaleido (and a Chromium it drives) is only needed to export a plot as a static image
+# (plot -o out.png / .svg / .pdf); kept out of [plot] so interactive HTML stays lightweight.
+plot-static = ["pytest-benchmem[plot]", "kaleido"]
 
 [project.scripts]
 benchmem = "pytest_benchmem.cli:app"
@@ -49,7 +52,7 @@ source = "vcs"
 
 [dependency-groups]
 # mypy <2.1: 2.1.0 errors on numpy's PEP 695 stub under python_version=3.11. Lift once fixed upstream.
-dev = ["ruff", "mypy<2.2", "pre-commit", "pytest-benchmem[plot]", { include-group = "docs" }]
+dev = ["ruff", "mypy<2.2", "pre-commit", "pytest-benchmem[plot-static]", { include-group = "docs" }]
 docs = [
     "jupytext",
     "ipykernel",

src/pytest_benchmem/cli.py

@@ -78,6 +78,35 @@ def _need_plotly() -> None:
         raise _fail("plotting needs extras: pip install 'pytest-benchmem[plot]'", 2)
 
 
+# Static raster/vector suffixes go through kaleido's write_image; .html (or a bare name) stays
+# interactive HTML. Anything else is a typo we refuse rather than silently writing HTML.
+_IMAGE_SUFFIXES = frozenset({".png", ".svg", ".pdf", ".jpg", ".jpeg", ".webp"})
+_HTML_SUFFIXES = frozenset({"", ".html", ".htm"})
+
+
+def _write_figure(fig: object, output: Path) -> None:
+    """Export ``fig`` to ``output``, choosing write_image vs write_html by the suffix.
+
+    Image suffixes need kaleido (the ``[plot-static]`` extra); raise a clear Exit(2) naming
+    the install when it is absent. An unrecognised suffix is rejected rather than silently
+    written as HTML.
+    """
+    suffix = output.suffix.lower()
+    if suffix in _IMAGE_SUFFIXES:
+        if importlib.util.find_spec("kaleido") is None:
+            raise _fail(
+                f"{suffix} export needs kaleido: pip install 'pytest-benchmem[plot-static]' "
+                f"(or use an .html output for the interactive plot)",
+                2,
+            )
+        fig.write_image(output)  # type: ignore[attr-defined]
+    elif suffix in _HTML_SUFFIXES:
+        fig.write_html(output)  # type: ignore[attr-defined]
+    else:
+        supported = ", ".join(sorted(_IMAGE_SUFFIXES | {".html"}))
+        raise _fail(f"unsupported output suffix {suffix!r}; use one of: {supported}", 2)
+
+
 def _parse_where(items: list[str] | None) -> dict[str, str] | None:
     """Parse repeatable ``KEY=VALUE`` filters into a dict; Exit(2) on a malformed entry."""
     if not items:
@@ -133,7 +162,14 @@ def plot(
             "--label", "-l", help="Series label per run, in order (repeat). Default: stem."
         ),
     ] = None,
-    output: Annotated[Path | None, typer.Option("--output", "-o", help="HTML out.")] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Out file; .html is interactive, .png/.svg/.pdf/.jpg/.webp export a static image.",
+        ),
+    ] = None,
     open_browser: Annotated[bool, typer.Option("--open/--no-open")] = False,
 ) -> None:
     """Render an interactive plotly view from one or more pytest-benchmark runs."""
@@ -202,7 +238,7 @@ def plot(
 
     output = output or Path(".benchmarks") / "plots" / f"{chosen}-{metric}.html"
     output.parent.mkdir(parents=True, exist_ok=True)
-    fig.write_html(output)
+    _write_figure(fig, output)
     typer.secho(f"{chosen} ({metric}): {n} ids → {output}", fg=typer.colors.GREEN)
     if open_browser:
         import webbrowser

tests/test_cli.py

@@ -46,6 +46,11 @@ def _bm(name, *, t=1.0, peak=None):
 class _FakeFig:
     def write_html(self, path):
         self.path = path
+        self.kind = "html"
+
+    def write_image(self, path):
+        self.path = path
+        self.kind = "image"
 
 
 # --- compare ---------------------------------------------------------------------
@@ -334,6 +339,61 @@ def test_plot_missing_file_exits_2(tmp_path):
     assert "missing" in _text(result)
 
 
+def _stub_view(plotting_mod, monkeypatch, fig):
+    """Point every plot_* view at a stub returning ``fig``, so -o export is what's exercised."""
+    for name in ("plot_compare", "plot_scatter", "plot_sweep", "plot_scaling"):
+        monkeypatch.setattr(plotting_mod, name, lambda *a, _f=fig, **k: (_f, 1))
+
+
+def test_plot_image_suffix_calls_write_image(tmp_path, monkeypatch):
+    """An image suffix routes through write_image (kaleido) instead of write_html."""
+    import pytest_benchmem.cli as cli
+
+    monkeypatch.setattr(cli.importlib.util, "find_spec", lambda name: object())
+    fig = _FakeFig()
+    _stub_view(plotting, monkeypatch, fig)
+    r = _run(tmp_path, "r.json", [_bm("x")])
+    out = tmp_path / "out.png"
+    result = runner.invoke(app, ["plot", str(r), "-o", str(out)])
+    assert result.exit_code == 0, _text(result)
+    assert fig.kind == "image" and fig.path == out
+
+
+def test_plot_image_suffix_without_kaleido_exits_2(tmp_path, monkeypatch):
+    """A static suffix without kaleido is a clean error naming the extra, not a crash."""
+    import pytest_benchmem.cli as cli
+
+    # plotly present (plot gate passes), kaleido absent (image gate fails).
+    monkeypatch.setattr(
+        cli.importlib.util,
+        "find_spec",
+        lambda name: None if name == "kaleido" else object(),
+    )
+    _stub_view(plotting, monkeypatch, _FakeFig())
+    r = _run(tmp_path, "r.json", [_bm("x")])
+    result = runner.invoke(app, ["plot", str(r), "-o", str(tmp_path / "out.png")])
+    assert result.exit_code == 2
+    assert "kaleido" in _text(result) and "plot-static" in _text(result)
+
+
+def test_plot_unsupported_suffix_exits_2(tmp_path, monkeypatch):
+    """A typo'd suffix is rejected rather than silently written as HTML."""
+    _stub_view(plotting, monkeypatch, _FakeFig())
+    r = _run(tmp_path, "r.json", [_bm("x")])
+    result = runner.invoke(app, ["plot", str(r), "-o", str(tmp_path / "out.pong")])
+    assert result.exit_code == 2
+    assert "unsupported output suffix" in _text(result)
+
+
+def test_plot_html_suffix_calls_write_html(tmp_path, monkeypatch):
+    fig = _FakeFig()
+    _stub_view(plotting, monkeypatch, fig)
+    r = _run(tmp_path, "r.json", [_bm("x")])
+    result = runner.invoke(app, ["plot", str(r), "-o", str(tmp_path / "out.html")])
+    assert result.exit_code == 0, _text(result)
+    assert fig.kind == "html"
+
+
 def test_plot_value_error_exits_1(tmp_path, monkeypatch):
     def boom(*a, **k):
         raise ValueError("no ids in common")