consolekit.testing

Test helpers.

New in version 0.9.0.

Attention

This module has the following additional requirements:

coincidence>=0.1.0
pytest>=6.0.0
pytest-regressions>=2.0.2

These can be installed as follows:

python -m pip install consolekit[testing]

Classes:

CliRunner([charset, env, echo_stdin, mix_stderr])

Provides functionality to invoke and test a Click script in an isolated environment.

Result(runner, stdout_bytes, stderr_bytes, …)

Holds the captured result of an invoked CLI script.

Functions:

cli_runner()

Returns a click runner for this test function.
class CliRunner(charset='UTF-8', env=None, *, echo_stdin=False, mix_stderr=True)[source]

Bases: CliRunner

Provides functionality to invoke and test a Click script in an isolated environment.

This only works in single-threaded systems without any concurrency as it changes the global interpreter state.

Parameters

  • charset (str) – The character set for the input and output data. Default 'UTF-8'.

  • env (Optional[Mapping[str, str]]) – A dictionary with environment variables to override. Default None.

  • echo_stdin (bool) – If True, then reading from stdin writes to stdout. This is useful for showing examples in some circumstances. Note that regular prompts will automatically echo the input. Default False.

  • mix_stderr (bool) – If False, then stdout and stderr are preserved as independent streams. This is useful for Unix-philosophy apps that have predictable stdout and noisy stderr, such that each may be measured independently. Default True.

invoke(cli, args=None, input=None, env=None, *, catch_exceptions=False, color=False, **extra)[source]

Invokes a command in an isolated environment.

The arguments are forwarded directly to the command line script, the extra keyword arguments are passed to the main() function of the command.

Parameters

  • cli (BaseCommand) – The command to invoke.

  • args (Union[str, Iterable[str], None]) – The arguments to invoke. It may be given as an iterable or a string. When given as string it will be interpreted as a Unix shell command. More details at shlex.split(). Default None.

  • input (Union[bytes, str, IO, None]) – The input data for sys.stdin. Default None.

  • env (Optional[Mapping[str, str]]) – The environment overrides. Default None.

  • catch_exceptions (bool) – Whether to catch any other exceptions than SystemExit. Default False.

  • color (bool) – whether the output should contain color codes. The application can still override this explicitly. Default False.

  • **extra – The keyword arguments to pass to click.Command.main().

Return type

Result

class Result(runner, stdout_bytes, stderr_bytes, exit_code, exception, exc_info=None)[source]

Bases: Result

Holds the captured result of an invoked CLI script.

Parameters

Methods:

check_stdout(file_regression[, extension])

Perform a regression check on the standard output from the command.

Attributes:

output

The (standard) output as a string.

stderr

The standard error as a string.

stdout

The standard output as a string.
check_stdout(file_regression, extension='.txt', **kwargs)[source]

Perform a regression check on the standard output from the command.

Parameters

  • file_regression (FileRegressionFixture)

  • extension (str) – The extension of the reference file. Default '.txt'.

  • **kwargs – Additional keyword arguments passed to FileRegressionFixture.check().

Return type

Literal[True]

property output

The (standard) output as a string.

Return type

str

property stderr

The standard error as a string.

Return type

str

property stdout

The standard output as a string.

Return type

str

fixture cli_runner[source]

Scope:    function

Returns a click runner for this test function.

Return type

CliRunner