blob: e9b3f460cc46a26995ae4fdb5f7bb085c3be2f83 [file] [log] [blame]
.. _`external plugins`:
.. _`extplugins`:
.. _`using plugins`:
Installing and Using plugins
This section talks about installing and using third party plugins.
For writing your own plugins, please refer to :ref:`writing-plugins`.
Installing a third party plugin can be easily done with ``pip``::
pip install pytest-NAME
pip uninstall pytest-NAME
If a plugin is installed, ``pytest`` automatically finds and integrates it,
there is no need to activate it.
Here is a little annotated list for some popular plugins:
.. _`django`:
* `pytest-django <>`_: write tests
for `django`_ apps, using pytest integration.
* `pytest-twisted <>`_: write tests
for `twisted <>`_ apps, starting a reactor and
processing deferreds from test functions.
* `pytest-catchlog <>`_:
to capture and assert about messages from the logging module
* `pytest-cov <>`_:
coverage reporting, compatible with distributed testing
* `pytest-xdist <>`_:
to distribute tests to CPUs and remote hosts, to run in boxed
mode which allows to survive segmentation faults, to run in
looponfailing mode, automatically re-running failing tests
on file changes, see also :ref:`xdist`
* `pytest-instafail <>`_:
to report failures while the test run is happening.
* `pytest-bdd <>`_ and
`pytest-konira <>`_
to write tests using behaviour-driven testing.
* `pytest-timeout <>`_:
to timeout tests based on function marks or global definitions.
* `pytest-pep8 <>`_:
a ``--pep8`` option to enable PEP8 compliance checking.
* `pytest-flakes <>`_:
check source code with pyflakes.
* `oejskit <>`_:
a plugin to run javascript unittests in live browsers.
To see a complete list of all plugins with their latest testing
status against different py.test and Python versions, please visit
`plugincompat <>`_.
You may also discover more plugins through a `pytest- search`_.
.. _`available installable plugins`:
.. _`pytest- search`:
Requiring/Loading plugins in a test module or conftest file
You can require plugins in a test module or a conftest file like this::
pytest_plugins = "myapp.testsupport.myplugin",
When the test module or conftest plugin is loaded the specified plugins
will be loaded as well.
pytest_plugins = "myapp.testsupport.myplugin"
which will import the specified module as a ``pytest`` plugin.
.. _`findpluginname`:
Finding out which plugins are active
If you want to find out which plugins are active in your
environment you can type::
py.test --traceconfig
and will get an extended test header which shows activated plugins
and their names. It will also print local plugins aka
:ref:` <conftest>` files when they are loaded.
.. _`cmdunregister`:
Deactivating / unregistering a plugin by name
You can prevent plugins from loading or unregister them::
py.test -p no:NAME
This means that any subsequent try to activate/load the named
plugin will not work.
If you want to unconditionally disable a plugin for a project, you can add
this option to your ``pytest.ini`` file:
.. code-block:: ini
addopts = -p no:NAME
Alternatively to disable it only in certain environments (for example in a
CI server), you can set ``PYTEST_ADDOPTS`` environment variable to
``-p no:name``.
See :ref:`findpluginname` for how to obtain the name of a plugin.
.. _`builtin plugins`:
Pytest default plugin reference
You can find the source code for the following plugins
in the `pytest repository <>`_.
.. autosummary::