testing.CliRunner does not follow terminal_width parameter

[mbergen]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the Typer documentation, with the integrated search.
• I already searched in Google "How to X in Typer" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.
• I already checked if it is not related to Typer but to Click.

Commit to Help

• I commit to help with one of those options 👆

Example Code

import click

LONG_HELP_TEXT = "This is a really long help text that does eventually wrap in the command output"

@click.command()
@click.option('--name', 'name', help=LONG_HELP_TEXT)
def hello_click(name):
   click.echo(f'Hello {name}!')


from click.testing import CliRunner as ClickCliRunner

def test_click_runner():
  runner = ClickCliRunner()
  # DOES WORK
  result = runner.invoke(hello_click, ['--help'], terminal_width=1000)
  print(result.output)
  assert result.exit_code == 0
  assert LONG_HELP_TEXT in result.output


import typer

app = typer.Typer()

@app.command()
def hello_typer(name: str = typer.Option(help=LONG_HELP_TEXT)):
   typer.echo(f'Hello {name}!')

from typer.testing import CliRunner as TyperCliRunner

def test_typer_runner():
   runner = TyperCliRunner()
   # DOES NOT WORK
   result = runner.invoke(app, ['hello_typer', '--help'], terminal_width=1000)
   print(result.output)
   assert result.exit_code == 0
   assert LONG_HELP_TEXT in result.output

Description

When using the CliRunner for testing, the terminal width seems to be at 80 chars.
Since this leads to linebreaks almost always, especially when options have a bit longer help texts, it makes it easier to check the output for longer line lengths.

According to Click documentation, passing terminal_width should allow to do that, and per the example this works when using a click command with the click CliRunner.

When using a typer app and typer CliRunner, adjusting the terminal_width in CliRunner does not have any effect.
Instead, one has to rely on setting the TERMINAL_WIDTH environment variable to achieve this.

Operating System

Linux

Operating System Details

No response

Typer Version

0.21.1

Python Version

3.12

Additional Context

No response

[svlandeg]

Hi @mbergen, thanks for the report! This seems to only be an issue when rich_markup_mode is enabled. We'll look into it!

[svlandeg]

Using pytest -s on a normal console will in fact fix things - I have mentioned it here to help other as well who may run into this. I feel like you're being very dismissive of everything I ask/say, even when you didn't provide all this information up front. I have only been trying to be helpful/constructive.

Anyway, considering Tiangolo's comment here, and the fact that this is a Rich limitation / console configuration issue, we probably won't be following up on this further. Setting an env var in a test suite (or two) is not a huge deal.

[mbergen]

I'm sorry if my responses came through as dismissive, i'm not a native speaker and did not intend to be dismissive.
As far as i understand i've answered all questions you asked and responded to your input with results from my machine(s) and my understanding of the topic.

If you are referring to the content of #1520 (reply in thread), i was trying to suggest an improvement to either the tooling or the documentation. I thought that a discussion here would be the place for that.

[svlandeg]

Definitely, which is why I wanted to understand the exact use-case. I know that Tiangolo is usually hesitant of adding additional features if they can be solved some other way. In this particular case, I had already previously worked on this PR which added a similar option to what you're asking (not exactly the same, but close), and it was eventually decided not to merge it in because the underlying issue is with the terminal. The point being that Typer assumes Rich does the right thing and uses full-length. So if there's ways for you to work around this (with env vars) that will probably be the best solution for now 😕

[mbergen]

Alright. Would it make sense for me to open a PR to add this info to the documentation about testing typer applications?

[svlandeg]

Sure!

[mbergen]

For reference:

Terminal width for output using Rich can be set with environment variable COLUMNS
Terminal width for output of Typer can be set with environment variable TERMINAL_WIDTH

[shauneccles]

Still reproduces on master (9a7b2e8). CliRunner already pins a help width, but only for the formatter that rich_markup_mode bypasses.

CliRunner.isolation() sets formatting.FORCED_WIDTH = 80:

typer/typer/testing.py

Lines 174 to 175 in 9a7b2e8

	old_forced_width = formatting.FORCED_WIDTH
	formatting.FORCED_WIDTH = 80

The constant it sets is the Click formatter's test hook:

typer/typer/_click/formatting.py

Lines 7 to 8 in 9a7b2e8

	# Can force a width. This is used by the test system
	FORCED_WIDTH: int | None = None

With rich_markup_mode enabled, which is the default, format_help branches to the Rich renderer and never uses its formatter argument. That argument is the one Click builds from ctx.terminal_width and ctx.max_content_width:

typer/typer/core.py

Lines 981 to 994 in 9a7b2e8

	def format_help(self, ctx: _click.Context, formatter: _click.HelpFormatter) -> None:
	if not HAS_RICH or self.rich_markup_mode is None:
	if not hasattr(ctx, "obj") or ctx.obj is None:
	ctx.ensure_object(dict)
	if isinstance(ctx.obj, dict):
	ctx.obj[MARKUP_MODE_KEY] = self.rich_markup_mode
	return super().format_help(ctx, formatter)
	from . import rich_utils
	return rich_utils.rich_format_help(
	obj=self,
	ctx=ctx,
	markup_mode=self.rich_markup_mode,
	)

The Rich renderer builds its own console, whose width comes from a module-level constant read once at import:

typer/typer/rich_utils.py

Lines 145 to 163 in 9a7b2e8

	def _get_rich_console(stderr: bool = False) -> Console:
	return Console(
	theme=Theme(
	{
	"option": STYLE_OPTION,
	"switch": STYLE_SWITCH,
	"negative_option": STYLE_NEGATIVE_OPTION,
	"negative_switch": STYLE_NEGATIVE_SWITCH,
	"types": STYLE_TYPES,
	"types_sep": STYLE_TYPES_SEPARATOR,
	"usage": STYLE_USAGE,
	},
	),
	highlighter=highlighter,
	color_system=COLOR_SYSTEM,
	force_terminal=FORCE_TERMINAL,
	width=MAX_WIDTH,
	stderr=stderr,
	)

typer/typer/rich_utils.py

Lines 72 to 73 in 9a7b2e8

	_TERMINAL_WIDTH = getenv("TERMINAL_WIDTH")
	MAX_WIDTH = int(_TERMINAL_WIDTH) if _TERMINAL_WIDTH else None

So FORCED_WIDTH and ctx.terminal_width both stop at that branch, and TERMINAL_WIDTH is already fixed by the time a test could set it: CliRunner.invoke(env=...) runs long after typer.rich_utils was imported.

The clearest sign of the gap is in this repo's own tests. All four tests that pass terminal_width= turn Rich off to do it:

typer/tests/test_cli/test_help.py

Lines 125 to 141 in 9a7b2e8

	assert args_line.startswith(" ")
	def test_format_long_help_option() -> None:
	app = typer.Typer(rich_markup_mode=None)
	@app.command()
	def cmd(
	very_long: str = typer.Option(
	...,
	"--this-is-a-very-very-very-long-option-name",
	help="Description is rendered in the next line for long option labels.",
	),
	) -> None:
	pass # pragma: no cover
	result = runner.invoke(app, ["cmd", "--help"], terminal_width=80)

test_format_long_help_option opens with typer.Typer(rich_markup_mode=None), and so do the other three. There is currently no way to write that test against the default renderer.

Reproduction

import typer
from typer._click import formatting
from typer.testing import CliRunner

app = typer.Typer()


@app.command()
def build(
    env_file: str = typer.Option(
        None,
        help=(
            "A deliberately long help line so any wrapping is obvious: "
            "DBMLSP_ENTERPRISE_READER sets the reporting service account."
        ),
    ),
) -> None:
    """Build something."""


runner = CliRunner()

outside = formatting.FORCED_WIDTH
with runner.isolation():
    inside = formatting.FORCED_WIDTH
print(f"formatting.FORCED_WIDTH  outside isolation(): {outside}")
print(f"formatting.FORCED_WIDTH  inside  isolation(): {inside}")

for label, kwargs in (("no argument", {}), ("terminal_width=200", {"terminal_width": 200})):
    result = runner.invoke(app, ["--help"], **kwargs)
    widest = max((len(line) for line in result.output.splitlines()), default=0)
    print(f"invoke({label:<20}) -> widest rendered line = {widest}")

Output:

formatting.FORCED_WIDTH  outside isolation(): None
formatting.FORCED_WIDTH  inside  isolation(): 80
invoke(no argument         ) -> widest rendered line = 79
invoke(terminal_width=200  ) -> widest rendered line = 79

FORCED_WIDTH is 80 and the output is 79 columns, but those are two independent defaults rather than the hook working. terminal_width=200 changes nothing, and COLUMNS=200 gives 199.

The fix

Resolve the width from the context before building the console, so an explicit terminal_width wins over the TERMINAL_WIDTH environment variable. That ordering mirrors the Click formatter, where the width argument is consulted before FORCED_WIDTH:

typer/typer/_click/formatting.py

Lines 105 to 115 in 9a7b2e8

	) -> None:
	self.indent_increment = indent_increment
	if max_width is None:
	max_width = 80
	if width is None:
	import shutil
	width = FORCED_WIDTH
	if width is None:
	width = max(min(shutil.get_terminal_size().columns, max_width) - 2, 50)
	self.width = width

def _get_help_width(ctx: _click.Context | None) -> int | None:
    if ctx is None or ctx.terminal_width is None:
        return MAX_WIDTH
    return ctx.terminal_width


def _get_rich_console(stderr: bool = False, width: int | None = None) -> Console:
    return Console(
        ...
        width=width if width is not None else MAX_WIDTH,
        ...
    )

rich_format_help passes _get_help_width(ctx). rich_format_error does the same, moving its existing getattr(self, "ctx", None) lookup above the console construction, so error panels wrap correctly too.

That is 20 changed lines in typer/rich_utils.py, plus three tests. It touches neither pyproject.toml nor uv.lock.

The three tests fail on master and pass with the change. Under scripts/test.sh, which exports TERMINAL_WIDTH=3000, the failure reads:

result = runner.invoke(app, ["cmd"], terminal_width=60)
assert result.exit_code != 0
>       assert max(len(line) for line in result.output.splitlines()) <= 60
E       assert 3000 <= 60

The branch and its CI run are here, staged on a fork rather than opened against this repo: shauneccles#1

Full matrix is green: all seven Test legs (Linux, macOS and Windows across Python 3.10 to 3.14, including both lowest-direct legs that resolve rich to its 13.8.0 floor), coverage-combine at --fail-under=100, and pre-commit. typer/rich_utils.py stays at 100%. The only red check is Add to Project, which needs maintainer secrets a fork does not have.

I have deliberately left max_content_width alone. Rich takes an exact width rather than a cap, so honouring it means clamping against a detected width, which is a larger change and a separate decision. Happy to fold it in if you would rather close #511 at the same time.

FORCE_TERMINAL under GITHUB_ACTIONS

A second difference, which the patch does not touch. FORCE_TERMINAL is true whenever GITHUB_ACTIONS is set:

typer/typer/rich_utils.py

Lines 77 to 84 in 9a7b2e8

	_TYPER_FORCE_DISABLE_TERMINAL = getenv("_TYPER_FORCE_DISABLE_TERMINAL")
	FORCE_TERMINAL = (
	True
	if getenv("GITHUB_ACTIONS") or getenv("FORCE_COLOR") or getenv("PY_COLORS")
	else None
	)
	if _TYPER_FORCE_DISABLE_TERMINAL:
	FORCE_TERMINAL = False

A downstream test then gets ANSI escapes on CI that it never gets locally, on top of wrapping at a different width. _TYPER_FORCE_DISABLE_TERMINAL turns it off, though the leading underscore suggests it is not meant for downstream use. From one of our CI runs, green locally and red on ubuntu-latest:

E  assert 'nowhere.env' in "\x1b[1;33mUsage: \x1b[0m\x1b[1mbuild [OPTIONS]\x1b[0m\n\x1b[2mTry \x1b[0m..."

Stripping the escapes produced a second failure:

E  assert 'nowhere.env' in "... /test_an_ex0/now here.env does not exist. ..."

The temp path wrapped mid-token, so nowhere.env arrived as now here.env. That test was asserting on presentation and deserved rewriting. It is here because there was no supported way to pin the presentation instead.

Environment

• Typer master at 9a7b2e8, and 0.27.0 as released
• Rich 15.0.0 locally, 13.8.0 on the lowest-direct CI legs
• Python 3.14.7
• Windows 11 locally, ubuntu-latest on CI

Related

• Long help text wraps too narrowly #511, diagnosing the same mechanism in 2022: "the Console used to generate helps does not respect the max_content_width context setting that click uses."
• Passing 'context_settings' to typer.Typer has no effect, but works for app.command() #365, closed with the note that the parameter is ignored while Rich is installed.
• ✅ Monkeypatch console width to allow running pytest directly #1542, which fixed this for Typer's own test suite with monkeypatch.setenv("COLUMNS", "200") rather than in the library.
• 📝 Add information about terminal width for testing output #1521, open, documenting the environment-variable workaround.

Glad to open the PR if this shape works for you.

One housekeeping note: this thread is marked as answered, but the answer records the COLUMNS and TERMINAL_WIDTH workaround rather than a fix, so it may not show up in triage any more. Happy to move this to a fresh discussion if that routes better, or to open the PR directly against @svlandeg's "we'll look into it" above. Whichever you prefer.

[DariuszPiskorowski]

Just confirming this workaround from another real-world project.

We hit the same issue with Typer 0.27.0 + Rich 15.0.0 on GitHub Actions (ubuntu-latest). Our CLI tests using typer.testing.CliRunner passed locally, while 10 tests checking --help output failed in CI. The commands themselves were successful (exit_code == 0), but assertions looking for option names in result.stdout failed because of the Rich/terminal rendering behavior under GITHUB_ACTIONS.

We added the following only to the pytest step:

- name: Run tests
  env:
    _TYPER_FORCE_DISABLE_TERMINAL: "1"
  run: uv run pytest

After that change, the complete test suite passed on GitHub Actions.

We deliberately did not set _TYPER_FORCE_DISABLE_TERMINAL for our normal CLI smoke/doctor step:

- name: Run doctor
  run: uv run midi-cleaner doctor --json

That step also passed, so in our case the workaround was needed specifically for the CliRunner tests and not for normal CLI execution.

Hopefully this confirmation helps others who encounter tests that are green locally but fail only under GitHub Actions.