Pytest API and builtin fixtures

This is a list of pytest.* API functions and fixtures.

For information on plugin hooks and objects, see Working with plugins and conftest files.

For information on the pytest.mark mechanism, see Marking test functions with attributes.

For the below objects, you can also interactively ask for help, e.g. by typing on the Python interactive prompt something like:

import pytest
help(pytest)

Invoking pytest interactively

More examples at Calling pytest from Python code

Helpers for assertions about Exceptions/Warnings

Examples at Assertions about expected exceptions.

Raising a specific test outcome

You can use the following functions in your test, fixture or setup functions to force a certain test outcome. Note that most often you can rather use declarative marks, see Skip and xfail: dealing with tests that can not succeed.

fail(msg='', pytrace=True)[source]

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

Parameters:pytrace – if false the msg represents the full failure information and no python traceback will be reported.
skip(msg='')[source]

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.

importorskip(modname, minversion=None)[source]

return imported module if it has at least “minversion” as its __version__ attribute. If no minversion is specified the a skip is only triggered if the module can not be imported. Note that version comparison only works with simple version strings like “1.2.3” but not “1.2.3.dev1” or others.

exit(msg)[source]

exit testing process as if KeyboardInterrupt was triggered.

fixtures and requests

To mark a fixture function:

Tutorial at pytest fixtures: explicit, modular, scalable.

The request object that can be used from fixture functions.

Builtin fixtures/function arguments

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

$ py.test -q --fixtures
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.

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)
    monkeypatch.chdir(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.

pytestconfig
    the pytest config object with access to command line opts.
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.

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.


 in 0.00 seconds