quicklinks

home TOC/contents
install changelog
examples customize
issues[bb] contact

Table Of Contents

Previous topic

py.test reference documentation

Next topic

Basic test configuration

Pytest builtin helpers

builtin pytest.* functions and helping objects

You can always use an interactive Python prompt and type:

import pytest
help(pytest)

to get an overview on the globally available helpers.

unit and functional testing with Python.

pytest.main(args=None, plugins=None)

returned exit code integer, after an in-process testing run with the given command line arguments, preloading an optional list of passed in plugin objects.

pytest.fail(msg='', pytrace=True)

explicitely fail an currently-executing test with the given Message. if @pytrace is not True the msg represents the full failure information.

pytest.skip(msg='')

skip an executing test with the given message. Note: it’s usually better to use the py.test.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.

pytest.exit(msg)

exit testing process as if KeyboardInterrupt was triggered.

pytest.importorskip(modname, minversion=None)

return imported module if it has a higher __version__ than the optionally specified ‘minversion’ - otherwise call py.test.skip() with a message detailing the mismatch.

pytest.raises(ExpectedException, *args, **kwargs)

assert that a code block/function call raises @ExpectedException and raise a failure exception otherwise.

If using Python 2.5 or above, you may use this function as a context manager:

>>> with raises(ZeroDivisionError):
...    1/0

Or you can specify a callable by passing a to-be-called lambda:

>>> raises(ZeroDivisionError, lambda: 1/0)
<ExceptionInfo ...>

or you can specify an arbitrary callable with arguments:

>>> def f(x): return 1/x
...
>>> raises(ZeroDivisionError, f, 0)
<ExceptionInfo ...>
>>> raises(ZeroDivisionError, f, x=0)
<ExceptionInfo ...>

A third possibility is to use a string which which will be executed:

>>> raises(ZeroDivisionError, "f(0)")
<ExceptionInfo ...>
pytest.xfail(reason='')

xfail an executing test or setup functions with the given reason.

pytest.deprecated_call(func, *args, **kwargs)

assert that calling func(*args, **kwargs) triggers a DeprecationWarning.

Builtin function arguments

You can ask for available builtin or project-custom function arguments by typing:

$ py.test --funcargs
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.1.3
collected 0 items
pytestconfig
    the pytest config object with access to command line opts.
capsys
    enables capturing of writes to sys.stdout/sys.stderr and makes
    captured output available via ``capsys.readouterr()`` method calls
    which return a ``(out, err)`` tuple.

capfd
    enables capturing of writes to file descriptors 1 and 2 and makes
    captured output available via ``capsys.readouterr()`` method calls
    which return a ``(out, err)`` tuple.

tmpdir
    return a temporary directory path object
    which is unique to each test function invocation,
    created as a sub directory of the base temporary
    directory.  The returned object is a `py.path.local`_
    path object.

monkeypatch
    The returned ``monkeypatch`` funcarg provides these
    helper methods to modify objects, dictionaries or os.environ::

    monkeypatch.setattr(obj, name, value, raising=True)
    monkeypatch.delattr(obj, name, raising=True)
    monkeypatch.setitem(mapping, name, value)
    monkeypatch.delitem(obj, name, raising=True)
    monkeypatch.setenv(name, value, prepend=False)
    monkeypatch.delenv(name, value, raising=True)
    monkeypatch.syspath_prepend(path)

    All modifications will be undone after the requesting
    test function has finished. The ``raising``
    parameter determines if a KeyError or AttributeError
    will be raised if the set/deletion operation has no target.

recwarn
    Return a WarningsRecorder instance that provides these methods:

    * ``pop(category=None)``: return last warning matching the category.
    * ``clear()``: clear list of warnings

    See http://docs.python.org/library/warnings.html for information
    on warning categories.

cov
    A pytest funcarg that provides access to the underlying coverage object.

=============================  in 0.00 seconds =============================