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)[source]¶ 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)[source]¶ 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
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 Pythontry
statement documentation for more detailed information.
Examples at Assertions about expected exceptions.
Comparing floating point numbers¶
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.
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:
$ 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.
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.
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.
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