| |
| .. _`pytest helpers`: |
| |
| Pytest API and builtin fixtures |
| ================================================ |
| |
| This is a list of ``pytest.*`` API functions and fixtures. |
| |
| For information on plugin hooks and objects, see :ref:`plugins`. |
| |
| For information on the ``pytest.mark`` mechanism, see :ref:`mark`. |
| |
| 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) |
| |
| .. currentmodule:: pytest |
| |
| Invoking pytest interactively |
| --------------------------------------------------- |
| |
| .. autofunction:: main |
| |
| More examples at :ref:`pytest.main-usage` |
| |
| |
| Helpers for assertions about Exceptions/Warnings |
| -------------------------------------------------------- |
| |
| .. autofunction:: raises |
| |
| Examples at :ref:`assertraises`. |
| |
| .. autofunction:: deprecated_call |
| |
| 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 :ref:`skipping`. |
| |
| .. autofunction:: _pytest.runner.fail |
| .. autofunction:: _pytest.runner.skip |
| .. autofunction:: _pytest.runner.importorskip |
| .. autofunction:: _pytest.skipping.xfail |
| .. autofunction:: _pytest.runner.exit |
| |
| fixtures and requests |
| ----------------------------------------------------- |
| |
| To mark a fixture function: |
| |
| .. autofunction:: _pytest.python.fixture |
| |
| Tutorial at :ref:`fixtures`. |
| |
| The ``request`` object that can be used from fixture functions. |
| |
| .. autoclass:: _pytest.python.FixtureRequest() |
| :members: |
| |
| |
| .. _builtinfixtures: |
| .. _builtinfuncargs: |
| |
| Builtin fixtures/function arguments |
| ----------------------------------------- |
| |
| You can ask for available builtin or project-custom |
| :ref:`fixtures <fixtures>` by typing:: |
| |
| $ py.test -q --fixtures |
| cache |
| Return a cache object that can persist state between testing sessions. |
| |
| cache.get(key, default) |
| cache.set(key, value) |
| |
| Keys must be a ``/`` separated value, where the first part is usually the |
| name of your plugin or application to avoid clashes with other cache users. |
| |
| Values can be any object handled by the json stdlib module. |
| 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 ``capfd.readouterr()`` method calls |
| which return a ``(out, err)`` tuple. |
| record_xml_property |
| Fixture that adds extra xml properties to the tag for the calling test. |
| The fixture is callable with (name, value), with value being automatically |
| xml-encoded. |
| 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_factory |
| Return a TempdirFactory instance for the test session. |
| 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. |
| |
| no tests ran in 0.12 seconds |