debugging.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407
  1. # mypy: allow-untyped-defs
  2. # ruff: noqa: T100
  3. """Interactive debugging with PDB, the Python Debugger."""
  4. from __future__ import annotations
  5. import argparse
  6. from collections.abc import Callable
  7. from collections.abc import Generator
  8. import functools
  9. import sys
  10. import types
  11. from typing import Any
  12. import unittest
  13. from _pytest import outcomes
  14. from _pytest._code import ExceptionInfo
  15. from _pytest.capture import CaptureManager
  16. from _pytest.config import Config
  17. from _pytest.config import ConftestImportFailure
  18. from _pytest.config import hookimpl
  19. from _pytest.config import PytestPluginManager
  20. from _pytest.config.argparsing import Parser
  21. from _pytest.config.exceptions import UsageError
  22. from _pytest.nodes import Node
  23. from _pytest.reports import BaseReport
  24. from _pytest.runner import CallInfo
  25. def _validate_usepdb_cls(value: str) -> tuple[str, str]:
  26. """Validate syntax of --pdbcls option."""
  27. try:
  28. modname, classname = value.split(":")
  29. except ValueError as e:
  30. raise argparse.ArgumentTypeError(
  31. f"{value!r} is not in the format 'modname:classname'"
  32. ) from e
  33. return (modname, classname)
  34. def pytest_addoption(parser: Parser) -> None:
  35. group = parser.getgroup("general")
  36. group.addoption(
  37. "--pdb",
  38. dest="usepdb",
  39. action="store_true",
  40. help="Start the interactive Python debugger on errors or KeyboardInterrupt",
  41. )
  42. group.addoption(
  43. "--pdbcls",
  44. dest="usepdb_cls",
  45. metavar="modulename:classname",
  46. type=_validate_usepdb_cls,
  47. help="Specify a custom interactive Python debugger for use with --pdb."
  48. "For example: --pdbcls=IPython.terminal.debugger:TerminalPdb",
  49. )
  50. group.addoption(
  51. "--trace",
  52. dest="trace",
  53. action="store_true",
  54. help="Immediately break when running each test",
  55. )
  56. def pytest_configure(config: Config) -> None:
  57. import pdb
  58. if config.getvalue("trace"):
  59. config.pluginmanager.register(PdbTrace(), "pdbtrace")
  60. if config.getvalue("usepdb"):
  61. config.pluginmanager.register(PdbInvoke(), "pdbinvoke")
  62. pytestPDB._saved.append(
  63. (pdb.set_trace, pytestPDB._pluginmanager, pytestPDB._config)
  64. )
  65. pdb.set_trace = pytestPDB.set_trace
  66. pytestPDB._pluginmanager = config.pluginmanager
  67. pytestPDB._config = config
  68. # NOTE: not using pytest_unconfigure, since it might get called although
  69. # pytest_configure was not (if another plugin raises UsageError).
  70. def fin() -> None:
  71. (
  72. pdb.set_trace,
  73. pytestPDB._pluginmanager,
  74. pytestPDB._config,
  75. ) = pytestPDB._saved.pop()
  76. config.add_cleanup(fin)
  77. class pytestPDB:
  78. """Pseudo PDB that defers to the real pdb."""
  79. _pluginmanager: PytestPluginManager | None = None
  80. _config: Config | None = None
  81. _saved: list[
  82. tuple[Callable[..., None], PytestPluginManager | None, Config | None]
  83. ] = []
  84. _recursive_debug = 0
  85. _wrapped_pdb_cls: tuple[type[Any], type[Any]] | None = None
  86. @classmethod
  87. def _is_capturing(cls, capman: CaptureManager | None) -> str | bool:
  88. if capman:
  89. return capman.is_capturing()
  90. return False
  91. @classmethod
  92. def _import_pdb_cls(cls, capman: CaptureManager | None):
  93. if not cls._config:
  94. import pdb
  95. # Happens when using pytest.set_trace outside of a test.
  96. return pdb.Pdb
  97. usepdb_cls = cls._config.getvalue("usepdb_cls")
  98. if cls._wrapped_pdb_cls and cls._wrapped_pdb_cls[0] == usepdb_cls:
  99. return cls._wrapped_pdb_cls[1]
  100. if usepdb_cls:
  101. modname, classname = usepdb_cls
  102. try:
  103. __import__(modname)
  104. mod = sys.modules[modname]
  105. # Handle --pdbcls=pdb:pdb.Pdb (useful e.g. with pdbpp).
  106. parts = classname.split(".")
  107. pdb_cls = getattr(mod, parts[0])
  108. for part in parts[1:]:
  109. pdb_cls = getattr(pdb_cls, part)
  110. except Exception as exc:
  111. value = ":".join((modname, classname))
  112. raise UsageError(
  113. f"--pdbcls: could not import {value!r}: {exc}"
  114. ) from exc
  115. else:
  116. import pdb
  117. pdb_cls = pdb.Pdb
  118. wrapped_cls = cls._get_pdb_wrapper_class(pdb_cls, capman)
  119. cls._wrapped_pdb_cls = (usepdb_cls, wrapped_cls)
  120. return wrapped_cls
  121. @classmethod
  122. def _get_pdb_wrapper_class(cls, pdb_cls, capman: CaptureManager | None):
  123. import _pytest.config
  124. class PytestPdbWrapper(pdb_cls):
  125. _pytest_capman = capman
  126. _continued = False
  127. def do_debug(self, arg):
  128. cls._recursive_debug += 1
  129. ret = super().do_debug(arg)
  130. cls._recursive_debug -= 1
  131. return ret
  132. if hasattr(pdb_cls, "do_debug"):
  133. do_debug.__doc__ = pdb_cls.do_debug.__doc__
  134. def do_continue(self, arg):
  135. ret = super().do_continue(arg)
  136. if cls._recursive_debug == 0:
  137. assert cls._config is not None
  138. tw = _pytest.config.create_terminal_writer(cls._config)
  139. tw.line()
  140. capman = self._pytest_capman
  141. capturing = pytestPDB._is_capturing(capman)
  142. if capturing:
  143. if capturing == "global":
  144. tw.sep(">", "PDB continue (IO-capturing resumed)")
  145. else:
  146. tw.sep(
  147. ">",
  148. f"PDB continue (IO-capturing resumed for {capturing})",
  149. )
  150. assert capman is not None
  151. capman.resume()
  152. else:
  153. tw.sep(">", "PDB continue")
  154. assert cls._pluginmanager is not None
  155. cls._pluginmanager.hook.pytest_leave_pdb(config=cls._config, pdb=self)
  156. self._continued = True
  157. return ret
  158. if hasattr(pdb_cls, "do_continue"):
  159. do_continue.__doc__ = pdb_cls.do_continue.__doc__
  160. do_c = do_cont = do_continue
  161. def do_quit(self, arg):
  162. # Raise Exit outcome when quit command is used in pdb.
  163. #
  164. # This is a bit of a hack - it would be better if BdbQuit
  165. # could be handled, but this would require to wrap the
  166. # whole pytest run, and adjust the report etc.
  167. ret = super().do_quit(arg)
  168. if cls._recursive_debug == 0:
  169. outcomes.exit("Quitting debugger")
  170. return ret
  171. if hasattr(pdb_cls, "do_quit"):
  172. do_quit.__doc__ = pdb_cls.do_quit.__doc__
  173. do_q = do_quit
  174. do_exit = do_quit
  175. def setup(self, f, tb):
  176. """Suspend on setup().
  177. Needed after do_continue resumed, and entering another
  178. breakpoint again.
  179. """
  180. ret = super().setup(f, tb)
  181. if not ret and self._continued:
  182. # pdb.setup() returns True if the command wants to exit
  183. # from the interaction: do not suspend capturing then.
  184. if self._pytest_capman:
  185. self._pytest_capman.suspend_global_capture(in_=True)
  186. return ret
  187. def get_stack(self, f, t):
  188. stack, i = super().get_stack(f, t)
  189. if f is None:
  190. # Find last non-hidden frame.
  191. i = max(0, len(stack) - 1)
  192. while i and stack[i][0].f_locals.get("__tracebackhide__", False):
  193. i -= 1
  194. return stack, i
  195. return PytestPdbWrapper
  196. @classmethod
  197. def _init_pdb(cls, method, *args, **kwargs):
  198. """Initialize PDB debugging, dropping any IO capturing."""
  199. import _pytest.config
  200. if cls._pluginmanager is None:
  201. capman: CaptureManager | None = None
  202. else:
  203. capman = cls._pluginmanager.getplugin("capturemanager")
  204. if capman:
  205. capman.suspend(in_=True)
  206. if cls._config:
  207. tw = _pytest.config.create_terminal_writer(cls._config)
  208. tw.line()
  209. if cls._recursive_debug == 0:
  210. # Handle header similar to pdb.set_trace in py37+.
  211. header = kwargs.pop("header", None)
  212. if header is not None:
  213. tw.sep(">", header)
  214. else:
  215. capturing = cls._is_capturing(capman)
  216. if capturing == "global":
  217. tw.sep(">", f"PDB {method} (IO-capturing turned off)")
  218. elif capturing:
  219. tw.sep(
  220. ">",
  221. f"PDB {method} (IO-capturing turned off for {capturing})",
  222. )
  223. else:
  224. tw.sep(">", f"PDB {method}")
  225. _pdb = cls._import_pdb_cls(capman)(**kwargs)
  226. if cls._pluginmanager:
  227. cls._pluginmanager.hook.pytest_enter_pdb(config=cls._config, pdb=_pdb)
  228. return _pdb
  229. @classmethod
  230. def set_trace(cls, *args, **kwargs) -> None:
  231. """Invoke debugging via ``Pdb.set_trace``, dropping any IO capturing."""
  232. frame = sys._getframe().f_back
  233. _pdb = cls._init_pdb("set_trace", *args, **kwargs)
  234. _pdb.set_trace(frame)
  235. class PdbInvoke:
  236. def pytest_exception_interact(
  237. self, node: Node, call: CallInfo[Any], report: BaseReport
  238. ) -> None:
  239. capman = node.config.pluginmanager.getplugin("capturemanager")
  240. if capman:
  241. capman.suspend_global_capture(in_=True)
  242. out, err = capman.read_global_capture()
  243. sys.stdout.write(out)
  244. sys.stdout.write(err)
  245. assert call.excinfo is not None
  246. if not isinstance(call.excinfo.value, unittest.SkipTest):
  247. _enter_pdb(node, call.excinfo, report)
  248. def pytest_internalerror(self, excinfo: ExceptionInfo[BaseException]) -> None:
  249. exc_or_tb = _postmortem_exc_or_tb(excinfo)
  250. post_mortem(exc_or_tb)
  251. class PdbTrace:
  252. @hookimpl(wrapper=True)
  253. def pytest_pyfunc_call(self, pyfuncitem) -> Generator[None, object, object]:
  254. wrap_pytest_function_for_tracing(pyfuncitem)
  255. return (yield)
  256. def wrap_pytest_function_for_tracing(pyfuncitem) -> None:
  257. """Change the Python function object of the given Function item by a
  258. wrapper which actually enters pdb before calling the python function
  259. itself, effectively leaving the user in the pdb prompt in the first
  260. statement of the function."""
  261. _pdb = pytestPDB._init_pdb("runcall")
  262. testfunction = pyfuncitem.obj
  263. # we can't just return `partial(pdb.runcall, testfunction)` because (on
  264. # python < 3.7.4) runcall's first param is `func`, which means we'd get
  265. # an exception if one of the kwargs to testfunction was called `func`.
  266. @functools.wraps(testfunction)
  267. def wrapper(*args, **kwargs) -> None:
  268. func = functools.partial(testfunction, *args, **kwargs)
  269. _pdb.runcall(func)
  270. pyfuncitem.obj = wrapper
  271. def maybe_wrap_pytest_function_for_tracing(pyfuncitem) -> None:
  272. """Wrap the given pytestfunct item for tracing support if --trace was given in
  273. the command line."""
  274. if pyfuncitem.config.getvalue("trace"):
  275. wrap_pytest_function_for_tracing(pyfuncitem)
  276. def _enter_pdb(
  277. node: Node, excinfo: ExceptionInfo[BaseException], rep: BaseReport
  278. ) -> BaseReport:
  279. # XXX we reuse the TerminalReporter's terminalwriter
  280. # because this seems to avoid some encoding related troubles
  281. # for not completely clear reasons.
  282. tw = node.config.pluginmanager.getplugin("terminalreporter")._tw
  283. tw.line()
  284. showcapture = node.config.option.showcapture
  285. for sectionname, content in (
  286. ("stdout", rep.capstdout),
  287. ("stderr", rep.capstderr),
  288. ("log", rep.caplog),
  289. ):
  290. if showcapture in (sectionname, "all") and content:
  291. tw.sep(">", "captured " + sectionname)
  292. if content[-1:] == "\n":
  293. content = content[:-1]
  294. tw.line(content)
  295. tw.sep(">", "traceback")
  296. rep.toterminal(tw)
  297. tw.sep(">", "entering PDB")
  298. tb_or_exc = _postmortem_exc_or_tb(excinfo)
  299. rep._pdbshown = True # type: ignore[attr-defined]
  300. post_mortem(tb_or_exc)
  301. return rep
  302. def _postmortem_exc_or_tb(
  303. excinfo: ExceptionInfo[BaseException],
  304. ) -> types.TracebackType | BaseException:
  305. from doctest import UnexpectedException
  306. get_exc = sys.version_info >= (3, 13)
  307. if isinstance(excinfo.value, UnexpectedException):
  308. # A doctest.UnexpectedException is not useful for post_mortem.
  309. # Use the underlying exception instead:
  310. underlying_exc = excinfo.value
  311. if get_exc:
  312. return underlying_exc.exc_info[1]
  313. return underlying_exc.exc_info[2]
  314. elif isinstance(excinfo.value, ConftestImportFailure):
  315. # A config.ConftestImportFailure is not useful for post_mortem.
  316. # Use the underlying exception instead:
  317. cause = excinfo.value.cause
  318. if get_exc:
  319. return cause
  320. assert cause.__traceback__ is not None
  321. return cause.__traceback__
  322. else:
  323. assert excinfo._excinfo is not None
  324. if get_exc:
  325. return excinfo._excinfo[1]
  326. return excinfo._excinfo[2]
  327. def post_mortem(tb_or_exc: types.TracebackType | BaseException) -> None:
  328. p = pytestPDB._init_pdb("post_mortem")
  329. p.reset()
  330. p.interaction(None, tb_or_exc)
  331. if p.quitting:
  332. outcomes.exit("Quitting debugger")