_pytest.outcomes module

exception classes and constants handling test outcomes as well as functions creating them

exception OutcomeException(msg: Optional[str] = None, pytrace: bool = True)

Bases: BaseException

OutcomeException and its subclass instances indicate and contain info about test and collection outcomes.

exception Skipped(msg: Optional[str] = None, pytrace: bool = True, allow_module_level: bool = False)

Bases: _pytest.outcomes.OutcomeException

exception Failed(msg: Optional[str] = None, pytrace: bool = True)

Bases: _pytest.outcomes.OutcomeException

raised from an explicit call to pytest.fail()

exception Exit(msg: str = 'unknown reason', returncode: Optional[int] = None)

Bases: Exception

raised for immediate program exits (no tracebacks/summaries)

class _WithException(*args, **kwds)

Bases: typing.Generic

Exception: _ET = None

_with_exception(exception_type: _ET) → Callable[[_F], _pytest.outcomes._WithException[_F, _ET]]

exit(msg: str, returncode: Optional[int] = None) → NoReturn

Exit testing process.

Parameters

• msg (str) – message to display upon exit.

• returncode (int) – return code to be used when exiting pytest.

skip(msg: str = '', *, allow_module_level: bool = False) → NoReturn

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. This function can be called in doctests as well.

Parameters

allow_module_level (bool) – 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 pytest.mark.skipif ref marker when possible to declare a test to be skipped under certain conditions like mismatching platforms or dependencies. Similarly, use the # doctest: +SKIP directive (see doctest.SKIP) to skip a doctest statically.

fail(msg: str = '', pytrace: bool = True) → NoReturn

Explicitly fail an executing test with the given message.

Parameters

• msg (str) – the message to show the user as reason for the failure.

• pytrace (bool) – if false the msg represents the full failure information and no python traceback will be reported.

exception XFailed(msg: Optional[str] = None, pytrace: bool = True)

Bases: _pytest.outcomes.Failed

raised from an explicit call to pytest.xfail()

xfail(reason: str = '') → NoReturn

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 pytest.mark.xfail ref marker when possible to declare a test to be xfailed under certain conditions like known bugs or missing features.

importorskip(modname: str, minversion: Optional[str] = None, reason: Optional[str] = None) → Any

Imports and returns the requested module modname, or skip the current test if the module cannot be imported.

Parameters

• modname (str) – the name of the module to import

• minversion (str) – if given, the imported module’s __version__ attribute must be at least this minimal version, otherwise the test is still skipped.

• reason (str) – if given, this reason is shown as the message when the module cannot be imported.

Returns

The imported module. This should be assigned to its canonical name.

Example:

docutils = pytest.importorskip("docutils")