pytest-devtools 1.2.0__tar.gz → 1.3.0__tar.gz

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: pytest-devtools
-Version: 1.2.0
-Summary: Pytest plugin providing debug fixtures, ANSI-stripped capsys, whitespace-visible assertions, and terminal column management.
+Version: 1.3.0
+Summary: Pytest plugin providing debug fixtures, ANSI-stripped capsys, whitespace-visible assertions, terminal column management, and click/typer CLI runner fixtures.
 Author: Nathaniel Landau
 Author-email: Nathaniel Landau <github@natelandau.com>
 License: MIT License
@@ -23,7 +23,11 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
 Requires-Dist: pytest>=7
 Requires-Dist: rich>=15.0.0
+Requires-Dist: click>=8.2 ; extra == 'click'
+Requires-Dist: typer>=0.25 ; extra == 'typer'
 Requires-Python: >=3.10
+Provides-Extra: click
+Provides-Extra: typer
 Description-Content-Type: text/markdown
 
 # pytest-devtools
@@ -39,6 +43,7 @@ A pytest plugin that smooths over a few common annoyances when writing and debug
 - **Stripped `capsys` output**: removes ANSI escape codes (and optionally the `tmp_path` prefix) from captured stdout/stderr so assertions stay readable.
 - **Visible whitespace in diffs**: replaces tabs, trailing spaces, carriage returns, and newlines with Unicode symbols when an assertion fails.
 - **Terminal column width control**: sets `COLUMNS` for every test so libraries that auto-wrap (Rich, Click, etc.) produce stable output.
+- **CLI runner output post-processing**: `cli_runner` and `typer_runner` fixtures strip ANSI codes, `tmp_path` prefixes, and trailing whitespace from `click`/`typer` `CliRunner` results, the same way `capsys` does for regular captured output.
 
 ## Installation
 
@@ -236,6 +241,116 @@ strip_ansi = true                # default: true
 capsys_strip_tmp_path = false    # default: false
 ```
 
+## CLI Runner Output
+
+`click.testing.CliRunner` and `typer.testing.CliRunner` replace `sys.stdout` and `sys.stderr` with their own in-memory buffers while a command runs. Nothing a CLI writes inside `invoke()` reaches pytest's capture machinery, so the `capsys` override above cannot see it and `result.output` arrives unprocessed.
+
+The `cli_runner` and `typer_runner` fixtures are drop-in replacements that post-process the runner's own `Result`.
+
+```bash
+# uv
+uv add --dev "pytest-devtools[click]"
+uv add --dev "pytest-devtools[typer]"
+
+# pip
+pip install "pytest-devtools[click]"
+pip install "pytest-devtools[typer]"
+```
+
+Neither extra is strictly required. A project testing a CLI already depends on click or typer directly, and the fixtures activate whenever the library is importable. The extras exist to record the supported versions:
+
+| Fixture        | Requires      |
+| -------------- | ------------- |
+| `cli_runner`   | `click>=8.2`  |
+| `typer_runner` | `typer>=0.25` |
+
+Those floors are where the runner exposes stdout and stderr as separate strings. Below them, `result.stderr` raises `ValueError: stderr not separately captured` and `result.output` silently returns the two streams mixed together. Both fixtures check the installed version at setup and fail with an explicit message rather than letting that surface later.
+
+### click
+
+```python
+from myapp.cli import main
+
+
+def test_greeting(cli_runner):
+    result = cli_runner.invoke(main, ["--name", "world"])
+
+    assert result.exit_code == 0
+    assert result.output == "Hello world\n"
+```
+
+### typer
+
+```python
+from myapp.cli import app
+
+
+def test_greeting(typer_runner):
+    result = typer_runner.invoke(app, ["--name", "world"])
+
+    assert result.exit_code == 0
+    assert result.output == "Hello world\n"
+```
+
+Both fixtures are real subclasses of their framework's runner, so `isolated_filesystem()` and every other runner method work as usual. Only `invoke()` changes.
+
+When a transform is active, `invoke()` returns a transparent proxy over the framework's `Result`: `isinstance(result, click.testing.Result)` and a `-> Result` annotation both hold, but `type(result)` reports the proxy, not the framework's class.
+
+### ANSI Escape Stripping
+
+On by default, and controlled by the same settings as `capsys`: `--no-strip-ansi`, `strip_ansi = false`, and `@pytest.mark.keep_ansi` for a single test.
+
+This matters most for CLIs that print through Rich. Click strips its own `echo()` styling inside the runner already, but a `Console(force_terminal=True)` writes escape codes straight past that.
+
+### `tmp_path` Stripping
+
+Off by default. Enable with `--cli-runner-strip-tmp-path` or `cli_runner_strip_tmp_path = true` to collapse paths under `tmp_path` to their relative portion:
+
+```python
+def test_writes_file(cli_runner, tmp_path):
+    result = cli_runner.invoke(main, ["--out", str(tmp_path / "sub" / "report.txt")])
+
+    assert "wrote sub/report.txt" in result.output
+```
+
+### Trailing Whitespace Stripping
+
+Off by default. Enable with `--cli-runner-strip-trailing-whitespace` or `cli_runner_strip_trailing_whitespace = true`.
+
+Typer renders help through a Rich panel, which pads every line out to the full terminal width. At a wide `--columns` setting that means lines of mostly blanks, which makes asserting on `--help` output impractical:
+
+```python
+def test_help(typer_runner):
+    result = typer_runner.invoke(app, ["--help"])
+
+    assert "Usage" in result.output
+    assert not any(line.endswith(" ") for line in result.output.split("\n"))
+```
+
+### Terminal Width
+
+Click's help formatter caps at 80 columns and ignores the `COLUMNS` environment variable, so the `--columns` setting alone never reached help text. When the column width feature is enabled, both fixtures pass it to `invoke()` as the `terminal_width` context setting. An explicit `terminal_width` argument always wins:
+
+```python
+def test_narrow_help(cli_runner):
+    result = cli_runner.invoke(main, ["--help"], terminal_width=40)
+```
+
+### Runners You Construct Yourself
+
+If runners come from your own conftest fixture and you would rather not switch to `cli_runner`, opt into patching instead. With `cli_runner_patch_result = true` or `--cli-runner-patch-result`, the same post-processing applies to every `Result` for the duration of each test, whoever built the runner:
+
+```toml
+[tool.pytest.ini_options]
+cli_runner_patch_result = true
+```
+
+Three caveats:
+
+- Terminal width injection does not reach externally built runners. Only the `cli_runner` and `typer_runner` fixtures' own `invoke()` passes `terminal_width` through; a runner you construct yourself keeps whatever width it would normally use.
+- Enabling patch mode changes what `cli_runner.invoke()` and `typer_runner.invoke()` return too: once the `Result` classes are patched, the fixtures' own `invoke()` skips its wrapping and returns the framework's `Result` directly instead of the proxy.
+- The patch is undone by `monkeypatch`, whose finalizer runs after every function-scoped fixture's teardown but before any session- or module-scoped one. A session- or module-scoped fixture that reads a `Result` during its own teardown therefore sees the raw, unprocessed output.
+
 ## Visible Whitespace in Assertions
 
 When two strings differ only in whitespace, pytest's default diff is hard to read. This plugin replaces invisible characters with visible Unicode symbols in the assertion failure message.
@@ -317,6 +432,10 @@ Every feature is configurable through CLI flags and `pyproject.toml` INI options
 | `tmp_path` in `capsys` | Off                   | `--capsys-strip-tmp-path` or `capsys_strip_tmp_path = true`       |
 | Visible whitespace     | On                    | `--no-show-whitespace` or `show_whitespace = false`               |
 | Column width           | Off                   | `--columns=N` or `set_columns = true`                             |
+| CLI runner ANSI        | On                    | Shares `--no-strip-ansi` / `strip_ansi = false`                    |
+| `tmp_path` in runner   | Off                   | `--cli-runner-strip-tmp-path` or `cli_runner_strip_tmp_path = true` |
+| Runner trailing space  | Off                   | `--cli-runner-strip-trailing-whitespace` or `cli_runner_strip_trailing_whitespace = true` |
+| Patch external runners | Off                   | `--cli-runner-patch-result` or `cli_runner_patch_result = true`     |
 
 ## AI Policy
 

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/README.md

@@ -11,6 +11,7 @@ A pytest plugin that smooths over a few common annoyances when writing and debug
 - **Stripped `capsys` output**: removes ANSI escape codes (and optionally the `tmp_path` prefix) from captured stdout/stderr so assertions stay readable.
 - **Visible whitespace in diffs**: replaces tabs, trailing spaces, carriage returns, and newlines with Unicode symbols when an assertion fails.
 - **Terminal column width control**: sets `COLUMNS` for every test so libraries that auto-wrap (Rich, Click, etc.) produce stable output.
+- **CLI runner output post-processing**: `cli_runner` and `typer_runner` fixtures strip ANSI codes, `tmp_path` prefixes, and trailing whitespace from `click`/`typer` `CliRunner` results, the same way `capsys` does for regular captured output.
 
 ## Installation
 
@@ -208,6 +209,116 @@ strip_ansi = true                # default: true
 capsys_strip_tmp_path = false    # default: false
 ```
 
+## CLI Runner Output
+
+`click.testing.CliRunner` and `typer.testing.CliRunner` replace `sys.stdout` and `sys.stderr` with their own in-memory buffers while a command runs. Nothing a CLI writes inside `invoke()` reaches pytest's capture machinery, so the `capsys` override above cannot see it and `result.output` arrives unprocessed.
+
+The `cli_runner` and `typer_runner` fixtures are drop-in replacements that post-process the runner's own `Result`.
+
+```bash
+# uv
+uv add --dev "pytest-devtools[click]"
+uv add --dev "pytest-devtools[typer]"
+
+# pip
+pip install "pytest-devtools[click]"
+pip install "pytest-devtools[typer]"
+```
+
+Neither extra is strictly required. A project testing a CLI already depends on click or typer directly, and the fixtures activate whenever the library is importable. The extras exist to record the supported versions:
+
+| Fixture        | Requires      |
+| -------------- | ------------- |
+| `cli_runner`   | `click>=8.2`  |
+| `typer_runner` | `typer>=0.25` |
+
+Those floors are where the runner exposes stdout and stderr as separate strings. Below them, `result.stderr` raises `ValueError: stderr not separately captured` and `result.output` silently returns the two streams mixed together. Both fixtures check the installed version at setup and fail with an explicit message rather than letting that surface later.
+
+### click
+
+```python
+from myapp.cli import main
+
+
+def test_greeting(cli_runner):
+    result = cli_runner.invoke(main, ["--name", "world"])
+
+    assert result.exit_code == 0
+    assert result.output == "Hello world\n"
+```
+
+### typer
+
+```python
+from myapp.cli import app
+
+
+def test_greeting(typer_runner):
+    result = typer_runner.invoke(app, ["--name", "world"])
+
+    assert result.exit_code == 0
+    assert result.output == "Hello world\n"
+```
+
+Both fixtures are real subclasses of their framework's runner, so `isolated_filesystem()` and every other runner method work as usual. Only `invoke()` changes.
+
+When a transform is active, `invoke()` returns a transparent proxy over the framework's `Result`: `isinstance(result, click.testing.Result)` and a `-> Result` annotation both hold, but `type(result)` reports the proxy, not the framework's class.
+
+### ANSI Escape Stripping
+
+On by default, and controlled by the same settings as `capsys`: `--no-strip-ansi`, `strip_ansi = false`, and `@pytest.mark.keep_ansi` for a single test.
+
+This matters most for CLIs that print through Rich. Click strips its own `echo()` styling inside the runner already, but a `Console(force_terminal=True)` writes escape codes straight past that.
+
+### `tmp_path` Stripping
+
+Off by default. Enable with `--cli-runner-strip-tmp-path` or `cli_runner_strip_tmp_path = true` to collapse paths under `tmp_path` to their relative portion:
+
+```python
+def test_writes_file(cli_runner, tmp_path):
+    result = cli_runner.invoke(main, ["--out", str(tmp_path / "sub" / "report.txt")])
+
+    assert "wrote sub/report.txt" in result.output
+```
+
+### Trailing Whitespace Stripping
+
+Off by default. Enable with `--cli-runner-strip-trailing-whitespace` or `cli_runner_strip_trailing_whitespace = true`.
+
+Typer renders help through a Rich panel, which pads every line out to the full terminal width. At a wide `--columns` setting that means lines of mostly blanks, which makes asserting on `--help` output impractical:
+
+```python
+def test_help(typer_runner):
+    result = typer_runner.invoke(app, ["--help"])
+
+    assert "Usage" in result.output
+    assert not any(line.endswith(" ") for line in result.output.split("\n"))
+```
+
+### Terminal Width
+
+Click's help formatter caps at 80 columns and ignores the `COLUMNS` environment variable, so the `--columns` setting alone never reached help text. When the column width feature is enabled, both fixtures pass it to `invoke()` as the `terminal_width` context setting. An explicit `terminal_width` argument always wins:
+
+```python
+def test_narrow_help(cli_runner):
+    result = cli_runner.invoke(main, ["--help"], terminal_width=40)
+```
+
+### Runners You Construct Yourself
+
+If runners come from your own conftest fixture and you would rather not switch to `cli_runner`, opt into patching instead. With `cli_runner_patch_result = true` or `--cli-runner-patch-result`, the same post-processing applies to every `Result` for the duration of each test, whoever built the runner:
+
+```toml
+[tool.pytest.ini_options]
+cli_runner_patch_result = true
+```
+
+Three caveats:
+
+- Terminal width injection does not reach externally built runners. Only the `cli_runner` and `typer_runner` fixtures' own `invoke()` passes `terminal_width` through; a runner you construct yourself keeps whatever width it would normally use.
+- Enabling patch mode changes what `cli_runner.invoke()` and `typer_runner.invoke()` return too: once the `Result` classes are patched, the fixtures' own `invoke()` skips its wrapping and returns the framework's `Result` directly instead of the proxy.
+- The patch is undone by `monkeypatch`, whose finalizer runs after every function-scoped fixture's teardown but before any session- or module-scoped one. A session- or module-scoped fixture that reads a `Result` during its own teardown therefore sees the raw, unprocessed output.
+
 ## Visible Whitespace in Assertions
 
 When two strings differ only in whitespace, pytest's default diff is hard to read. This plugin replaces invisible characters with visible Unicode symbols in the assertion failure message.
@@ -289,6 +400,10 @@ Every feature is configurable through CLI flags and `pyproject.toml` INI options
 | `tmp_path` in `capsys` | Off                   | `--capsys-strip-tmp-path` or `capsys_strip_tmp_path = true`       |
 | Visible whitespace     | On                    | `--no-show-whitespace` or `show_whitespace = false`               |
 | Column width           | Off                   | `--columns=N` or `set_columns = true`                             |
+| CLI runner ANSI        | On                    | Shares `--no-strip-ansi` / `strip_ansi = false`                    |
+| `tmp_path` in runner   | Off                   | `--cli-runner-strip-tmp-path` or `cli_runner_strip_tmp_path = true` |
+| Runner trailing space  | Off                   | `--cli-runner-strip-trailing-whitespace` or `cli_runner_strip_trailing_whitespace = true` |
+| Patch external runners | Off                   | `--cli-runner-patch-result` or `cli_runner_patch_result = true`     |
 
 ## AI Policy
 

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/pyproject.toml

@@ -11,16 +11,20 @@
         "Topic :: Software Development :: Testing",
     ]
     dependencies = ["pytest>=7", "rich>=15.0.0"]
-    description = "Pytest plugin providing debug fixtures, ANSI-stripped capsys, whitespace-visible assertions, and terminal column management."
+    description = "Pytest plugin providing debug fixtures, ANSI-stripped capsys, whitespace-visible assertions, terminal column management, and click/typer CLI runner fixtures."
     license = { file = "LICENSE" }
     name = "pytest-devtools"
     readme = "README.md"
     requires-python = ">=3.10"
-    version = "1.2.0"
+    version = "1.3.0"
 
     [project.entry-points.pytest11]
         pytest-devtools = "devtools.plugin"
 
+[project.optional-dependencies]
+    click = ["click>=8.2"]
+    typer = ["typer>=0.25"]
+
 [build-system]
     build-backend = "uv_build"
     requires      = ["uv_build>=0.11.8,<0.12.0"]
@@ -30,19 +34,21 @@
 
 [dependency-groups]
     dev = [
-        "commitizen>=4.15.0",
-        "coverage>=7.13.5",
+        "click>=8.2",
+        "commitizen>=4.16.3",
+        "coverage>=7.14.1",
         "duty>=1.9.0",
-        "prek>=0.3.11",
+        "prek>=0.4.4",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.1.0",
         "pytest-mock>=3.15.1",
         "pytest-repeat>=0.9.4",
-        "ruff>=0.15.12",
-        "ty>=0.0.34",
-        "typos>=1.46.0",
+        "ruff>=0.15.16",
+        "ty>=0.0.44",
+        "typer>=0.25",
+        "typos>=1.47.2",
         "yamllint>=1.38.0",
-]
+    ]
 
 [tool.commitizen]
     bump_message               = "bump(release): v$current_version → v$new_version"

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/src/devtools/_options.py

@@ -36,3 +36,24 @@ def resolve_option(
         return cli_value
 
     return request.config.getini(name)
+
+
+def should_strip_ansi(request: pytest.FixtureRequest) -> bool:
+    """Determine whether ANSI stripping applies to this test.
+
+    Shared by the capsys override and the CLI runner fixtures so a single set of
+    controls governs both.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        True if ANSI codes should be stripped, False otherwise.
+    """
+    if request.config.getoption("no_strip_ansi", default=False):
+        return False
+
+    if not request.config.getini("strip_ansi"):
+        return False
+
+    return not request.node.get_closest_marker("keep_ansi")

pytest_devtools-1.3.0/src/devtools/_text.py

@@ -0,0 +1,66 @@
+"""Pure text transforms shared by the capsys override and the CLI runner fixtures.
+
+Keep this module free of pytest imports so the transforms stay directly testable
+and reusable from any context.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from a string.
+
+    Args:
+        text: The string potentially containing ANSI escape sequences.
+
+    Returns:
+        The string with all ANSI SGR sequences removed.
+    """
+    return ANSI_PATTERN.sub("", text)
+
+
+def strip_tmp_path(text: str, tmp_path: Path) -> str:
+    r"""Remove tmp_path prefix occurrences from a string.
+
+    Strip the prefix together with its trailing separator, then any bare
+    remainder, so that paths nested under ``tmp_path`` collapse to their
+    relative portion. Both separators are tried because a Windows
+    ``str(tmp_path)`` uses ``\`` while the bare prefix alone would leave a
+    leading separator behind.
+
+    Args:
+        text: The captured output string.
+        tmp_path: The pytest ``tmp_path`` fixture value to strip.
+
+    Returns:
+        The string with tmp_path prefixes removed.
+    """
+    tmp_str = str(tmp_path)
+    for separator in ("/", "\\"):
+        text = text.replace(f"{tmp_str}{separator}", "")
+    return text.replace(tmp_str, "")
+
+
+def strip_trailing_whitespace(text: str) -> str:
+    r"""Remove trailing whitespace from every line of a string.
+
+    Rich renders panels and tables by padding every line out to the full
+    terminal width, which makes exact-match assertions against CLI help output
+    impractical. Splitting on ``"\n"`` rather than using ``splitlines()``
+    preserves the presence or absence of a trailing newline.
+
+    Args:
+        text: The string to right-trim line by line.
+
+    Returns:
+        The string with trailing whitespace removed from each line.
+    """
+    return "\n".join(line.rstrip() for line in text.split("\n"))

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/src/devtools/capsys_strip.py

@@ -8,51 +8,20 @@ output simpler and more reliable.
 from __future__ import annotations
 
 import contextlib
-import re
 from typing import TYPE_CHECKING, Any
 
 import pytest
 from _pytest.capture import CaptureFixture, CaptureResult
 
-from devtools._options import resolve_option
+from devtools._options import resolve_option, should_strip_ansi
+from devtools._text import strip_ansi as strip_ansi  # noqa: PLC0414
+from devtools._text import strip_tmp_path as strip_tmp_path  # noqa: PLC0414
 
 if TYPE_CHECKING:
     from pathlib import Path
 
     from _pytest.config import Config
 
-ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
-
-
-def strip_ansi(text: str) -> str:
-    """Remove ANSI escape sequences from a string.
-
-    Args:
-        text: The string potentially containing ANSI escape sequences.
-
-    Returns:
-        The string with all ANSI SGR sequences removed.
-    """
-    return ANSI_PATTERN.sub("", text)
-
-
-def strip_tmp_path(text: str, tmp_path: Path) -> str:
-    """Remove tmp_path prefix occurrences from a string.
-
-    Strip both ``str(tmp_path) + "/"`` and bare ``str(tmp_path)`` so that paths
-    nested under ``tmp_path`` collapse to their relative portion (matching the
-    behavior of the ``debug`` fixture's tmp_path stripping).
-
-    Args:
-        text: The captured output string.
-        tmp_path: The pytest ``tmp_path`` fixture value to strip.
-
-    Returns:
-        The string with tmp_path prefixes removed.
-    """
-    tmp_str = str(tmp_path)
-    return text.replace(f"{tmp_str}/", "").replace(tmp_str, "")
-
 
 def add_options(parser: pytest.Parser) -> None:
     """Register CLI options for ANSI stripping.
@@ -102,28 +71,10 @@ def configure(config: Config) -> None:
     """
     config.addinivalue_line(
         "markers",
-        "keep_ansi: disable ANSI stripping from capsys for this test",
+        "keep_ansi: disable ANSI stripping for this test",
     )
 
 
-def _should_strip_ansi(request: pytest.FixtureRequest) -> bool:
-    """Determine whether ANSI stripping should be applied for this test.
-
-    Args:
-        request: The pytest fixture request object.
-
-    Returns:
-        True if ANSI codes should be stripped, False otherwise.
-    """
-    if request.config.getoption("no_strip_ansi", default=False):
-        return False
-
-    if not request.config.getini("strip_ansi"):
-        return False
-
-    return not request.node.get_closest_marker("keep_ansi")
-
-
 class StrippedCaptureFixture:
     """Wrapper around CaptureFixture that strips noise from readouterr() results.
 
@@ -187,7 +138,7 @@ def capsys(
     Returns:
         Either the original capsys or a wrapped version that post-processes output.
     """
-    ansi = _should_strip_ansi(request)
+    ansi = should_strip_ansi(request)
     tmp_path = bool(resolve_option(request, "capsys_strip_tmp_path"))
 
     if not ansi and not tmp_path:

pytest_devtools-1.3.0/src/devtools/cli_runners.py

@@ -0,0 +1,538 @@
+"""CliRunner fixtures for click and typer with output post-processing.
+
+``CliRunner.invoke()`` replaces ``sys.stdout`` and ``sys.stderr`` with its own
+in-memory buffers, so output produced inside it never reaches pytest's capture
+machinery and the ``capsys`` override cannot see it. These fixtures apply the
+same post-processing to the runner's own ``Result`` instead.
+
+Neither click nor typer is imported at module scope; both are optional extras.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from devtools._options import resolve_option, should_strip_ansi
+from devtools._text import strip_ansi, strip_tmp_path, strip_trailing_whitespace
+from devtools.columns import get_columns_value
+from devtools.debug_fixture import phase_report_key
+
+MIN_CLICK_VERSION = "8.2"
+MIN_TYPER_VERSION = "0.25"
+
+# Remembers a tmp_path materialized on demand, which never lands in item.funcargs.
+_tmp_path_key: pytest.StashKey[Path] = pytest.StashKey()
+
+
+def _has_click() -> bool:
+    """Report whether click is importable.
+
+    Exists as a named seam so tests can simulate the library's absence without
+    uninstalling it.
+    """
+    return importlib.util.find_spec("click") is not None
+
+
+def _has_typer() -> bool:
+    """Report whether typer is importable.
+
+    Exists as a named seam so tests can simulate the library's absence without
+    uninstalling it.
+    """
+    return importlib.util.find_spec("typer") is not None
+
+
+def _installed_version(dist: str) -> str:
+    """Return the installed version string for a distribution.
+
+    Exists as a named seam so tests can simulate an outdated install without
+    downgrading anything.
+
+    Args:
+        dist: The distribution name to look up.
+
+    Returns:
+        The installed version string.
+    """
+    from importlib.metadata import version  # noqa: PLC0415
+
+    return version(dist)
+
+
+def _check_min_version(dist: str, minimum: str) -> None:
+    """Fail the test if an installed framework predates the supported floor.
+
+    The optional extras cannot enforce this: the fixtures activate on a lazy
+    import probe, so a project that already depends on click or typer gets them
+    at whatever version it happens to pin. Below the floor click's Result mixes
+    stderr into stdout and raises on ``.stderr``, which surfaces far from the
+    real cause.
+
+    Args:
+        dist: The distribution name to check.
+        minimum: The minimum supported version.
+    """
+    from packaging.version import Version  # noqa: PLC0415
+
+    installed = _installed_version(dist)
+    if Version(installed) < Version(minimum):
+        pytest.fail(
+            f"pytest-devtools CLI runner fixtures require {dist}>={minimum}, "
+            f"but {dist} {installed} is installed.",
+            pytrace=False,
+        )
+
+
+def add_options(parser: pytest.Parser) -> None:
+    """Register CLI options for CLI runner output processing.
+
+    Args:
+        parser: The pytest option parser to add options to.
+    """
+    group = parser.getgroup("devtools-cli-runner", "CLI runner output processing")
+    group.addoption(
+        "--cli-runner-strip-tmp-path",
+        action="store_true",
+        default=None,
+        dest="cli_runner_strip_tmp_path",
+        help="Strip tmp_path prefix from CLI runner output (default: false)",
+    )
+    group.addoption(
+        "--no-cli-runner-strip-tmp-path",
+        action="store_false",
+        dest="cli_runner_strip_tmp_path",
+        help="Don't strip tmp_path prefix from CLI runner output",
+    )
+    group.addoption(
+        "--cli-runner-strip-trailing-whitespace",
+        action="store_true",
+        default=None,
+        dest="cli_runner_strip_trailing_whitespace",
+        help="Right-trim every line of CLI runner output (default: false)",
+    )
+    group.addoption(
+        "--no-cli-runner-strip-trailing-whitespace",
+        action="store_false",
+        dest="cli_runner_strip_trailing_whitespace",
+        help="Don't right-trim lines of CLI runner output",
+    )
+    group.addoption(
+        "--cli-runner-patch-result",
+        action="store_true",
+        default=None,
+        dest="cli_runner_patch_result",
+        help="Post-process Result output for runners the plugin did not create",
+    )
+    group.addoption(
+        "--no-cli-runner-patch-result",
+        action="store_false",
+        dest="cli_runner_patch_result",
+        help="Don't patch Result for externally created runners",
+    )
+    parser.addini(
+        "cli_runner_strip_tmp_path",
+        type="bool",
+        default=False,
+        help="Strip tmp_path prefix from CLI runner output (default: false)",
+    )
+    parser.addini(
+        "cli_runner_strip_trailing_whitespace",
+        type="bool",
+        default=False,
+        help="Right-trim every line of CLI runner output (default: false)",
+    )
+    parser.addini(
+        "cli_runner_patch_result",
+        type="bool",
+        default=False,
+        help="Post-process Result output for externally created runners (default: false)",
+    )
+
+
+@dataclass(frozen=True)
+class _Transforms:
+    """Resolved set of post-processing steps to apply to runner output."""
+
+    ansi: bool
+    tmp_path: Path | None
+    trailing_whitespace: bool
+
+    @property
+    def active(self) -> bool:
+        """Report whether any transform would change the output."""
+        return self.ansi or self.tmp_path is not None or self.trailing_whitespace
+
+    def apply(self, text: str) -> str:
+        """Apply every enabled transform to a single output string.
+
+        Strip ANSI first so tmp_path matching never has to contend with escape
+        codes embedded in a path, and right-trim last so it also removes
+        whitespace exposed by the earlier steps.
+
+        Every transform is idempotent: applying it twice yields the same
+        result as applying it once. That invariant is what lets patch mode
+        and the fixtures' own wrapping coexist safely under any interleaving
+        of runners and tests; a future non-idempotent transform would break
+        that guarantee.
+
+        Args:
+            text: The raw output string from the runner Result.
+
+        Returns:
+            The post-processed string.
+        """
+        if self.ansi:
+            text = strip_ansi(text)
+        if self.tmp_path is not None:
+            text = strip_tmp_path(text, self.tmp_path)
+        if self.trailing_whitespace:
+            text = strip_trailing_whitespace(text)
+        return text
+
+
+def _in_teardown(request: pytest.FixtureRequest) -> bool:
+    """Report whether the current test item is in its teardown phase.
+
+    ``request.getfixturevalue()`` for a fixture nothing requested during setup
+    is only legal while the call phase is still running: pytest's internal
+    setup/teardown stack drops the item before running its finalizers, so
+    resolving a fixture for the first time from within another fixture's
+    teardown code raises an assertion deep in pytest's runner. The call
+    phase's report lands in ``item.stash`` only once that phase finishes, and
+    a failed setup skips the call phase entirely and goes straight to
+    teardown, so either signal reliably means teardown is underway.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        True if the item is past setup and call, running teardown.
+    """
+    reports = request.node.stash.get(phase_report_key, {})
+    if "call" in reports:
+        return True
+    setup = reports.get("setup")
+    return setup is not None and not setup.passed
+
+
+def _resolve_transforms(request: pytest.FixtureRequest) -> _Transforms:
+    """Resolve which transforms apply to the current test.
+
+    Prefers the already-resolved ``tmp_path`` value from ``item.funcargs``
+    when the test's fixture closure requested it. That dict is filled once
+    during setup and never cleared, so it holds the correct value through the
+    whole test regardless of where ``tmp_path`` sits in the test's own
+    argument order, and regardless of whether tmp_path's own finalizer has
+    already run.
+
+    Falls back to ``request.getfixturevalue()`` only during the call phase,
+    for a test whose fixture closure never asked for ``tmp_path`` at all;
+    that materializes it on demand so a Result read directly in the test body
+    still gets stripped. ``getfixturevalue()`` does not record into
+    ``funcargs``, so the value is stashed on the item: without that, the same
+    Result would strip in the test body and come back unstripped from a
+    teardown read, where the fallback is illegal and cannot run again.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        The resolved transform set.
+    """
+    tmp_path: Path | None = None
+    if resolve_option(request, "cli_runner_strip_tmp_path"):
+        funcargs = request.node.funcargs
+        stash = request.node.stash
+        if "tmp_path" in funcargs:
+            tmp_path = funcargs["tmp_path"]
+        elif (stashed := stash.get(_tmp_path_key, None)) is not None:
+            tmp_path = stashed
+        elif not _in_teardown(request):
+            with contextlib.suppress(pytest.FixtureLookupError):
+                tmp_path = request.getfixturevalue("tmp_path")
+                stash[_tmp_path_key] = tmp_path
+
+    return _Transforms(
+        ansi=should_strip_ansi(request),
+        tmp_path=tmp_path,
+        trailing_whitespace=bool(resolve_option(request, "cli_runner_strip_trailing_whitespace")),
+    )
+
+
+def _transforms_configured(request: pytest.FixtureRequest) -> bool:
+    """Report whether any transform is enabled, without resolving tmp_path.
+
+    Reads the tmp_path option flag directly rather than resolving the
+    tmp_path fixture, so this check is safe to call from an autouse fixture
+    before deciding whether to install the patch at all.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        True if any transform would apply to this test.
+    """
+    return (
+        should_strip_ansi(request)
+        or bool(resolve_option(request, "cli_runner_strip_tmp_path"))
+        or bool(resolve_option(request, "cli_runner_strip_trailing_whitespace"))
+    )
+
+
+def _patch_active(request: pytest.FixtureRequest) -> bool:
+    """Report whether global Result patching is enabled for this test.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        True if the Result classes should be patched.
+    """
+    return bool(resolve_option(request, "cli_runner_patch_result"))
+
+
+class StrippedResult:
+    """Wrapper around a runner Result that post-processes its output strings.
+
+    ``Result.output``, ``.stdout`` and ``.stderr`` are read-only properties and
+    cannot be reassigned per instance, so wrap the Result and forward everything
+    else through ``__getattr__``.
+    """
+
+    def __init__(self, original: Any, transforms: _Transforms) -> None:
+        self._original = original
+        self._transforms = transforms
+
+    @property
+    def __class__(self) -> type:
+        """Report the wrapped Result's class so isinstance() checks pass.
+
+        CPython's isinstance() consults __class__ before falling back to the
+        real type, so a user's isinstance(result, click.testing.Result) or
+        -> Result annotation holds regardless of which transforms are active.
+        type(result) still reports StrippedResult, since type() reads the
+        real object header rather than this property.
+        """
+        return type(self._original)
+
+    @property
+    def output(self) -> str:
+        """Return the interleaved stdout and stderr, post-processed."""
+        return self._transforms.apply(self._original.output)
+
+    @property
+    def stdout(self) -> str:
+        """Return the standard output, post-processed."""
+        return self._transforms.apply(self._original.stdout)
+
+    @property
+    def stderr(self) -> str:
+        """Return the standard error, post-processed."""
+        return self._transforms.apply(self._original.stderr)
+
+    def __repr__(self) -> str:
+        """Delegate to the wrapped Result's repr."""
+        return repr(self._original)
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the wrapped Result."""
+        return getattr(self._original, name)
+
+
+class _ResultPostProcessMixin:
+    """Supply an ``invoke()`` that post-processes the returned Result.
+
+    Mixed in ahead of the framework's own ``CliRunner`` so ``super().invoke()``
+    resolves to the real implementation.
+    """
+
+    def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the CLI and post-process the resulting output.
+
+        Args:
+            *args: Positional arguments forwarded to the framework's invoke().
+            **kwargs: Keyword arguments forwarded to the framework's invoke().
+
+        Returns:
+            A StrippedResult when any transform is enabled, else the original
+            Result.
+        """
+        request: pytest.FixtureRequest | None = getattr(self, "_devtools_request", None)
+
+        if request is None:
+            return super().invoke(*args, **kwargs)  # ty: ignore[unresolved-attribute]
+
+        # click's help formatter caps at 80 columns and ignores COLUMNS, so the
+        # width has to travel in as a Context setting.
+        width = get_columns_value(request.config)
+        if width is not None:
+            kwargs.setdefault("terminal_width", width)
+
+        result = super().invoke(*args, **kwargs)  # ty: ignore[unresolved-attribute]
+
+        if _patch_active(request):
+            return result
+
+        transforms = _resolve_transforms(request)
+        return StrippedResult(result, transforms) if transforms.active else result
+
+
+def _click_runner_class() -> type:
+    """Build the click runner subclass, importing click lazily.
+
+    Built fresh on every call rather than cached. A cached class pins the
+    ``CliRunner`` from whichever click copy was importable first, and under
+    ``pytester`` a later run re-imports click fresh. The runner would then
+    build a ``Result`` from the stale copy while patch mode patches the fresh
+    ``click.testing.Result``, silently dropping all post-processing.
+
+    Returns:
+        The ``DevtoolsClickRunner`` class.
+    """
+    from click.testing import CliRunner  # noqa: PLC0415
+
+    return type("DevtoolsClickRunner", (_ResultPostProcessMixin, CliRunner), {})
+
+
+@pytest.fixture
+def cli_runner(request: pytest.FixtureRequest) -> Any:
+    """Provide a click CliRunner whose Result output is post-processed.
+
+    Use in place of ``click.testing.CliRunner()`` so that ANSI escape sequences
+    and other configured noise are removed from ``result.output``,
+    ``result.stdout`` and ``result.stderr``.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        A CliRunner subclass instance.
+    """
+    if not _has_click():
+        pytest.fail(
+            "The cli_runner fixture requires click. Install pytest-devtools[click].",
+            pytrace=False,
+        )
+    _check_min_version("click", MIN_CLICK_VERSION)
+
+    runner = _click_runner_class()()
+    runner._devtools_request = request  # noqa: SLF001
+    return runner
+
+
+def _typer_runner_class() -> type:
+    """Build the typer runner subclass, importing typer lazily.
+
+    Subclassing typer's own runner covers both typer eras: before 0.26 it is a
+    click CliRunner subclass, from 0.26 an independent implementation over
+    typer's vendored click.
+
+    Built fresh on every call rather than cached, for the same reason as the
+    click runner, plus one specific to typer: ``invoke()`` re-derives the click
+    command via ``get_command()``, which resolves unset ``Typer()`` defaults
+    with ``isinstance(value, DefaultPlaceholder)`` checks. Run against a
+    freshly imported typer, those checks fail across the two module copies and
+    let an unresolved placeholder leak through as real data.
+    """
+    from typer.testing import CliRunner  # noqa: PLC0415
+
+    return type("DevtoolsTyperRunner", (_ResultPostProcessMixin, CliRunner), {})
+
+
+@pytest.fixture
+def typer_runner(request: pytest.FixtureRequest) -> Any:
+    """Provide a typer CliRunner whose Result output is post-processed.
+
+    Use in place of ``typer.testing.CliRunner()`` so that ANSI escape sequences
+    and other configured noise are removed from ``result.output``,
+    ``result.stdout`` and ``result.stderr``.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        A typer CliRunner subclass instance.
+    """
+    if not _has_typer():
+        pytest.fail(
+            "The typer_runner fixture requires typer. Install pytest-devtools[typer].",
+            pytrace=False,
+        )
+    _check_min_version("typer", MIN_TYPER_VERSION)
+
+    runner = _typer_runner_class()()
+    runner._devtools_request = request  # noqa: SLF001
+    return runner
+
+
+def _result_classes() -> list[type]:
+    """Collect the installed frameworks' Result classes.
+
+    Before typer 0.26 ``typer.testing.Result`` is ``click.testing.Result``, so
+    de-duplicate by identity to avoid patching the same class twice.
+
+    Returns:
+        The distinct Result classes to patch.
+    """
+    classes: list[type] = []
+
+    if _has_click():
+        from click.testing import Result  # noqa: PLC0415
+
+        classes.append(Result)
+
+    if _has_typer():
+        from typer.testing import Result as TyperResult  # noqa: PLC0415
+
+        if TyperResult not in classes:
+            classes.append(TyperResult)
+
+    return classes
+
+
+@pytest.fixture(autouse=True)
+def _patch_cli_result(
+    request: pytest.FixtureRequest,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Post-process Result output for runners this plugin did not create.
+
+    Opt in with ``cli_runner_patch_result`` when runners are constructed
+    elsewhere, for instance in a project's own conftest fixture. monkeypatch
+    teardown restores the original properties after each test.
+
+    The replacement properties resolve transforms on every read rather than
+    once here, so ``tmp_path`` materializes only if a test actually reads a
+    patched ``Result`` attribute, not for every test that merely has patching
+    and tmp_path stripping enabled.
+
+    Args:
+        request: The pytest fixture request object.
+        monkeypatch: The pytest monkeypatch fixture.
+    """
+    if not _patch_active(request):
+        return
+
+    if not _transforms_configured(request):
+        return
+
+    for result_cls in _result_classes():
+        for name in ("output", "stdout", "stderr"):
+            original = getattr(result_cls, name)
+            monkeypatch.setattr(
+                result_cls,
+                name,
+                property(
+                    lambda self, _fget=original.fget: _resolve_transforms(request).apply(
+                        _fget(self)
+                    )
+                ),
+            )

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/src/devtools/columns.py

@@ -43,7 +43,7 @@ def add_options(parser: pytest.Parser) -> None:
     )
 
 
-def _get_columns_value(config: Config) -> int | None:
+def get_columns_value(config: Config) -> int | None:
     """Determine the COLUMNS value from CLI and ini options.
 
     Args:
@@ -71,6 +71,6 @@ def _set_columns(request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch
         request: The pytest fixture request object.
         monkeypatch: The pytest monkeypatch fixture.
     """
-    columns = _get_columns_value(request.config)
+    columns = get_columns_value(request.config)
     if columns is not None:
         monkeypatch.setenv("COLUMNS", str(columns))

{pytest_devtools-1.2.0 → pytest_devtools-1.3.0}/src/devtools/plugin.py

@@ -9,8 +9,11 @@ import pytest
 if TYPE_CHECKING:
     from collections.abc import Generator
 
-from devtools import capsys_strip, columns, debug_fixture, whitespace
+from devtools import capsys_strip, cli_runners, columns, debug_fixture, whitespace
 from devtools.capsys_strip import capsys as capsys  # noqa: PLC0414
+from devtools.cli_runners import _patch_cli_result as _patch_cli_result  # noqa: PLC0414
+from devtools.cli_runners import cli_runner as cli_runner  # noqa: PLC0414
+from devtools.cli_runners import typer_runner as typer_runner  # noqa: PLC0414
 from devtools.columns import _set_columns as _set_columns  # noqa: PLC0414
 from devtools.debug_fixture import debug as debug  # noqa: PLC0414
 from devtools.debug_fixture import phase_report_key
@@ -22,6 +25,7 @@ def pytest_addoption(parser: pytest.Parser) -> None:
     capsys_strip.add_options(parser)
     whitespace.add_options(parser)
     debug_fixture.add_options(parser)
+    cli_runners.add_options(parser)
 
 
 def pytest_configure(config: pytest.Config) -> None: