
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*.


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.
