# 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 `ExceptionInfo()` object (see below).

  You may use this function as a context manager:

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

  Changed in version 2.10.

  In the context manager form you may use the keyword argument `message` to specify a custom failure message:

      >>> with raises(ZeroDivisionError, message="Expecting ZeroDivisionError"):
      ...    pass
      Traceback (most recent call last):
        ...
      Failed: Expecting ZeroDivisionError

  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:

      >>> value = 15
      >>> with raises(ValueError) as exc_info:
      ...     if value > 10:
      ...         raise ValueError("value must be <= 10")
      ...     assert exc_info.type == ValueError  # this will not execute

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

      >>> with raises(ValueError) as exc_info:
      ...     if value > 10:
      ...         raise ValueError("value must be <= 10")
      ...
      >>> assert exc_info.type == ValueError

  Since version `3.1` you can use the keyword argument `match` to assert that the exception matches a text or regex:

      >>> with raises(ValueError, match='must be 0 or None'):
      ...     raise ValueError("value must be 0 or None")

      >>> with raises(ValueError, match=r'must be \d+$'):
      ...     raise ValueError("value must be 42")

  Legacy forms

  The forms below are fully supported but are discouraged for new code because the context manager form is regarded as more readable and less error-prone.

  It is possible to 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 ...>

  It is also possible to pass a string to be evaluated at runtime:

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

  The string will be evaluated using the same `locals()` and `globals()` at the moment of the `raises` call.

  class `ExceptionInfo`(tup=None, exprinfo=None)

    wraps sys.exc_info() objects and offers help for navigating the traceback.

    `type` = None

      the exception class

    `value` = None

      the exception instance

    `tb` = None

      the exception raw traceback

    `typename` = None

      the exception type name

    `traceback` = None

      the exception traceback (_pytest._code.Traceback instance)

    `exconly`(tryshort=False)

      return the exception as a string

      when 'tryshort' resolves to True, and the exception is a _pytest._code._AssertionError, only the actual exception part of the exception representation is returned (so 'AssertionError: ' is removed from the beginning)

    `errisinstance`(exc)

      return True if the exception is an instance of exc

    `getrepr`(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False)

      return str()able representation of this exception info. showlocals: show locals per traceback entry style: long|short|no|native traceback style tbfilter: hide entries (where __tracebackhide__ is true)

      in case of style==native, tbfilter and showlocals is ignored.

    `match`(regexp)

      Match the regular expression 'regexp' on the string representation of the exception. If it matches then True is returned (so that it is possible to write 'assert excinfo.match()'). If it doesn't match an AssertionError is raised.

  Note

  Similar to caught exception objects in Python, explicitly clearing local references to returned `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=None, *args, **kwargs)

  context manager that can be used to ensure a block of code triggers a `DeprecationWarning` or `PendingDeprecationWarning`:

      >>> import warnings
      >>> def api_call_v2():
      ...     warnings.warn('use v3 of this api', DeprecationWarning)
      ...     return 200

      >>> with deprecated_call():
      ...    assert api_call_v2() == 200

  `deprecated_call` can also be used by passing a function and `*args` and `*kwargs`, in which case it will ensure calling `func(*args, **kwargs)` produces one of the warnings types above.

## Comparing floating point numbers

`approx`(expected, rel=None, abs=None, nan_ok=False)

  Assert that two numbers (or two sets of numbers) are equal to each other within some tolerance.

  Due to the intricacies of floating-point arithmetic, numbers that we would intuitively expect to be equal are not always so:

      >>> 0.1 + 0.2 == 0.3
      False

  This problem is commonly encountered when writing tests, e.g. when making sure that floating-point values are what you expect them to be. One way to deal with this problem is to assert that two floating-point numbers are equal to within some appropriate tolerance:

      >>> abs((0.1 + 0.2) - 0.3) < 1e-6
      True

  However, comparisons like this are tedious to write and difficult to understand. Furthermore, absolute comparisons like the one above are usually discouraged because there's no tolerance that works well for all situations. `1e-6` is good for numbers around `1`, but too small for very big numbers and too big for very small ones. It's better to express the tolerance as a fraction of the expected value, but relative comparisons like that are even more difficult to write correctly and concisely.

  The `approx` class performs floating-point comparisons using a syntax that's as intuitive as possible:

      >>> from pytest import approx
      >>> 0.1 + 0.2 == approx(0.3)
      True

  The same syntax also works for sequences of numbers:

      >>> (0.1 + 0.2, 0.2 + 0.4) == approx((0.3, 0.6))
      True

  Dictionary values:

      >>> {'a': 0.1 + 0.2, 'b': 0.2 + 0.4} == approx({'a': 0.3, 'b': 0.6})
      True

  And `numpy` arrays:

      >>> import numpy as np
      >>> np.array([0.1, 0.2]) + np.array([0.2, 0.4]) == approx(np.array([0.3, 0.6]))
      True

  By default, `approx` considers numbers within a relative tolerance of `1e-6` (i.e. one part in a million) of its expected value to be equal. This treatment would lead to surprising results if the expected value was `0.0`, because nothing but `0.0` itself is relatively close to `0.0`. To handle this case less surprisingly, `approx` also considers numbers within an absolute tolerance of `1e-12` of its expected value to be equal. Infinity and NaN are special cases. Infinity is only considered equal to itself, regardless of the relative tolerance. NaN is not considered equal to anything by default, but you can make it be equal to itself by setting the `nan_ok` argument to True. (This is meant to facilitate comparing arrays that use NaN to mean "no data".)

  Both the relative and absolute tolerances can be changed by passing arguments to the `approx` constructor:

      >>> 1.0001 == approx(1)
      False
      >>> 1.0001 == approx(1, rel=1e-3)
      True
      >>> 1.0001 == approx(1, abs=1e-3)
      True

  If you specify `abs` but not `rel`, the comparison will not consider the relative tolerance at all. In other words, two numbers that are within the default relative tolerance of `1e-6` will still be considered unequal if they exceed the specified absolute tolerance. If you specify both `abs` and `rel`, the numbers will be considered equal if either tolerance is met:

      >>> 1 + 1e-8 == approx(1)
      True
      >>> 1 + 1e-8 == approx(1, abs=1e-12)
      False
      >>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)
      True

  If you're thinking about using `approx`, then you might want to know how it compares to other good ways of comparing floating-point numbers. All of these algorithms are based on relative and absolute tolerances and should agree for the most part, but they do have meaningful differences:

  - `math.isclose(a, b, rel_tol=1e-9, abs_tol=0.0)`: True if the relative tolerance is met w.r.t. either `a` or `b` or if the absolute tolerance is met. Because the relative tolerance is calculated w.r.t. both `a` and `b`, this test is symmetric (i.e. neither `a` nor `b` is a "reference value"). You have to specify an absolute tolerance if you want to compare to `0.0` because there is no tolerance by default. Only available in python>=3.5. More information...
  - `numpy.isclose(a, b, rtol=1e-5, atol=1e-8)`: True if the difference between `a` and `b` is less that the sum of the relative tolerance w.r.t. `b` and the absolute tolerance. Because the relative tolerance is only calculated w.r.t. `b`, this test is asymmetric and you can think of `b` as the reference value. Support for comparing sequences is provided by `numpy.allclose`. More information...
  - `unittest.TestCase.assertAlmostEqual(a, b)`: True if `a` and `b` are within an absolute tolerance of `1e-7`. No relative tolerance is considered and the absolute tolerance cannot be changed, so this function is not appropriate for very large or very small numbers. Also, it's only available in subclasses of `unittest.TestCase` and it's ugly because it doesn't follow PEP8. More information...
  - `a == pytest.approx(b, rel=1e-6, abs=1e-12)`: True if the relative tolerance is met w.r.t. `b` or if the absolute tolerance is met. Because the relative tolerance is only calculated w.r.t. `b`, this test is asymmetric and you can think of `b` as the reference value. In the special case that you explicitly specify an absolute tolerance but not a relative tolerance, only the absolute tolerance is considered.

  Warning

  Changed in version 3.2.

  In order to avoid inconsistent behavior, `TypeError` is raised for `>`, `>=`, `<` and `<=` comparisons. The example below illustrates the problem:

      assert approx(0.1) > 0.1 + 1e-10  # calls approx(0.1).__gt__(0.1 + 1e-10)
      assert 0.1 + 1e-10 > approx(0.1)  # calls approx(0.1).__lt__(0.1 + 1e-10)

  In the second example one expects `approx(0.1).__le__(0.1 + 1e-10)` to be called. But instead, `approx(0.1).__lt__(0.1 + 1e-10)` is used to comparison. This is because the call hierarchy of rich comparisons follows a fixed behavior. More information...

## 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 cannot 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='', **kwargs)

  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.

  Parameters: | allow_module_level (bool) -- allows this function to be called at module level, skipping the rest of the module. Default to False.

`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, name=None)

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

  This decorator can be used (with 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" or "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.
  - name -- the name of the fixture. This defaults to the name of the decorated function. If a fixture is used in the same module in which it is defined, the function name of the fixture will be shadowed by the function arg that requests the fixture; one way to resolve this is to name the decorated function `fixture_<fixturename>` and then use `@pytest.fixture(name='<fixturename>')`.

  Fixtures can optionally provide their values to test functions using a `yield` statement, instead of `return`. In this case, the code block after the `yield` statement is executed as teardown code regardless of the test outcome. A fixture function must yield exactly once.

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", "class", "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).

  `getfixturevalue`(argname)

    Dynamically run a named fixture function.

    Declaring fixtures via function argument is recommended where possible. But if you can only decide whether to use another fixture at test setup time, you may use this function to retrieve it inside a fixture or test function body.

  `getfuncargvalue`(argname)

    Deprecated, use getfixturevalue.

## Builtin fixtures/function arguments

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

    $ pytest -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
        Enable capturing of writes to sys.stdout/sys.stderr and make
        captured output available via ``capsys.readouterr()`` method calls
        which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``text``
        objects.
    capsysbinary
        Enable capturing of writes to sys.stdout/sys.stderr and make
        captured output available via ``capsys.readouterr()`` method calls
        which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``bytes``
        objects.
    capfd
        Enable capturing of writes to file descriptors 1 and 2 and make
        captured output available via ``capfd.readouterr()`` method calls
        which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``text``
        objects.
    capfdbinary
        Enable capturing of write to file descriptors 1 and 2 and make
        captured output available via ``capfdbinary.readouterr`` method calls
        which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be
        ``bytes`` objects.
    doctest_namespace
        Inject names into the doctest namespace.
    pytestconfig
        the pytest config object with access to command line opts.
    record_xml_property
        Add extra xml properties to the tag for the calling test.
        The fixture is callable with ``(name, value)``, with value being automatically
        xml-encoded.
    caplog
        Access and control log capturing.

        Captured logs are available through the following methods::

        * caplog.text()          -> string containing formatted log output
        * caplog.records()       -> list of logging.LogRecord instances
        * caplog.record_tuples() -> list of (logger_name, level, message) tuples
    monkeypatch
        The returned ``monkeypatch`` fixture 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 or fixture has finished. 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

        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