CLI testing¶

Todo

Write example and tutorial.

`click_extra.testing` API¶

        classDiagram
  AssertionError <|-- RegexLineMismatch
  CliRunner <|-- ExtraCliRunner
  Result <|-- ExtraResult

… py:module:: click_extra.testing

CLI testing and simulation of their execution.

… py:data:: PROMPT

module:

click_extra.testing

value:

‘$ ’

Prompt used to simulate the CLI execution.

… hint:: Use ASCII characters to avoid issues with Windows terminals.

… py:data:: INDENT

module:

click_extra.testing

value:

’ ’

Constants for rendering of CLI execution.

… py:function:: args_cleanup(*args)

module:

click_extra.testing

Flatten recursive iterables, remove all None, and cast each element to strings.

Helps serialize :py:class:pathlib.Path and other objects.

It also allows for nested iterables and None values as CLI arguments for convenience. We just need to flatten and filters them out.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`

… py:function:: format_cli_prompt(cmd_args, extra_env=None)

module:

click_extra.testing

Simulate the console prompt used to invoke the CLI.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str``

… py:function:: render_cli_run(args, result, env=None)

module:

click_extra.testing

Generates the full simulation of CLI execution, including output.

Mostly used to print debug traces to user or in test results.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str``

… py:function:: print_cli_run(args, result, env=None)

module:

click_extra.testing

Prints the full simulation of CLI execution, including output.

rtype:

sphinx_autodoc_typehints_type:: \:py\:obj\:\None``

… py:data:: INVOKE_ARGS

module:

click_extra.testing

value:

{‘args’, ‘catch_exceptions’, ‘cli’, ‘color’, ‘env’, ‘input’, ‘self’}

Parameter IDs of click.testing.CliRunner.invoke().

We need to collect them to help us identify which extra parameters passed to invoke() collides with its original signature.

… warning:: This has been reported upstream to Click project <https://github.com/pallets/click/issues/2110>_ but has been rejected and not considered an issue worth fixing.

… py:class:: ExtraResult(runner, stdout_bytes, stderr_bytes, output_bytes, return_value, exit_code, exception, exc_info=None)

module:

click_extra.testing

Bases: :py:class:~click.testing.Result

A Result subclass with automatic traceback formatting.

Enhances __repr__ so that pytest assertion failures show the full traceback instead of just the exception type.

… py:property:: ExtraResult.formatted_exception

module:

click_extra.testing

type:

str | None

Full formatted traceback, or None if no exception occurred.

… py:class:: ExtraCliRunner(charset=‘utf-8’, env=None, echo_stdin=False, catch_exceptions=True)

module:

click_extra.testing

Bases: :py:class:~click.testing.CliRunner

Augment :class:click.testing.CliRunner with extra features and bug fixes.

… py:attribute:: ExtraCliRunner.force_color

module:

click_extra.testing

type:

bool

value:

False

Global class attribute to override the color parameter in invoke.

… py:method:: ExtraCliRunner.invoke(cli, *args, input=None, env=None, catch_exceptions=True, color=None, **extra)

module:

click_extra.testing

Same as click.testing.CliRunner.invoke() with extra features.

The first positional parameter is the CLI to invoke. The remaining positional parameters of the function are the CLI arguments. All other parameters are required to be named.
The CLI arguments can be nested iterables of arbitrary depth. This is useful for argument composition of test cases with @pytest.mark.parametrize <https://docs.pytest.org/en/stable/example/parametrize.html>_.
Allow forcing of the color property at the class-level via force_color attribute.
Adds a special case in the form of color="forced" parameter, which allows colored output to be kept, while forcing the initialization of Context.color = True. This is not allowed in current implementation <https://github.com/pallets/click/issues/2110>_ of click.testing.CliRunner.invoke() because of colliding parameters.
Strips all ANSI codes from results if color was explicirely set to False.
Always prints a simulation of the CLI execution as the user would see it in its terminal. Including colors.
Pretty-prints a formatted exception traceback if the command fails.

type cli:

:sphinx_autodoc_typehints_type:\:py\:class\:\~click.core.Command``

param cli:

CLI to invoke.

param *args:

can be nested iterables composed of str, :py:class:pathlib.Path objects and None values. The nested structure will be flattened and None values will be filtered out. Then all elements will be casted to str. See :func:args_cleanup for details.

type input:

:sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`bytes` | :py:class:`~typing.IO` | :py:obj:`None``

param input:

CLI testing¶

click_extra.testing API¶

`click_extra.testing` API¶