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

Invoking pytest interactively

main(args=None, plugins=None)[source]

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

  • 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)[source]

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

This helper produces a ExceptionInfo() object (see below).

If using Python 2.5 or above, 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


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 str(exc_info.value) == "value must be <= 10"  # 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 str(exc_info.value) == "value must be <= 10"

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 ...>
class ExceptionInfo(tup=None, exprinfo=None)[source]

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)


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)


return True if the exception is an instance of exc

getrepr(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False)[source]

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


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)[source]

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

This function can be used as a context manager:

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

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

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.

Comparing floating point numbers

class approx(expected, rel=None, abs=None)[source]

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

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

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)

The same syntax also works on sequences of numbers:

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

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. Infinite numbers are another special case. They are only considered equal to themselves, regardless of the relative tolerance. Both the relative and absolute tolerances can be changed by passing arguments to the approx constructor:

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

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)
>>> 1 + 1e-8 == approx(1, abs=1e-12)
>>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)

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.

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)[source]

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 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)[source]

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 an executing test or setup functions with the given reason.


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)[source]

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

  • 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[source]

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”


underlying collection node (depends on current request scope)


the pytest config object associated with this request.


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


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


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


python module object where the test function was collected.


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


keywords/markers dictionary for the underlying node.


pytest session object.


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


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(...).

raise a FixtureLookupError with the given message.

cached_setup(setup, teardown=None, scope='module', extrakey=None)[source]

(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().

  • 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).

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.


Deprecated, use getfixturevalue.

Builtin fixtures/function arguments

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

$ pytest -q --fixtures
    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.
    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.
    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.
    Inject names into the doctest namespace.
    the pytest config object with access to command line opts.
    Add extra xml properties to the tag for the calling test.
    The fixture is callable with ``(name, value)``, with value being automatically
    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)

    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.
    Return a WarningsRecorder instance that provides these methods:

    * ``pop(category=None)``: return last warning matching the category.
    * ``clear()``: clear list of warnings

    See for information
    on warning categories.
    Return a TempdirFactory instance for the test session.
    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