Skip to content

Commit

Permalink
doc: fix a few pytest.mark.xfail nits
Browse files Browse the repository at this point in the history
Refs #9027, #10094.
  • Loading branch information
bluetech committed Aug 12, 2023
1 parent 556e075 commit 1827d8d
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 4 deletions.
8 changes: 5 additions & 3 deletions doc/en/reference/reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ pytest.mark.xfail

Marks a test function as *expected to fail*.

.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=False)
.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=xfail_strict)
:type condition: bool or str
:param condition:
Expand All @@ -249,17 +249,19 @@ Marks a test function as *expected to fail*.
:keyword Type[Exception] raises:
Exception subclass (or tuple of subclasses) expected to be raised by the test function; other exceptions will fail the test.
:keyword bool run:
If 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
not be executed (useful if a function is segfaulting).
:keyword bool strict:
* If ``False`` (the default) the function will be shown in the terminal output as ``xfailed`` if it fails
* If ``False`` the function will be shown in the terminal output as ``xfailed`` if it fails
and as ``xpass`` if it passes. In both cases this will not cause the test suite to fail as a whole. This
is particularly useful to mark *flaky* tests (tests that fail at random) to be tackled later.
* If ``True``, the function will be shown in the terminal output as ``xfailed`` if it fails, but if it
unexpectedly passes then it will **fail** the test suite. This is particularly useful to mark functions
that are always failing and there should be a clear indication if they unexpectedly start to pass (for example
a new release of a library fixes a known bug).

Defaults to :confval:`xfail_strict`, which is ``False`` by default.


Custom marks
~~~~~~~~~~~~
Expand Down
4 changes: 3 additions & 1 deletion src/_pytest/mark/structures.py
Original file line number Diff line number Diff line change
Expand Up @@ -461,7 +461,9 @@ def __call__(
*conditions: Union[str, bool],
reason: str = ...,
run: bool = ...,
raises: Union[Type[BaseException], Tuple[Type[BaseException], ...]] = ...,
raises: Union[
None, Type[BaseException], Tuple[Type[BaseException], ...]
] = ...,
strict: bool = ...,
) -> MarkDecorator:
...
Expand Down
3 changes: 3 additions & 0 deletions src/_pytest/outcomes.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,9 @@ def xfail(reason: str = "") -> NoReturn:
This function should be called only during testing (setup, call or teardown).
No other code is executed after using ``xfail()`` (it is implemented
internally by raising an exception).
:param reason:
The message to show the user as reason for the xfail.
Expand Down

0 comments on commit 1827d8d

Please sign in to comment.