Skip to content

Mention explicitly when pytest.skip and pytest.xfail can be called #3922

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nicoddemus merged 1 commit into from
Sep 2, 2018
Merged

Mention explicitly when pytest.skip and pytest.xfail can be called #3922

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 24 additions & 8 deletions src/_pytest/outcomes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,19 @@ def exit(msg):


def skip(msg="", **kwargs):
""" skip an executing test with the given message. Note: it's usually
better to use the pytest.mark.skipif marker to declare a test to be
skipped under certain conditions like mismatching platforms or
dependencies. See the pytest_skipping plugin for details.
"""
Skip an executing test with the given message.

This function should be called only during testing (setup, call or teardown) or
during collection by using the ``allow_module_level`` flag.

:kwarg bool allow_module_level: allows this function to be called at
module level, skipping the rest of the module. Default to False.

.. 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 like mismatching platforms or
dependencies.
"""
__tracebackhide__ = True
allow_module_level = kwargs.pop("allow_module_level", False)
Expand All @@ -87,10 +93,12 @@ def skip(msg="", **kwargs):


def fail(msg="", pytrace=True):
""" explicitly fail a currently-executing test with the given Message.
"""
Explicitly fail an executing test with the given message.

:arg pytrace: if false the msg represents the full failure information
and no python traceback will be reported.
:param str msg: the message to show the user as reason for the failure.
:param bool pytrace: if false the msg represents the full failure information and no
python traceback will be reported.
"""
__tracebackhide__ = True
raise Failed(msg=msg, pytrace=pytrace)
Expand All @@ -104,7 +112,15 @@ class XFailed(fail.Exception):


def xfail(reason=""):
""" xfail an executing test or setup functions with the given reason."""
"""
Imperatively xfail an executing test or setup functions with the given reason.

This function should be called only during testing (setup, call or teardown).

.. note::
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.
"""
__tracebackhide__ = True
raise XFailed(reason)

Expand Down