test_ok1/doc/builtin.txt

.. _`pytest helpers`:

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.

.. automodule:: pytest
    :members:

builtin function arguments
-----------------------------------------------------

You can ask for available builtin or project-custom
:ref:`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