# Pytest API and builtin fixtures

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

For information on plugin hooks and objects, see Writing plugins.

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

`main`(args=None, plugins=None)

  return exit code, after performing an in-process test run.

  Parameters:

  - args – list of command line arguments.
  - plugins – list of plugin objects to be auto-registered during initialization.

More examples at Calling pytest from Python code

## Helpers for assertions about Exceptions/Warnings

`raises`(expected_exception, *args, **kwargs)

  assert that a code block/function call raises @expected_exception and raise a failure exception otherwise.

  This helper produces a `py.code.ExceptionInfo()` object.

  If using Python 2.5 or above, you may use this function as a context manager:

      >>> with raises(ZeroDivisionError):
      ...    1/0

  Note

  When using `pytest.raises` as a context manager, it’s worthwhile to note that normal context manager rules apply and that the exception raised must be the final line in the scope of the context manager. Lines of code after that, within the scope of the context manager will not be executed. For example:

      >>> with raises(OSError) as err:
              assert 1 == 1  # this will execute as expected
              raise OSError(errno.EEXISTS, 'directory exists')
              assert err.errno == errno.EEXISTS  # this will not execute

  Instead, the following approach must be taken (note the difference in scope):

      >>> with raises(OSError) as err:
              assert 1 == 1  # this will execute as expected
              raise OSError(errno.EEXISTS, 'directory exists')

          assert err.errno == errno.EEXISTS  # this will now execute

  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 to be executed:

      >>> raises(ZeroDivisionError, "f(0)")
      <ExceptionInfo ...>

  Similar to caught exception objects in Python, explicitly clearing local references to returned `py.code.ExceptionInfo` objects can help the Python interpreter speed up its garbage collection.

  Clearing those references breaks a reference cycle (`ExceptionInfo` –> caught exception –> frame stack raising the exception –> current frame stack –> local variables –> `ExceptionInfo`) which makes Python keep all objects referenced from that cycle (including all local variables in the current frame) alive until the next cyclic garbage collection run. See the official Python `try` statement documentation for more detailed information.

Examples at Assertions about expected exceptions.

`deprecated_call`(func, *args, **kwargs)

  assert that calling `func(*args, **kwargs)` triggers a `DeprecationWarning` or `PendingDeprecationWarning`.

  Note: we cannot use WarningsRecorder here because it is still subject to the mechanism that prevents warnings of the same type from being triggered twice for the same module. See #1190.

## 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)

  explicitly 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='')

  skip an executing test with the given message. Note: it’s usually better to use the pytest.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)

  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.

`xfail`(reason='')

  xfail an executing test or setup functions with the given reason.

`exit`(msg)

  exit testing process as if KeyboardInterrupt was triggered.

## fixtures and requests

To mark a fixture function:

`fixture`(scope='function', params=None, autouse=False, ids=None)

  (return a) decorator to mark a fixture factory function.

  This decorator can be used (with or or without parameters) to define a fixture function. The name of the fixture function can later be referenced to cause its invocation ahead of running tests: test modules or classes can use the pytest.mark.usefixtures(fixturename) marker. Test functions can directly use fixture names as input arguments in which case the fixture instance returned from the fixture function will be injected.

  Parameters:

  - scope – the scope for which this fixture is shared, one of “function” (default), “class”, “module”, “session”.
  - params – an optional list of parameters which will cause multiple invocations of the fixture function and all of the tests using it.
  - autouse – if True, the fixture func is activated for all tests that can see it. If False (the default) then an explicit reference is needed to activate the fixture.
  - ids – list of string ids each corresponding to the params so that they are part of the test id. If no ids are provided they will be generated automatically from the params.

Tutorial at pytest fixtures: explicit, modular, scalable.

The `request` object that can be used from fixture functions.

class `FixtureRequest`

  A request for a fixture from a test or fixture function.

  A request object gives access to the requesting test context and has an optional `param` attribute in case the fixture is parametrized indirectly.

  `fixturename` = None

    fixture for which this request is being performed

  `scope` = None

    Scope string, one of “function”, “cls”, “module”, “session”

  `node`

    underlying collection node (depends on current request scope)

  `config`

    the pytest config object associated with this request.

  `function`

    test function object if the request has a per-function scope.

  `cls`

    class (can be None) where the test function was collected.

  `instance`

    instance (can be None) on which test function was collected.

  `module`

    python module object where the test function was collected.

  `fspath`

    the file system path of the test module which collected this test.

  `keywords`

    keywords/markers dictionary for the underlying node.

  `session`

    pytest session object.

  `addfinalizer`(finalizer)

    add finalizer/teardown function to be called after the last test within the requesting test context finished execution.

  `applymarker`(marker)

    Apply a marker to a single test function invocation. This method is useful if you don’t want to have a keyword/marker on all function invocations.

    Parameters: | marker – a `_pytest.mark.MarkDecorator` object created by a call to `pytest.mark.NAME(...)`.

  `raiseerror`(msg)

    raise a FixtureLookupError with the given message.

  `cached_setup`(setup, teardown=None, scope='module', extrakey=None)

    (deprecated) Return a testing resource managed by `setup` & `teardown` calls. `scope` and `extrakey` determine when the `teardown` function will be called so that subsequent calls to `setup` would recreate the resource. With pytest-2.3 you often do not need `cached_setup()` as you can directly declare a scope on a fixture function and register a finalizer through `request.addfinalizer()`.

    Parameters:

    - teardown – function receiving a previously setup resource.
    - setup – a no-argument function creating a resource.
    - scope – a string value out of `function`, `class`, `module` or `session` indicating the caching lifecycle of the resource.
    - extrakey – added to internal caching key of (funcargname, scope).

  `getfuncargvalue`(argname)

    Dynamically retrieve a named fixture function argument.

    As of pytest-2.3, it is easier and usually better to access other fixture values by stating it as an input argument in the fixture function. If you only can decide about using another fixture at test setup time, you may use this function to retrieve it inside a fixture function body.

## Builtin fixtures/function arguments

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