outcomes.py 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308
  1. """Exception classes and constants handling test outcomes as well as
  2. functions creating them."""
  3. from __future__ import annotations
  4. import sys
  5. from typing import Any
  6. from typing import ClassVar
  7. from typing import NoReturn
  8. from .warning_types import PytestDeprecationWarning
  9. class OutcomeException(BaseException):
  10. """OutcomeException and its subclass instances indicate and contain info
  11. about test and collection outcomes."""
  12. def __init__(self, msg: str | None = None, pytrace: bool = True) -> None:
  13. if msg is not None and not isinstance(msg, str):
  14. error_msg = ( # type: ignore[unreachable]
  15. "{} expected string as 'msg' parameter, got '{}' instead.\n"
  16. "Perhaps you meant to use a mark?"
  17. )
  18. raise TypeError(error_msg.format(type(self).__name__, type(msg).__name__))
  19. super().__init__(msg)
  20. self.msg = msg
  21. self.pytrace = pytrace
  22. def __repr__(self) -> str:
  23. if self.msg is not None:
  24. return self.msg
  25. return f"<{self.__class__.__name__} instance>"
  26. __str__ = __repr__
  27. TEST_OUTCOME = (OutcomeException, Exception)
  28. class Skipped(OutcomeException):
  29. # XXX hackish: on 3k we fake to live in the builtins
  30. # in order to have Skipped exception printing shorter/nicer
  31. __module__ = "builtins"
  32. def __init__(
  33. self,
  34. msg: str | None = None,
  35. pytrace: bool = True,
  36. allow_module_level: bool = False,
  37. *,
  38. _use_item_location: bool = False,
  39. ) -> None:
  40. super().__init__(msg=msg, pytrace=pytrace)
  41. self.allow_module_level = allow_module_level
  42. # If true, the skip location is reported as the item's location,
  43. # instead of the place that raises the exception/calls skip().
  44. self._use_item_location = _use_item_location
  45. class Failed(OutcomeException):
  46. """Raised from an explicit call to pytest.fail()."""
  47. __module__ = "builtins"
  48. class Exit(Exception):
  49. """Raised for immediate program exits (no tracebacks/summaries)."""
  50. def __init__(
  51. self, msg: str = "unknown reason", returncode: int | None = None
  52. ) -> None:
  53. self.msg = msg
  54. self.returncode = returncode
  55. super().__init__(msg)
  56. class XFailed(Failed):
  57. """Raised from an explicit call to pytest.xfail()."""
  58. class _Exit:
  59. """Exit testing process.
  60. :param reason:
  61. The message to show as the reason for exiting pytest. reason has a default value
  62. only because `msg` is deprecated.
  63. :param returncode:
  64. Return code to be used when exiting pytest. None means the same as ``0`` (no error),
  65. same as :func:`sys.exit`.
  66. :raises pytest.exit.Exception:
  67. The exception that is raised.
  68. """
  69. Exception: ClassVar[type[Exit]] = Exit
  70. def __call__(self, reason: str = "", returncode: int | None = None) -> NoReturn:
  71. __tracebackhide__ = True
  72. raise Exit(msg=reason, returncode=returncode)
  73. exit: _Exit = _Exit()
  74. class _Skip:
  75. """Skip an executing test with the given message.
  76. This function should be called only during testing (setup, call or teardown) or
  77. during collection by using the ``allow_module_level`` flag. This function can
  78. be called in doctests as well.
  79. :param reason:
  80. The message to show the user as reason for the skip.
  81. :param allow_module_level:
  82. Allows this function to be called at module level.
  83. Raising the skip exception at module level will stop
  84. the execution of the module and prevent the collection of all tests in the module,
  85. even those defined before the `skip` call.
  86. Defaults to False.
  87. :raises pytest.skip.Exception:
  88. The exception that is raised.
  89. .. note::
  90. It is better to use the :ref:`pytest.mark.skipif ref` marker when
  91. possible to declare a test to be skipped under certain conditions
  92. like mismatching platforms or dependencies.
  93. Similarly, use the ``# doctest: +SKIP`` directive (see :py:data:`doctest.SKIP`)
  94. to skip a doctest statically.
  95. """
  96. Exception: ClassVar[type[Skipped]] = Skipped
  97. def __call__(self, reason: str = "", allow_module_level: bool = False) -> NoReturn:
  98. __tracebackhide__ = True
  99. raise Skipped(msg=reason, allow_module_level=allow_module_level)
  100. skip: _Skip = _Skip()
  101. class _Fail:
  102. """Explicitly fail an executing test with the given message.
  103. :param reason:
  104. The message to show the user as reason for the failure.
  105. :param pytrace:
  106. If False, msg represents the full failure information and no
  107. python traceback will be reported.
  108. :raises pytest.fail.Exception:
  109. The exception that is raised.
  110. """
  111. Exception: ClassVar[type[Failed]] = Failed
  112. def __call__(self, reason: str = "", pytrace: bool = True) -> NoReturn:
  113. __tracebackhide__ = True
  114. raise Failed(msg=reason, pytrace=pytrace)
  115. fail: _Fail = _Fail()
  116. class _XFail:
  117. """Imperatively xfail an executing test or setup function with the given reason.
  118. This function should be called only during testing (setup, call or teardown).
  119. No other code is executed after using ``xfail()`` (it is implemented
  120. internally by raising an exception).
  121. :param reason:
  122. The message to show the user as reason for the xfail.
  123. .. note::
  124. It is better to use the :ref:`pytest.mark.xfail ref` marker when
  125. possible to declare a test to be xfailed under certain conditions
  126. like known bugs or missing features.
  127. :raises pytest.xfail.Exception:
  128. The exception that is raised.
  129. """
  130. Exception: ClassVar[type[XFailed]] = XFailed
  131. def __call__(self, reason: str = "") -> NoReturn:
  132. __tracebackhide__ = True
  133. raise XFailed(msg=reason)
  134. xfail: _XFail = _XFail()
  135. def importorskip(
  136. modname: str,
  137. minversion: str | None = None,
  138. reason: str | None = None,
  139. *,
  140. exc_type: type[ImportError] | None = None,
  141. ) -> Any:
  142. """Import and return the requested module ``modname``, or skip the
  143. current test if the module cannot be imported.
  144. :param modname:
  145. The name of the module to import.
  146. :param minversion:
  147. If given, the imported module's ``__version__`` attribute must be at
  148. least this minimal version, otherwise the test is still skipped.
  149. :param reason:
  150. If given, this reason is shown as the message when the module cannot
  151. be imported.
  152. :param exc_type:
  153. The exception that should be captured in order to skip modules.
  154. Must be :py:class:`ImportError` or a subclass.
  155. If the module can be imported but raises :class:`ImportError`, pytest will
  156. issue a warning to the user, as often users expect the module not to be
  157. found (which would raise :class:`ModuleNotFoundError` instead).
  158. This warning can be suppressed by passing ``exc_type=ImportError`` explicitly.
  159. See :ref:`import-or-skip-import-error` for details.
  160. :returns:
  161. The imported module. This should be assigned to its canonical name.
  162. :raises pytest.skip.Exception:
  163. If the module cannot be imported.
  164. Example::
  165. docutils = pytest.importorskip("docutils")
  166. .. versionadded:: 8.2
  167. The ``exc_type`` parameter.
  168. """
  169. import warnings
  170. __tracebackhide__ = True
  171. compile(modname, "", "eval") # to catch syntaxerrors
  172. # Until pytest 9.1, we will warn the user if we catch ImportError (instead of ModuleNotFoundError),
  173. # as this might be hiding an installation/environment problem, which is not usually what is intended
  174. # when using importorskip() (#11523).
  175. # In 9.1, to keep the function signature compatible, we just change the code below to:
  176. # 1. Use `exc_type = ModuleNotFoundError` if `exc_type` is not given.
  177. # 2. Remove `warn_on_import` and the warning handling.
  178. if exc_type is None:
  179. exc_type = ImportError
  180. warn_on_import_error = True
  181. else:
  182. warn_on_import_error = False
  183. skipped: Skipped | None = None
  184. warning: Warning | None = None
  185. with warnings.catch_warnings():
  186. # Make sure to ignore ImportWarnings that might happen because
  187. # of existing directories with the same name we're trying to
  188. # import but without a __init__.py file.
  189. warnings.simplefilter("ignore")
  190. try:
  191. __import__(modname)
  192. except exc_type as exc:
  193. # Do not raise or issue warnings inside the catch_warnings() block.
  194. if reason is None:
  195. reason = f"could not import {modname!r}: {exc}"
  196. skipped = Skipped(reason, allow_module_level=True)
  197. if warn_on_import_error and not isinstance(exc, ModuleNotFoundError):
  198. lines = [
  199. "",
  200. f"Module '{modname}' was found, but when imported by pytest it raised:",
  201. f" {exc!r}",
  202. "In pytest 9.1 this warning will become an error by default.",
  203. "You can fix the underlying problem, or alternatively overwrite this behavior and silence this "
  204. "warning by passing exc_type=ImportError explicitly.",
  205. "See https://docs.pytest.org/en/stable/deprecations.html#pytest-importorskip-default-behavior-regarding-importerror",
  206. ]
  207. warning = PytestDeprecationWarning("\n".join(lines))
  208. if warning:
  209. warnings.warn(warning, stacklevel=2)
  210. if skipped:
  211. raise skipped
  212. mod = sys.modules[modname]
  213. if minversion is None:
  214. return mod
  215. verattr = getattr(mod, "__version__", None)
  216. if minversion is not None:
  217. # Imported lazily to improve start-up time.
  218. from packaging.version import Version
  219. if verattr is None or Version(verattr) < Version(minversion):
  220. raise Skipped(
  221. f"module {modname!r} has __version__ {verattr!r}, required is: {minversion!r}",
  222. allow_module_level=True,
  223. )
  224. return mod