click.testing.CliRunner Class Reference

Public Member Functions
None	__init__ (self, str charset="utf-8", cabc.Mapping[str, str|None]|None env=None, bool echo_stdin=False, bool catch_exceptions=True)
str	get_default_prog_name (self, Command cli)
cabc.Mapping[str, str|None]	make_env (self, cabc.Mapping[str, str|None]|None overrides=None)
cabc.Iterator[tuple[io.BytesIO, io.BytesIO, io.BytesIO]]	isolation (self, str|bytes|t.IO[t.Any]|None input=None, cabc.Mapping[str, str|None]|None env=None, bool color=False)
Result	invoke (self, Command cli, str|cabc.Sequence[str]|None args=None, str|bytes|t.IO[t.Any]|None input=None, cabc.Mapping[str, str|None]|None env=None, bool|None catch_exceptions=None, bool color=False, **t.Any extra)
cabc.Iterator[str]	isolated_filesystem (self, str|os.PathLike[str]|None temp_dir=None)

Public Attributes
	charset
	echo_stdin
	catch_exceptions

Detailed Description

The CLI runner provides functionality to invoke a Click command line
script for unittesting purposes in a isolated environment.  This only
works in single-threaded systems without any concurrency as it changes the
global interpreter state.

:param charset: the character set for the input and output data.
:param env: a dictionary with environment variables for overriding.
:param echo_stdin: if this is set to `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.
:param catch_exceptions: Whether to catch any exceptions other than
                         ``SystemExit`` when running :meth:`~CliRunner.invoke`.

.. versionchanged:: 8.2
    Added the ``catch_exceptions`` parameter.

.. versionchanged:: 8.2
    ``mix_stderr`` parameter has been removed.

Member Function Documentation

get_default_prog_name()

str click.testing.CliRunner.get_default_prog_name	(		self,
		Command	cli
	)

Given a command object it will return the default program name
for it.  The default is the `name` attribute or ``"root"`` if not
set.

invoke()

Result click.testing.CliRunner.invoke	(		self,
		Command	cli,
		str | cabc.Sequence[str] | None	args = None,
		str | bytes | t.IO[t.Any] | None	input = None,
		cabc.Mapping[str, str | None] | None	env = None,
		bool | None	catch_exceptions = None,
		bool	color = False,
		**t.Any	extra
	)

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 :meth:`~clickpkg.Command.main` function of
the command.

This returns a :class:`Result` object.

:param cli: the command to invoke
:param args: 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
             :func:`shlex.split`.
:param input: the input data for `sys.stdin`.
:param env: the environment overrides.
:param catch_exceptions: Whether to catch any other exceptions than
                         ``SystemExit``. If :data:`None`, the value
                         from :class:`CliRunner` is used.
:param extra: the keyword arguments to pass to :meth:`main`.
:param color: whether the output should contain color codes. The
              application can still override this explicitly.

.. versionadded:: 8.2
    The result object has the ``output_bytes`` attribute with
    the mix of ``stdout_bytes`` and ``stderr_bytes``, as the user would
    see it in its terminal.

.. versionchanged:: 8.2
    The result object always returns the ``stderr_bytes`` stream.

.. versionchanged:: 8.0
    The result object has the ``return_value`` attribute with
    the value returned from the invoked command.

.. versionchanged:: 4.0
    Added the ``color`` parameter.

.. versionchanged:: 3.0
    Added the ``catch_exceptions`` parameter.

.. versionchanged:: 3.0
    The result object has the ``exc_info`` attribute with the
    traceback if available.

isolated_filesystem()

cabc.Iterator[str] click.testing.CliRunner.isolated_filesystem	(		self,
		str | os.PathLike[str] | None	temp_dir = None
	)

A context manager that creates a temporary directory and
changes the current working directory to it. This isolates tests
that affect the contents of the CWD to prevent them from
interfering with each other.

:param temp_dir: Create the temporary directory under this
    directory. If given, the created directory is not removed
    when exiting.

.. versionchanged:: 8.0
    Added the ``temp_dir`` parameter.

isolation()

cabc.Iterator[tuple[io.BytesIO, io.BytesIO, io.BytesIO]] click.testing.CliRunner.isolation	(		self,
		str | bytes | t.IO[t.Any] | None	input = None,
		cabc.Mapping[str, str | None] | None	env = None,
		bool	color = False
	)

A context manager that sets up the isolation for invoking of a
command line tool.  This sets up `<stdin>` with the given input data
and `os.environ` with the overrides from the given dictionary.
This also rebinds some internals in Click to be mocked (like the
prompt functionality).

This is automatically done in the :meth:`invoke` method.

:param input: the input stream to put into `sys.stdin`.
:param env: the environment overrides as dictionary.
:param color: whether the output should contain color codes. The
              application can still override this explicitly.

.. versionadded:: 8.2
    An additional output stream is returned, which is a mix of
    `<stdout>` and `<stderr>` streams.

.. versionchanged:: 8.2
    Always returns the `<stderr>` stream.

.. versionchanged:: 8.0
    `<stderr>` is opened with ``errors="backslashreplace"``
    instead of the default ``"strict"``.

.. versionchanged:: 4.0
    Added the ``color`` parameter.

make_env()

cabc.Mapping[str, str | None] click.testing.CliRunner.make_env	(		self,
		cabc.Mapping[str, str | None] | None	overrides = None
	)

Returns the environment overrides for invoking a script.

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/click/testing.py