Coverage for typer / testing.py: 100%

187 statements  

« 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

9 

10from typer.main import Typer 1abcdefghij

11from typer.main import get_command as _get_command 1abcdefghij

12 

13from . import _click 1abcdefghij

14from ._click import _compat, formatting, termui, utils 1abcdefghij

15 

16if TYPE_CHECKING: 1abcdefghij

17 from _typeshed import ReadableBuffer 

18 

19 

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

25 

26 return io.BytesIO(input) 1abcdefghij

27 

28 

29class BytesIOCopy(io.BytesIO): 1abcdefghij

30 """Patch ``io.BytesIO`` to let the written stream be copied to another.""" 

31 

32 def __init__(self, copy_to: io.BytesIO) -> None: 1abcdefghij

33 super().__init__() 1abcdefghij

34 self.copy_to = copy_to 1abcdefghij

35 

36 def flush(self) -> None: 1abcdefghij

37 super().flush() 1abcdefghij

38 self.copy_to.flush() 1abcdefghij

39 

40 def write(self, b: "ReadableBuffer") -> int: 1abcdefghij

41 self.copy_to.write(b) 1abcdefghij

42 return super().write(b) 1abcdefghij

43 

44 

45class StreamMixer: 1abcdefghij

46 """Mixes `<stdout>` and `<stderr>` streams. 

47 

48 The result is available in the ``output`` attribute. 

49 """ 

50 

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

55 

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

61 

62 

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

68 

69 @property 1abcdefghij

70 def name(self) -> str: 1abcdefghij

71 return self._name # pragma: no cover 

72 

73 @property 1abcdefghij

74 def mode(self) -> str: 1abcdefghij

75 return self._mode # pragma: no cover 

76 

77 

78class Result: 1abcdefghij

79 """Holds the captured result of an invoked CLI script.""" 

80 

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

101 

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 ) 

108 

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 ) 

115 

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 ) 

122 

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

126 

127 

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 """ 

134 

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

142 

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

148 

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

157 

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

170 

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

176 

177 env = self.make_env(env) 1abcdefghij

178 

179 stream_mixer = StreamMixer() 1abcdefghij

180 

181 sys.stdin = text_input = _NamedTextIOWrapper( 1abcdefghij

182 bytes_input, encoding=self.charset, name="<stdin>", mode="r" 

183 ) 

184 

185 sys.stdout = _NamedTextIOWrapper( 1abcdefghij

186 stream_mixer.stdout, encoding=self.charset, name="<stdout>", mode="w" 

187 ) 

188 

189 sys.stderr = _NamedTextIOWrapper( 1abcdefghij

190 stream_mixer.stderr, 

191 encoding=self.charset, 

192 name="<stderr>", 

193 mode="w", 

194 errors="backslashreplace", 

195 ) 

196 

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

206 

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 

214 

215 def _getchar(echo: bool) -> str: 1abcdefghij

216 char = sys.stdin.read(1) 1abcdefghij

217 

218 if echo: 1abcdefghij

219 sys.stdout.write(char) 1abcdefghij

220 

221 sys.stdout.flush() 1abcdefghij

222 return char 1abcdefghij

223 

224 default_color = color 1abcdefghij

225 

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

232 

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

243 

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

274 

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

287 

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

292 

293 if isinstance(args, str): 1abcdefghij

294 args = shlex.split(args) 1abcdefghij

295 

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

300 

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

306 

307 if e_code is None: 1abcdefghij

308 e_code = 0 1abcdefghij

309 

310 if e_code != 0: 1abcdefghij

311 exception = e 1abcdefghij

312 

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

317 

318 exit_code = e_code 1abcdefghij

319 

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

332 

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 )