tests.test_help module

Conformance of every command’s --help: that it is exercised, and readable.

The --help invocations themselves live as [[cases]] entries in tests/cli-test-suite.toml, executed by click-extra test-suite in CI and against the compiled binaries during releases. A static roster drifts as commands are added or removed, so the first test compares it against the live command tree and fails naming the missing or orphaned entries.

Exercising a command’s help says nothing about how it reads, which the second test covers: it walks the same tree and rejects a docstring whose example blocks Click will rewrap into prose.

tests.test_help.NO_REWRAP = '\x08'

Click’s escape suppressing the rewrapping of one paragraph.

It only holds for the paragraph it opens, and only when it is that paragraph’s first line: click.formatting.wrap_text tests buf[0] and nothing else.

tests.test_help.test_suite_covers_all_commands()

Every command and subcommand must have a --help case in the suite.

Return type:

None

tests.test_help.test_every_preformatted_block_carries_its_own_marker()

Every indented block in a --help text must open with its own marker.

Writing one marker above a run of example blocks reads as if it covered them all, and renders the first correctly, which is what lets the rest ship collapsed. Both offenders this caught had exactly that shape.

Return type:

None

tests.test_help.test_lazy_choice_degrades_instead_of_refusing_everything(choice_type, monkeypatch)

A type that cannot resolve accepts anything, rather than nothing.

An empty Choice refuses every value including the option’s own default, so a project the type cannot read would take the whole command down. Each subclass either declares a fallback it can always offer, or passes the value through untouched.

tests.test_help.test_lazy_choice_survives_a_resolver_that_raises(choice_type, monkeypatch)

Resolution runs while Click renders, where a traceback replaces the help.

tests.test_help.test_every_command_renders_its_help_outside_a_project(tmp_path, monkeypatch)

--help must render anywhere, whatever the lazy types can resolve.

Every one of them reads the working directory, so a directory holding no pyproject.toml and no .github/ is where an unguarded resolver shows up.