Coverage for typer / testing.py: 100%
187 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
1import contextlib 1abcdefghij
2import io 1abcdefghij
3import os 1abcdefghij
4import shlex 1abcdefghij
5import sys 1abcdefghij
6from collections.abc import Generator, Mapping, Sequence 1abcdefghij
7from types import TracebackType 1abcdefghij
8from typing import IO, TYPE_CHECKING, Any, BinaryIO, cast 1abcdefghij
10from typer.main import Typer 1abcdefghij
11from typer.main import get_command as _get_command 1abcdefghij
13from . import _click 1abcdefghij
14from ._click import _compat, formatting, termui, utils 1abcdefghij
16if TYPE_CHECKING: 1abcdefghij
17 from _typeshed import ReadableBuffer
20def make_input_stream(input: str | bytes | None, charset: str) -> BinaryIO: 1abcdefghij
21 if input is None: 1abcdefghij
22 input = b"" 1abcdefghij
23 elif isinstance(input, str): 1abcdefghij
24 input = input.encode(charset) 1abcdefghij
26 return io.BytesIO(input) 1abcdefghij
29class BytesIOCopy(io.BytesIO): 1abcdefghij
30 """Patch ``io.BytesIO`` to let the written stream be copied to another."""
32 def __init__(self, copy_to: io.BytesIO) -> None: 1abcdefghij
33 super().__init__() 1abcdefghij
34 self.copy_to = copy_to 1abcdefghij
36 def flush(self) -> None: 1abcdefghij
37 super().flush() 1abcdefghij
38 self.copy_to.flush() 1abcdefghij
40 def write(self, b: "ReadableBuffer") -> int: 1abcdefghij
41 self.copy_to.write(b) 1abcdefghij
42 return super().write(b) 1abcdefghij
45class StreamMixer: 1abcdefghij
46 """Mixes `<stdout>` and `<stderr>` streams.
48 The result is available in the ``output`` attribute.
49 """
51 def __init__(self) -> None: 1abcdefghij
52 self.output: io.BytesIO = io.BytesIO() 1abcdefghij
53 self.stdout: io.BytesIO = BytesIOCopy(copy_to=self.output) 1abcdefghij
54 self.stderr: io.BytesIO = BytesIOCopy(copy_to=self.output) 1abcdefghij
56 def __del__(self) -> None: 1abcdefghij
57 """Guarantee that file-like objects are closed in a predictable order"""
58 self.stderr.close() 1abcdefghij
59 self.stdout.close() 1abcdefghij
60 self.output.close() 1abcdefghij
63class _NamedTextIOWrapper(io.TextIOWrapper): 1abcdefghij
64 def __init__(self, buffer: BinaryIO, name: str, mode: str, **kwargs: Any) -> None: 1abcdefghij
65 super().__init__(buffer, **kwargs) 1abcdefghij
66 self._name = name 1abcdefghij
67 self._mode = mode 1abcdefghij
69 @property 1abcdefghij
70 def name(self) -> str: 1abcdefghij
71 return self._name # pragma: no cover
73 @property 1abcdefghij
74 def mode(self) -> str: 1abcdefghij
75 return self._mode # pragma: no cover
78class Result: 1abcdefghij
79 """Holds the captured result of an invoked CLI script."""
81 def __init__( 1abcdefghij
82 self,
83 runner: "CliRunner",
84 stdout_bytes: bytes,
85 stderr_bytes: bytes,
86 output_bytes: bytes,
87 return_value: Any,
88 exit_code: int,
89 exception: BaseException | None,
90 exc_info: tuple[type[BaseException], BaseException, TracebackType]
91 | None = None,
92 ):
93 self.runner = runner 1abcdefghij
94 self.stdout_bytes = stdout_bytes 1abcdefghij
95 self.stderr_bytes = stderr_bytes 1abcdefghij
96 self.output_bytes = output_bytes 1abcdefghij
97 self.return_value = return_value 1abcdefghij
98 self.exit_code = exit_code 1abcdefghij
99 self.exception = exception 1abcdefghij
100 self.exc_info = exc_info 1abcdefghij
102 @property 1abcdefghij
103 def output(self) -> str: 1abcdefghij
104 """The terminal output as unicode string, as the user would see it."""
105 return self.output_bytes.decode(self.runner.charset, "replace").replace( 1abcdefghij
106 "\r\n", "\n"
107 )
109 @property 1abcdefghij
110 def stdout(self) -> str: 1abcdefghij
111 """The standard output as unicode string."""
112 return self.stdout_bytes.decode(self.runner.charset, "replace").replace( 1abcdefghij
113 "\r\n", "\n"
114 )
116 @property 1abcdefghij
117 def stderr(self) -> str: 1abcdefghij
118 """The standard error as unicode string."""
119 return self.stderr_bytes.decode(self.runner.charset, "replace").replace( 1abcdefghij
120 "\r\n", "\n"
121 )
123 def __repr__(self) -> str: 1abcdefghij
124 exc_str = repr(self.exception) if self.exception else "okay" 1abcdefghij
125 return f"<{type(self).__name__} {exc_str}>" 1abcdefghij
128class CliRunner: 1abcdefghij
129 """The CLI runner provides functionality to invoke a command line
130 script for unittesting purposes in an isolated environment. This only
131 works in single-threaded systems without any concurrency as it changes the
132 global interpreter state. Based on functionality from Click.
133 """
135 def __init__( 1abcdefghij
136 self,
137 charset: str = "utf-8",
138 env: Mapping[str, str | None] | None = None,
139 ) -> None:
140 self.charset = charset 1abcdefghij
141 self.env: Mapping[str, str | None] = env or {} 1abcdefghij
143 def get_default_prog_name(self, cli: _click.Command) -> str: 1abcdefghij
144 """Return the default program name for a command.
145 The default is the `name` attribute or ``"root"`` if not set.
146 """
147 return cli.name or "root" 1abcdefghij
149 def make_env( 1abcdefghij
150 self, overrides: Mapping[str, str | None] | None = None
151 ) -> Mapping[str, str | None]:
152 """Returns the environment overrides for invoking a script."""
153 rv = dict(self.env) 1abcdefghij
154 if overrides: 1abcdefghij
155 rv.update(overrides) 1abcdefghij
156 return rv 1abcdefghij
158 @contextlib.contextmanager 1abcdefghij
159 def isolation( 1abcdefghij
160 self,
161 input: str | bytes | None = None,
162 env: Mapping[str, str | None] | None = None,
163 color: bool = False,
164 ) -> Generator[tuple[io.BytesIO, io.BytesIO, io.BytesIO]]:
165 """A context manager that sets up the isolation for invoking of a
166 command line tool. This sets up `<stdin>` with the given input data
167 and `os.environ` with the overrides from the given dictionary.
168 """
169 bytes_input = make_input_stream(input, self.charset) 1abcdefghij
171 old_stdin = sys.stdin 1abcdefghij
172 old_stdout = sys.stdout 1abcdefghij
173 old_stderr = sys.stderr 1abcdefghij
174 old_forced_width = formatting.FORCED_WIDTH 1abcdefghij
175 formatting.FORCED_WIDTH = 80 1abcdefghij
177 env = self.make_env(env) 1abcdefghij
179 stream_mixer = StreamMixer() 1abcdefghij
181 sys.stdin = text_input = _NamedTextIOWrapper( 1abcdefghij
182 bytes_input, encoding=self.charset, name="<stdin>", mode="r"
183 )
185 sys.stdout = _NamedTextIOWrapper( 1abcdefghij
186 stream_mixer.stdout, encoding=self.charset, name="<stdout>", mode="w"
187 )
189 sys.stderr = _NamedTextIOWrapper( 1abcdefghij
190 stream_mixer.stderr,
191 encoding=self.charset,
192 name="<stderr>",
193 mode="w",
194 errors="backslashreplace",
195 )
197 def visible_input(prompt: str | None = None) -> str: 1abcdefghij
198 sys.stdout.write(prompt or "") 1abcdefghij
199 try: 1abcdefghij
200 val = next(text_input).rstrip("\r\n") 1abcdefghij
201 except StopIteration as e: # pragma: no cover
202 raise EOFError() from e
203 sys.stdout.write(f"{val}\n") 1abcdefghij
204 sys.stdout.flush() 1abcdefghij
205 return val 1abcdefghij
207 def hidden_input(prompt: str | None = None) -> str: 1abcdefghij
208 sys.stdout.write(f"{prompt or ''}\n") 1abcdefghij
209 sys.stdout.flush() 1abcdefghij
210 try: 1abcdefghij
211 return next(text_input).rstrip("\r\n") 1abcdefghij
212 except StopIteration as e: # pragma: no cover
213 raise EOFError() from e
215 def _getchar(echo: bool) -> str: 1abcdefghij
216 char = sys.stdin.read(1) 1abcdefghij
218 if echo: 1abcdefghij
219 sys.stdout.write(char) 1abcdefghij
221 sys.stdout.flush() 1abcdefghij
222 return char 1abcdefghij
224 default_color = color 1abcdefghij
226 def should_strip_ansi( 1abcdefghij
227 stream: IO[Any] | None = None, color: bool | None = None
228 ) -> bool:
229 if color is None: 1abcdefghij
230 return not default_color 1abcdefghij
231 return not color 1abcdefghij
233 old_visible_prompt_func = termui.visible_prompt_func 1abcdefghij
234 old_hidden_prompt_func = termui.hidden_prompt_func 1abcdefghij
235 old__getchar_func = termui._getchar 1abcdefghij
236 old_should_strip_ansi = utils.should_strip_ansi # type: ignore[attr-defined] 1abcdefghij
237 old__compat_should_strip_ansi = _compat.should_strip_ansi 1abcdefghij
238 termui.visible_prompt_func = visible_input 1abcdefghij
239 termui.hidden_prompt_func = hidden_input # ty: ignore[invalid-assignment] 1abcdefghij
240 termui._getchar = _getchar 1abcdefghij
241 utils.should_strip_ansi = should_strip_ansi # type: ignore 1abcdefghij
242 _compat.should_strip_ansi = should_strip_ansi # ty: ignore[invalid-assignment] 1abcdefghij
244 old_env = {} 1abcdefghij
245 try: 1abcdefghij
246 for key, value in env.items(): 1abcdefghij
247 old_env[key] = os.environ.get(key) 1abcdefghij
248 if value is None: 1abcdefghij
249 try: 1abcdefghij
250 del os.environ[key] 1abcdefghij
251 except Exception: # pragma: no cover
252 pass
253 else:
254 os.environ[key] = value 1abcdefghij
255 yield (stream_mixer.stdout, stream_mixer.stderr, stream_mixer.output) 1abcdefghij
256 finally:
257 for key, value in old_env.items(): 1abcdefghij
258 if value is None: 1abcdefghij
259 try: 1abcdefghij
260 del os.environ[key] 1abcdefghij
261 except Exception: # pragma: no cover
262 pass
263 else:
264 os.environ[key] = value 1abcdefghij
265 sys.stdout = old_stdout 1abcdefghij
266 sys.stderr = old_stderr 1abcdefghij
267 sys.stdin = old_stdin 1abcdefghij
268 termui.visible_prompt_func = old_visible_prompt_func 1abcdefghij
269 termui.hidden_prompt_func = old_hidden_prompt_func 1abcdefghij
270 termui._getchar = old__getchar_func 1abcdefghij
271 utils.should_strip_ansi = old_should_strip_ansi # type: ignore[attr-defined] 1abcdefghij
272 _compat.should_strip_ansi = old__compat_should_strip_ansi 1abcdefghij
273 formatting.FORCED_WIDTH = old_forced_width 1abcdefghij
275 def invoke( 1abcdefghij
276 self,
277 app: Typer,
278 args: str | Sequence[str] | None = None,
279 input: bytes | str | None = None,
280 env: Mapping[str, str | None] | None = None,
281 catch_exceptions: bool = True,
282 color: bool = False,
283 **extra: Any,
284 ) -> Result:
285 cli = _get_command(app) 1abcdefghij
286 exc_info = None 1abcdefghij
288 with self.isolation(input=input, env=env, color=color) as outstreams: 1abcdefghij
289 return_value = None 1abcdefghij
290 exception: BaseException | None = None 1abcdefghij
291 exit_code = 0 1abcdefghij
293 if isinstance(args, str): 1abcdefghij
294 args = shlex.split(args) 1abcdefghij
296 try: 1abcdefghij
297 prog_name = extra.pop("prog_name") 1abcdefghij
298 except KeyError: 1abcdefghij
299 prog_name = self.get_default_prog_name(cli) 1abcdefghij
301 try: 1abcdefghij
302 return_value = cli.main(args=args or (), prog_name=prog_name, **extra) 1abcdefghij
303 except SystemExit as e: 1abcdefghij
304 exc_info = sys.exc_info() 1abcdefghij
305 e_code = cast("int | Any | None", e.code) 1abcdefghij
307 if e_code is None: 1abcdefghij
308 e_code = 0 1abcdefghij
310 if e_code != 0: 1abcdefghij
311 exception = e 1abcdefghij
313 if not isinstance(e_code, int): 1abcdefghij
314 sys.stdout.write(str(e_code)) 1abcdefghij
315 sys.stdout.write("\n") 1abcdefghij
316 e_code = 1 1abcdefghij
318 exit_code = e_code 1abcdefghij
320 except Exception as e: 1abcdefghij
321 if not catch_exceptions: 1abcdefghij
322 raise 1abcdefghij
323 exception = e 1abcdefghij
324 exit_code = 1 1abcdefghij
325 exc_info = sys.exc_info() 1abcdefghij
326 finally:
327 sys.stdout.flush() 1abcdefghij
328 sys.stderr.flush() 1abcdefghij
329 stdout = outstreams[0].getvalue() 1abcdefghij
330 stderr = outstreams[1].getvalue() 1abcdefghij
331 output = outstreams[2].getvalue() 1abcdefghij
333 return Result( 1abcdefghij
334 runner=self,
335 stdout_bytes=stdout,
336 stderr_bytes=stderr,
337 output_bytes=output,
338 return_value=return_value,
339 exit_code=exit_code,
340 exception=exception,
341 exc_info=exc_info, # type: ignore
342 )