pytest-agent-digest 0.2.0__py3-none-any.whl

pytest_agent_digest/__init__.py

@@ -0,0 +1,23 @@
+"""Top-level package for pytest_agent_digest.
+
+The pytest11 entry point points to this package, so pytest hook functions
+are imported here from ``plugin`` to make them discoverable.
+"""
+
+from pytest_agent_digest.plugin import (
+    AgentDigestPlugin,
+    get_output_modes,
+    get_report_path,
+    pytest_addoption,
+    pytest_configure,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AgentDigestPlugin",
+    "get_output_modes",
+    "get_report_path",
+    "pytest_addoption",
+    "pytest_configure",
+]

pytest_agent_digest/collector.py

@@ -0,0 +1,194 @@
+"""Test result collector for pytest-agent-digest."""
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+import pytest
+
+
+def strip_ansi(text: str) -> str:
+    """
+    Remove ANSI escape sequences from *text*.
+
+    Args:
+        text: The string that may contain ANSI escape sequences.
+
+    Returns:
+        The input string with all ANSI color/style codes removed.
+    """
+    return re.sub(r"\x1b\[[0-9;]*m", "", text)
+
+
+@dataclass
+class TestResult:
+    """Represents a single test outcome captured during a pytest session.
+
+    Attributes:
+        node_id: The pytest node ID (e.g. `tests/test_foo.py::test_bar`).
+        outcome: One of `"passed"`, `"failed"`, `"skipped"`, `"xfailed"`, `"xpassed"`.
+        longrepr: Formatted traceback or reason string, stripped of ANSI codes.
+            `None` when not applicable.
+        duration: Test duration in seconds.
+        skip_reason: Human-readable skip reason for skipped tests; `None` otherwise.
+    """
+
+    node_id: str
+    outcome: str
+    longrepr: str | None
+    duration: float
+    skip_reason: str | None
+
+
+class ReportCollector:
+    """
+    Accumulates the `TestResult` objects while a pytest session runs.
+
+    Wire this into `pytest_configure` (instantiate) and `pytest_runtest_logreport` (call `add`) so the renderer can
+    consume a fully populated collector at the session end.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with an empty result list."""
+        self.results: list[TestResult] = []
+
+    def add(self, report: pytest.TestReport) -> None:
+        """
+        Classify *report* and append a `TestResult` class if it is a call phase.
+
+        ``report.when == "call"`` reports are stored for normal outcomes.
+        ``report.when == "setup"`` reports are stored only when skipped, because
+        ``@pytest.mark.skip`` raises a ``Skipped`` exception during the setup phase
+        and never produces a call-phase report.
+
+        Args:
+            report: The pytest test report to classify and store.
+        """
+        if report.when == "setup" and report.skipped:
+            outcome = "skipped"
+            longrepr = self._extract_longrepr(report)
+            skip_reason = self._extract_skip_reason(report, outcome)
+            self.results.append(
+                TestResult(
+                    node_id=report.nodeid,
+                    outcome=outcome,
+                    longrepr=longrepr,
+                    duration=report.duration,
+                    skip_reason=skip_reason,
+                )
+            )
+            return
+
+        if report.when != "call":
+            return
+
+        outcome = self._classify(report)
+        longrepr = self._extract_longrepr(report)
+        skip_reason = self._extract_skip_reason(report, outcome)
+
+        self.results.append(
+            TestResult(
+                node_id=report.nodeid,
+                outcome=outcome,
+                longrepr=longrepr,
+                duration=report.duration,
+                skip_reason=skip_reason,
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def counts(self) -> dict[str, int]:
+        """
+        Return a dict of `{outcome: count}` with zero-count keys omitted.
+
+        Returns:
+            Mapping from the outcome string to the number of results with that outcome.
+        """
+        return dict(Counter(tr.outcome for tr in self.results))
+
+    @property
+    def has_failures(self) -> bool:
+        """
+        Return `True` if any result is `"failed"` or `"xpassed"`.
+
+        Returns:
+            `True` when there is at least one failure or unexpected pass.
+        """
+        return any(tr.outcome in {"failed", "xpassed"} for tr in self.results)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _classify(report: pytest.TestReport) -> str:
+        """
+        Return the outcome string for *report*.
+
+        Args:
+            report: The test report to classify.
+
+        Returns:
+            One of `"passed"`, `"failed"`, `"skipped"`, `"xfailed"`, `"xpassed"`.
+        """
+        has_xfail = hasattr(report, "wasxfail")
+        if report.passed:
+            return "xpassed" if has_xfail else "passed"
+        if report.skipped:
+            return "xfailed" if has_xfail else "skipped"
+        return "failed"
+
+    @staticmethod
+    def _longrepr_reason(longrepr: object) -> str:
+        """
+        Extract and ANSI-strip a reason string from a longrepr value.
+
+        Skipped reports store ``longrepr`` as a ``(filename, lineno, reason)`` tuple;
+        all other reports store it as a string-like object.
+
+        Args:
+            longrepr: The raw ``report.longrepr`` value (tuple or str-like).
+
+        Returns:
+            A plain-text reason string.
+        """
+        if isinstance(longrepr, tuple):
+            return strip_ansi(str(longrepr[2]))
+        return strip_ansi(str(longrepr))
+
+    @staticmethod
+    def _extract_longrepr(report: pytest.TestReport) -> str | None:
+        """
+        Extract and ANSI-strip the longrepr from *report*.
+
+        Args:
+            report: The test report whose longrepr should be extracted.
+
+        Returns:
+            A plain-text longrepr string, or `None` if absent.
+        """
+        if report.longrepr is None:
+            return None
+        return ReportCollector._longrepr_reason(report.longrepr)
+
+    @staticmethod
+    def _extract_skip_reason(report: pytest.TestReport, outcome: str) -> str | None:
+        """
+        Return the skip reason for skipped tests, else `None`.
+
+        Args:
+            report: The test report to inspect.
+            outcome: The already-classified outcome string.
+
+        Returns:
+            The skip reason string, or `None` for non-skipped outcomes.
+        """
+        if outcome != "skipped":
+            return None
+        if report.longrepr is None:
+            return None
+        return ReportCollector._longrepr_reason(report.longrepr)

pytest_agent_digest/plugin.py

@@ -0,0 +1,153 @@
+"""pytest plugin hooks for pytest-agent-digest."""
+
+from pathlib import Path
+
+import pytest
+
+from pytest_agent_digest.collector import ReportCollector
+from pytest_agent_digest.renderer import render_report
+
+_PLUGIN_NAME = "agent_digest_plugin"
+
+
+class AgentDigestPlugin:
+    """
+    Internal plugin class that holds the per-session state.
+
+    Registered by `pytest_configure` so that `pytest_runtest_logreport` and
+    `pytest_sessionfinish` share the same `~pytest_agent_digest.collector.ReportCollector`
+    without a global.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the plugin with a fresh collector."""
+        self.collector: ReportCollector = ReportCollector()
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        """
+        Forward each test report to the collector.
+
+        Args:
+            report: The test report for the current phase.
+        """
+        self.collector.add(report)
+
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        """
+        Finalize the digest at the end of the test session.
+
+        When ``term`` mode is active, renders the Markdown digest and prints it to stdout.
+        When ``file`` mode is active, writes the Markdown digest to disk and prints a confirmation line.
+        Both modes may be active simultaneously.
+
+        Args:
+            session: The pytest session object.
+            exitstatus: The exit status code for the session.
+        """
+        config = session.config
+        modes = get_output_modes(config)
+        if not modes:
+            return
+
+        report = render_report(self.collector, verbose=config.option.verbose, tb_style=config.option.tbstyle)
+
+        if "term" in modes:
+            print(report, end="")
+
+        if "file" in modes:
+            path = get_report_path(config)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(report, encoding="utf-8")
+            print(f"Agent digest written to {path}")
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """
+    Register pytest-agent-digest command-line options.
+
+    Args:
+        parser: The pytest argument parser.
+    """
+    parser.addoption(
+        "--agent-digest",
+        action="append",
+        choices=["term", "file"],
+        default=None,
+        help=(
+            "Generate Agent-friendly Markdown digest. Use 'term' for stdout, "
+            "'file' for file output. Can be passed twice."
+        ),
+    )
+    parser.addoption(
+        "--agent-digest-file",
+        action="store",
+        default=None,
+        help="Path for the Markdown digest file (default: test-results.md).",
+    )
+    parser.addini(
+        "agent_digest_file",
+        default="test-results.md",
+        help="Default path for the Agent digest file.",
+    )
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_configure(config: pytest.Config) -> None:
+    """
+    Configure the pytest-agent-digest plugin.
+
+    Instantiates the `AgentDigestPlugin` class and registers it so its hooks are active for the session.
+    When ``term`` mode is active, unregisters pytest's built-in terminal reporter so only the Markdown
+    digest appears on stdout.
+
+    Marked ``trylast=True`` so that the built-in terminal reporter is already registered by the time
+    this hook runs, making it safe to unregister.
+
+    Args:
+        config: The pytest configuration object.
+    """
+    plugin = AgentDigestPlugin()
+    config.pluginmanager.register(plugin, _PLUGIN_NAME)
+
+    if "term" in get_output_modes(config):
+        tr = config.pluginmanager.get_plugin("terminalreporter")
+        if tr is not None:
+            config.pluginmanager.unregister(tr)
+
+
+def get_output_modes(config: pytest.Config) -> set[str]:
+    """
+    Return the set of output modes requested via --agent-digest.
+
+    Args:
+        config: The pytest configuration object.
+
+    Returns:
+        A set of mode strings (`"term"`, `"file"`), or an empty set if the flag was not passed.
+    """
+    modes = config.getoption("--agent-digest", default=None)
+    if not modes:
+        return set()
+    return set(modes)
+
+
+def get_report_path(config: pytest.Config) -> Path:
+    """
+    Return the output path for the Markdown digest file.
+
+    Resolution order:
+
+    1. `--agent-digest-file` CLI flag
+    2. `agent_digest_file` ini option
+    3. Hard-coded default `test-results.md`
+
+    Args:
+        config: The pytest configuration object.
+
+    Returns:
+        A `pathlib.Path` pointing to the desired report file location.
+    """
+    cli_value = config.getoption("--agent-digest-file", default=None)
+    if cli_value is not None:
+        return Path(cli_value)
+    return Path(config.getini("agent_digest_file"))

pytest_agent_digest/renderer.py

@@ -0,0 +1,93 @@
+"""Markdown renderer for pytest-agent-digest."""
+
+from pytest_agent_digest.collector import ReportCollector, TestResult
+
+_OUTCOME_ORDER = ["passed", "failed", "skipped", "xfailed", "xpassed"]
+
+_STATUS_LABEL: dict[str, str] = {
+    "failed": "FAILED",
+    "xpassed": "XPASSED",
+}
+
+
+def render_report(collector: ReportCollector, verbose: int, tb_style: str) -> str:
+    """
+    Render a Markdown report from a populated collector.
+
+    Args:
+        collector: The populated ``ReportCollector`` instance.
+        verbose: If ``True``, include a ``## Passes`` section listing each passed test.
+        tb_style: The pytest ``--tb`` style value.  When ``"no"``, traceback
+            code blocks are omitted from failure entries.
+
+    Returns:
+        A Markdown string suitable for Agent consumption.  The document always
+        ends with a newline and contains no ANSI escape sequences.
+    """
+    sections: list[str] = []
+
+    # ------------------------------------------------------------------
+    # Summary line (always present, even when empty)
+    # ------------------------------------------------------------------
+    counts = collector.counts
+    summary_parts = [f"{counts[o]} {o}" for o in _OUTCOME_ORDER if o in counts]
+    sections.append(", ".join(summary_parts))
+
+    # ------------------------------------------------------------------
+    # Failures section (failed + xpassed)
+    # ------------------------------------------------------------------
+    failures = [r for r in collector.results if r.outcome in {"failed", "xpassed"}]
+    if failures:
+        failure_lines: list[str] = ["## Failures"]
+        for result in failures:
+            failure_lines.extend(_failure_entry_lines(result, tb_style))
+        sections.append("\n".join(failure_lines))
+
+    # ------------------------------------------------------------------
+    # Skipped section
+    # ------------------------------------------------------------------
+    skipped = [r for r in collector.results if r.outcome == "skipped"]
+    if skipped:
+        skipped_lines: list[str] = ["## Skipped", ""]
+        for result in skipped:
+            skipped_lines.append(f"- {result.node_id}: {result.skip_reason}")
+        sections.append("\n".join(skipped_lines))
+
+    # ------------------------------------------------------------------
+    # Passes section (verbose only)
+    # ------------------------------------------------------------------
+    if verbose:
+        passed = [r for r in collector.results if r.outcome == "passed"]
+        if passed:
+            passed_lines: list[str] = ["## Passes", ""]
+            for result in passed:
+                passed_lines.append(f"- {result.node_id}")
+            sections.append("\n".join(passed_lines))
+
+    return "\n\n".join(sections) + "\n"
+
+
+def _failure_entry_lines(result: TestResult, tb_style: str) -> list[str]:
+    """
+    Build the lines for a single failure entry.
+
+    Args:
+        result: The ``TestResult`` to render (must be ``failed`` or ``xpassed``).
+        tb_style: The pytest ``--tb`` style; ``"no"`` suppresses the traceback block.
+
+    Returns:
+        A list of strings (without a trailing blank line) representing the entry.
+    """
+    lines = [
+        "",
+        f"### {result.node_id}",
+        "",
+        f"**Status:** {_STATUS_LABEL.get(result.outcome, result.outcome.upper())}",
+        f"**Duration:** {result.duration:.2f}s",
+    ]
+    if tb_style != "no" and result.longrepr:
+        lines.append("")
+        lines.append("```")
+        lines.extend(tb_line.rstrip() for tb_line in result.longrepr.splitlines())
+        lines.append("```")
+    return lines

pytest_agent_digest-0.2.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: pytest-agent-digest
+Version: 0.2.0
+Summary: A Pytest plugin to generate a Markdown report for AI Agents
+Project-URL: Homepage, https://github.com/callowayproject/pytest-agent-digest
+Project-URL: Documentation, https://callowayproject.github.io/pytest-agent-digest
+Project-URL: Repository, https://github.com/callowayproject/pytest-agent-digest
+Project-URL: Changelog, https://github.com/callowayproject/pytest-agent-digest/CHANGELOG.md
+Author-email: Corey Oordt <coreyoordt@gmail.com>
+License: BSD License
+        
+        Copyright (c) 2026, Corey Oordt
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without modification,
+        are permitted provided that the following conditions are met:
+        
+        * Redistributions of source code must retain the above copyright notice, this
+          list of conditions and the following disclaimer.
+        
+        * Redistributions in binary form must reproduce the above copyright notice, this
+          list of conditions and the following disclaimer in the documentation and/or
+          other materials provided with the distribution.
+        
+        * Neither the name of pytest-agent-digest nor the names of its
+          contributors may be used to endorse or promote products derived from this
+          software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+        IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+        INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+        BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+        OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+        OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+        OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: AI,LLM,agent,pytest,report
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: pytest>=7.0
+Description-Content-Type: text/markdown
+
+# pytest-agent-digest
+
+A pytest plugin that generates compact Markdown digests designed for consumption by AI agents and LLMs. Instead of the standard terminal output, `pytest-agent-digest` produces structured Markdown that is typically **≥20% smaller in token count** than raw pytest output — keeping your context window budget under control.
+
+[![PyPI](https://img.shields.io/pypi/v/pytest-agent-digest)](https://pypi.org/project/pytest-agent-digest/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-agent-digest)](https://pypi.org/project/pytest-agent-digest/)
+
+## Quick start
+
+```bash
+# Install
+pip install pytest-agent-digest
+
+# Print Markdown digest to stdout (replaces normal output)
+pytest --agent-digest=term
+
+# Write digest to test-results.md (normal output preserved)
+pytest --agent-digest=file
+
+# Both at once
+pytest --agent-digest=term --agent-digest=file
+```
+
+## Documentation
+
+Full documentation is available at **<https://callowayproject.github.io/pytest-agent-digest>**, including:
+
+- [Quickstart guide](https://callowayproject.github.io/pytest-agent-digest/quickstart/)
+- [Options reference](https://callowayproject.github.io/pytest-agent-digest/reference/options/)

pytest_agent_digest-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pytest_agent_digest/__init__.py,sha256=Vw4ToGGT_PLIznVxIq1G0mnQUjVPQPcSqQno5FZ67Us,498
+pytest_agent_digest/collector.py,sha256=zMvZxV3kcL0ZO6BZLUiWqk5EU2phmAuGJKcG4-yvyTE,6203
+pytest_agent_digest/plugin.py,sha256=HwhCSHdNNiWY-EfLglPokpfAFJNMolI3golyKgp_fOg,4729
+pytest_agent_digest/renderer.py,sha256=x139dj-Ro-o36mOB7NMUoopkT5rsy2lXstFE7VGByJY,3629
+pytest_agent_digest-0.2.0.dist-info/METADATA,sha256=qlHNobAm-MMe_QQVrIwAUrepnb9s5O0va2Wwu9_WkUY,4216
+pytest_agent_digest-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pytest_agent_digest-0.2.0.dist-info/entry_points.txt,sha256=CrI63EMB63yVm0o2dXTSaPtWQUpeFaNuqnxAJgOb_Qw,46
+pytest_agent_digest-0.2.0.dist-info/licenses/LICENSE,sha256=TVX9QAgAPr4aFy9DSBKeZMmySsYXDsFRMTOXOh3q7Xc,1501
+pytest_agent_digest-0.2.0.dist-info/RECORD,,

pytest_agent_digest-0.2.0.dist-info/WHEEL

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

pytest_agent_digest-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+agent_digest = pytest_agent_digest

pytest_agent_digest-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD License
+
+Copyright (c) 2026, Corey Oordt
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of pytest-agent-digest nor the names of its
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+OF THE POSSIBILITY OF SUCH DAMAGE.