Skip to content

Commit 5c1c73b

Browse files
[8.2.x] Document exceptions raised by exit, skip, xfail, fail, and importorskip (#12288)
Co-authored-by: Bruno Oliveira <[email protected]>
1 parent a152c2c commit 5c1c73b

File tree

2 files changed

+33
-1
lines changed

2 files changed

+33
-1
lines changed

doc/en/reference/reference.rst

+18-1
Original file line numberDiff line numberDiff line change
@@ -59,11 +59,19 @@ pytest.fail
5959

6060
.. autofunction:: pytest.fail(reason, [pytrace=True, msg=None])
6161

62+
.. class:: pytest.fail.Exception
63+
64+
The exception raised by :func:`pytest.fail`.
65+
6266
pytest.skip
6367
~~~~~~~~~~~
6468

6569
.. autofunction:: pytest.skip(reason, [allow_module_level=False, msg=None])
6670

71+
.. class:: pytest.skip.Exception
72+
73+
The exception raised by :func:`pytest.skip`.
74+
6775
.. _`pytest.importorskip ref`:
6876

6977
pytest.importorskip
@@ -76,11 +84,19 @@ pytest.xfail
7684

7785
.. autofunction:: pytest.xfail
7886

87+
.. class:: pytest.xfail.Exception
88+
89+
The exception raised by :func:`pytest.xfail`.
90+
7991
pytest.exit
8092
~~~~~~~~~~~
8193

8294
.. autofunction:: pytest.exit(reason, [returncode=None, msg=None])
8395

96+
.. class:: pytest.exit.Exception
97+
98+
The exception raised by :func:`pytest.exit`.
99+
84100
pytest.main
85101
~~~~~~~~~~~
86102

@@ -246,9 +262,10 @@ Marks a test function as *expected to fail*.
246262
to specify ``reason`` (see :ref:`condition string <string conditions>`).
247263
:keyword str reason:
248264
Reason why the test function is marked as xfail.
249-
:keyword Type[Exception] raises:
265+
:keyword raises:
250266
Exception class (or tuple of classes) expected to be raised by the test function; other exceptions will fail the test.
251267
Note that subclasses of the classes passed will also result in a match (similar to how the ``except`` statement works).
268+
:type raises: Type[:py:exc:`Exception`]
252269

253270
:keyword bool run:
254271
Whether the test function should actually be executed. If ``False``, the function will always xfail and will

src/_pytest/outcomes.py

+15
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,9 @@ def exit(
114114
115115
:param returncode:
116116
Return code to be used when exiting pytest. None means the same as ``0`` (no error), same as :func:`sys.exit`.
117+
118+
:raises pytest.exit.Exception:
119+
The exception that is raised.
117120
"""
118121
__tracebackhide__ = True
119122
raise Exit(reason, returncode)
@@ -142,6 +145,9 @@ def skip(
142145
143146
Defaults to False.
144147
148+
:raises pytest.skip.Exception:
149+
The exception that is raised.
150+
145151
.. note::
146152
It is better to use the :ref:`pytest.mark.skipif ref` marker when
147153
possible to declare a test to be skipped under certain conditions
@@ -163,6 +169,9 @@ def fail(reason: str = "", pytrace: bool = True) -> NoReturn:
163169
:param pytrace:
164170
If False, msg represents the full failure information and no
165171
python traceback will be reported.
172+
173+
:raises pytest.fail.Exception:
174+
The exception that is raised.
166175
"""
167176
__tracebackhide__ = True
168177
raise Failed(msg=reason, pytrace=pytrace)
@@ -188,6 +197,9 @@ def xfail(reason: str = "") -> NoReturn:
188197
It is better to use the :ref:`pytest.mark.xfail ref` marker when
189198
possible to declare a test to be xfailed under certain conditions
190199
like known bugs or missing features.
200+
201+
:raises pytest.xfail.Exception:
202+
The exception that is raised.
191203
"""
192204
__tracebackhide__ = True
193205
raise XFailed(reason)
@@ -227,6 +239,9 @@ def importorskip(
227239
:returns:
228240
The imported module. This should be assigned to its canonical name.
229241
242+
:raises pytest.skip.Exception:
243+
If the module cannot be imported.
244+
230245
Example::
231246
232247
docutils = pytest.importorskip("docutils")

0 commit comments

Comments
 (0)