Table Of Contents

Previous topic

py.test reference documentation

Next topic

basic test configuration

This Page

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 available globally available helpers.

unit and functional testing with Python.

see http://pytest.org for documentation and details

  1. Holger Krekel and others, 2004-2010
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='')

explicitely fail an currently-executing test with the given Message.

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 an exception.

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
pytestconfig
    the pytest config object with access to command line opts.
capsys
    captures writes to sys.stdout/sys.stderr and makes
    them available successively via a ``capsys.readouterr()`` method
    which returns a ``(out, err)`` tuple of captured snapshot strings.

capfd
    captures writes to file descriptors 1 and 2 and makes
    snapshotted ``(out, err)`` string tuples available
    via the ``capsys.readouterr()`` method.  If the underlying
    platform does not have ``os.dup`` (e.g. Jython) tests using
    this funcarg will automatically skip.

tmpdir
    return a temporary directory path object
    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 when the requesting
    test function finished its execution.  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