1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
Testing Click Applications
==========================
.. currentmodule:: click.testing
For basic testing, Click provides the :mod:`click.testing` module which
provides test functionality that helps you invoke command line
applications and check their behavior.
These tools should really only be used for testing as they change
the entire interpreter state for simplicity and are not in any way
thread-safe!
Basic Testing
-------------
The basic functionality for testing Click applications is the
:class:`CliRunner` which can invoke commands as command line scripts. The
:meth:`CliRunner.invoke` method runs the command line script in isolation
and captures the output as both bytes and binary data.
Note that :meth:`CliRunner.invoke` is asynchronous. The :func:`runner`
fixture, which most Click tests use, contains a synchronous :attr:`invoke`
for your convenience.
The return value is a :class:`Result` object, which has the captured output
data, exit code, and optional exception attached:
.. code-block:: python
:caption: hello.py
import asyncclick as click
@click.command()
@click.argument('name')
async def hello(name):
click.echo(f'Hello {name}!')
.. code-block:: python
:caption: test_hello.py
from asyncclick.testing import CliRunner
from hello import hello
@pytest.mark.anyio
async def test_hello_world():
runner = CliRunner()
result = await runner.invoke(hello, ['Peter'])
assert result.exit_code == 0
assert result.output == 'Hello Peter!\n'
For subcommand testing, a subcommand name must be specified in the `args` parameter of :meth:`CliRunner.invoke` method:
.. code-block:: python
:caption: sync.py
import asyncclick as click
@click.group()
@click.option('--debug/--no-debug', default=False)
async def cli(debug):
click.echo(f"Debug mode is {'on' if debug else 'off'}")
@cli.command()
async def sync():
click.echo('Syncing')
.. code-block:: python
:caption: test_sync.py
from asyncclick.testing import CliRunner
from sync import cli
@pytest.mark.anyio
async def test_sync():
runner = CliRunner()
result = await runner.invoke(cli, ['--debug', 'sync'])
assert result.exit_code == 0
assert 'Debug mode is on' in result.output
assert 'Syncing' in result.output
Additional keyword arguments passed to ``.invoke()`` will be used to construct the initial Context object.
For example, if you want to run your tests against a fixed terminal width you can use the following::
runner = CliRunner()
result = await runner.invoke(cli, ['--debug', 'sync'], terminal_width=60)
File System Isolation
---------------------
For basic command line tools with file system operations, the
:meth:`CliRunner.isolated_filesystem` method is useful for setting the
current working directory to a new, empty folder.
.. code-block:: python
:caption: cat.py
import asyncclick as click
@click.command()
@click.argument('f', type=click.File())
async def cat(f):
click.echo(f.read())
.. code-block:: python
:caption: test_cat.py
from asyncclick.testing import CliRunner
from cat import cat
@pytest.mark.anyio
async def test_cat():
runner = CliRunner()
with runner.isolated_filesystem():
with open('hello.txt', 'w') as f:
f.write('Hello World!')
result = await runner.invoke(cat, ['hello.txt'])
assert result.exit_code == 0
assert result.output == 'Hello World!\n'
Pass ``temp_dir`` to control where the temporary directory is created.
The directory will not be removed by Click in this case. This is useful
to integrate with a framework like Pytest that manages temporary files.
.. code-block:: python
def test_keep_dir(tmp_path):
runner = CliRunner()
with runner.isolated_filesystem(temp_dir=tmp_path) as td:
...
Input Streams
-------------
The test wrapper can also be used to provide input data for the input
stream (stdin). This is very useful for testing prompts, for instance:
.. code-block:: python
:caption: prompt.py
import asyncclick as click
@click.command()
@click.option('--foo', prompt=True)
async def prompt(foo):
click.echo(f"foo={foo}")
.. code-block:: python
:caption: test_prompt.py
from asyncclick.testing import CliRunner
from prompt import prompt
def test_prompts():
runner = CliRunner()
result = await runner.invoke(prompt, input='wau wau\n')
assert not result.exception
assert result.output == 'Foo: wau wau\nfoo=wau wau\n'
Note that prompts will be emulated so that they write the input data to
the output stream as well. If hidden input is expected then this
obviously does not happen.
|
