diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 39317497e..e46478da0 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -59,11 +59,19 @@ pytest.fail .. autofunction:: pytest.fail(reason, [pytrace=True, msg=None]) +.. class:: pytest.fail.Exception + + The exception raised by :func:`pytest.fail`. + pytest.skip ~~~~~~~~~~~ .. autofunction:: pytest.skip(reason, [allow_module_level=False, msg=None]) +.. class:: pytest.skip.Exception + + The exception raised by :func:`pytest.skip`. + .. _`pytest.importorskip ref`: pytest.importorskip @@ -76,11 +84,19 @@ pytest.xfail .. autofunction:: pytest.xfail +.. class:: pytest.xfail.Exception + + The exception raised by :func:`pytest.xfail`. + pytest.exit ~~~~~~~~~~~ .. autofunction:: pytest.exit(reason, [returncode=None, msg=None]) +.. class:: pytest.exit.Exception + + The exception raised by :func:`pytest.exit`. + pytest.main ~~~~~~~~~~~ @@ -246,9 +262,10 @@ Marks a test function as *expected to fail*. to specify ``reason`` (see :ref:`condition string `). :keyword str reason: Reason why the test function is marked as xfail. - :keyword Type[Exception] raises: + :keyword raises: Exception class (or tuple of classes) expected to be raised by the test function; other exceptions will fail the test. Note that subclasses of the classes passed will also result in a match (similar to how the ``except`` statement works). + :type raises: Type[:py:exc:`Exception`] :keyword bool run: Whether the test function should actually be executed. If ``False``, the function will always xfail and will diff --git a/src/_pytest/outcomes.py b/src/_pytest/outcomes.py index 76d94accd..f953dabe0 100644 --- a/src/_pytest/outcomes.py +++ b/src/_pytest/outcomes.py @@ -114,6 +114,9 @@ def exit( :param returncode: Return code to be used when exiting pytest. None means the same as ``0`` (no error), same as :func:`sys.exit`. + + :raises pytest.exit.Exception: + The exception that is raised. """ __tracebackhide__ = True raise Exit(reason, returncode) @@ -142,6 +145,9 @@ def skip( Defaults to False. + :raises pytest.skip.Exception: + The exception that is raised. + .. note:: It is better to use the :ref:`pytest.mark.skipif ref` marker when possible to declare a test to be skipped under certain conditions @@ -163,6 +169,9 @@ def fail(reason: str = "", pytrace: bool = True) -> NoReturn: :param pytrace: If False, msg represents the full failure information and no python traceback will be reported. + + :raises pytest.fail.Exception: + The exception that is raised. """ __tracebackhide__ = True raise Failed(msg=reason, pytrace=pytrace) @@ -188,6 +197,9 @@ def xfail(reason: str = "") -> NoReturn: It is better to use the :ref:`pytest.mark.xfail ref` marker when possible to declare a test to be xfailed under certain conditions like known bugs or missing features. + + :raises pytest.xfail.Exception: + The exception that is raised. """ __tracebackhide__ = True raise XFailed(reason) @@ -227,6 +239,9 @@ def importorskip( :returns: The imported module. This should be assigned to its canonical name. + :raises pytest.skip.Exception: + If the module cannot be imported. + Example:: docutils = pytest.importorskip("docutils")