Document exceptions raised by exit, skip, xfail, fail, and importorskip (#12285)
As commented on: https://github.com/pytest-dev/pytest/issues/7469#issuecomment-2094104215
This commit is contained in:
parent
3d09c85df0
commit
84e59af8c8
|
@ -59,11 +59,19 @@ pytest.fail
|
||||||
|
|
||||||
.. autofunction:: pytest.fail(reason, [pytrace=True, msg=None])
|
.. autofunction:: pytest.fail(reason, [pytrace=True, msg=None])
|
||||||
|
|
||||||
|
.. class:: pytest.fail.Exception
|
||||||
|
|
||||||
|
The exception raised by :func:`pytest.fail`.
|
||||||
|
|
||||||
pytest.skip
|
pytest.skip
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
.. autofunction:: pytest.skip(reason, [allow_module_level=False, msg=None])
|
.. 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 ref`:
|
||||||
|
|
||||||
pytest.importorskip
|
pytest.importorskip
|
||||||
|
@ -76,11 +84,19 @@ pytest.xfail
|
||||||
|
|
||||||
.. autofunction:: pytest.xfail
|
.. autofunction:: pytest.xfail
|
||||||
|
|
||||||
|
.. class:: pytest.xfail.Exception
|
||||||
|
|
||||||
|
The exception raised by :func:`pytest.xfail`.
|
||||||
|
|
||||||
pytest.exit
|
pytest.exit
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
.. autofunction:: pytest.exit(reason, [returncode=None, msg=None])
|
.. autofunction:: pytest.exit(reason, [returncode=None, msg=None])
|
||||||
|
|
||||||
|
.. class:: pytest.exit.Exception
|
||||||
|
|
||||||
|
The exception raised by :func:`pytest.exit`.
|
||||||
|
|
||||||
pytest.main
|
pytest.main
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -246,9 +262,10 @@ Marks a test function as *expected to fail*.
|
||||||
to specify ``reason`` (see :ref:`condition string <string conditions>`).
|
to specify ``reason`` (see :ref:`condition string <string conditions>`).
|
||||||
:keyword str reason:
|
:keyword str reason:
|
||||||
Reason why the test function is marked as xfail.
|
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.
|
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).
|
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:
|
:keyword bool run:
|
||||||
Whether the test function should actually be executed. If ``False``, the function will always xfail and will
|
Whether the test function should actually be executed. If ``False``, the function will always xfail and will
|
||||||
|
|
|
@ -114,6 +114,9 @@ def exit(
|
||||||
|
|
||||||
:param returncode:
|
:param returncode:
|
||||||
Return code to be used when exiting pytest. None means the same as ``0`` (no error), same as :func:`sys.exit`.
|
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
|
__tracebackhide__ = True
|
||||||
raise Exit(reason, returncode)
|
raise Exit(reason, returncode)
|
||||||
|
@ -142,6 +145,9 @@ def skip(
|
||||||
|
|
||||||
Defaults to False.
|
Defaults to False.
|
||||||
|
|
||||||
|
:raises pytest.skip.Exception:
|
||||||
|
The exception that is raised.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
It is better to use the :ref:`pytest.mark.skipif ref` marker when
|
It is better to use the :ref:`pytest.mark.skipif ref` marker when
|
||||||
possible to declare a test to be skipped under certain conditions
|
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:
|
:param pytrace:
|
||||||
If False, msg represents the full failure information and no
|
If False, msg represents the full failure information and no
|
||||||
python traceback will be reported.
|
python traceback will be reported.
|
||||||
|
|
||||||
|
:raises pytest.fail.Exception:
|
||||||
|
The exception that is raised.
|
||||||
"""
|
"""
|
||||||
__tracebackhide__ = True
|
__tracebackhide__ = True
|
||||||
raise Failed(msg=reason, pytrace=pytrace)
|
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
|
It is better to use the :ref:`pytest.mark.xfail ref` marker when
|
||||||
possible to declare a test to be xfailed under certain conditions
|
possible to declare a test to be xfailed under certain conditions
|
||||||
like known bugs or missing features.
|
like known bugs or missing features.
|
||||||
|
|
||||||
|
:raises pytest.xfail.Exception:
|
||||||
|
The exception that is raised.
|
||||||
"""
|
"""
|
||||||
__tracebackhide__ = True
|
__tracebackhide__ = True
|
||||||
raise XFailed(reason)
|
raise XFailed(reason)
|
||||||
|
@ -227,6 +239,9 @@ def importorskip(
|
||||||
:returns:
|
:returns:
|
||||||
The imported module. This should be assigned to its canonical name.
|
The imported module. This should be assigned to its canonical name.
|
||||||
|
|
||||||
|
:raises pytest.skip.Exception:
|
||||||
|
If the module cannot be imported.
|
||||||
|
|
||||||
Example::
|
Example::
|
||||||
|
|
||||||
docutils = pytest.importorskip("docutils")
|
docutils = pytest.importorskip("docutils")
|
||||||
|
|
Loading…
Reference in New Issue