1.. _`external plugins`:
2.. _`extplugins`:
3.. _`using plugins`:
4
5Installing and Using plugins
6============================
7
8This section talks about installing and using third party plugins.
9For writing your own plugins, please refer to :ref:`writing-plugins`.
10
11Installing a third party plugin can be easily done with ``pip``::
12
13    pip install pytest-NAME
14    pip uninstall pytest-NAME
15
16If a plugin is installed, ``pytest`` automatically finds and integrates it,
17there is no need to activate it.
18
19Here is a little annotated list for some popular plugins:
20
21.. _`django`: https://www.djangoproject.com/
22
23* `pytest-django <https://pypi.org/project/pytest-django/>`_: write tests
24  for `django`_ apps, using pytest integration.
25
26* `pytest-twisted <https://pypi.org/project/pytest-twisted/>`_: write tests
27  for `twisted <http://twistedmatrix.com>`_ apps, starting a reactor and
28  processing deferreds from test functions.
29
30* `pytest-cov <https://pypi.org/project/pytest-cov/>`_:
31  coverage reporting, compatible with distributed testing
32
33* `pytest-xdist <https://pypi.org/project/pytest-xdist/>`_:
34  to distribute tests to CPUs and remote hosts, to run in boxed
35  mode which allows to survive segmentation faults, to run in
36  looponfailing mode, automatically re-running failing tests
37  on file changes.
38
39* `pytest-instafail <https://pypi.org/project/pytest-instafail/>`_:
40  to report failures while the test run is happening.
41
42* `pytest-bdd <https://pypi.org/project/pytest-bdd/>`_ and
43  `pytest-konira <https://pypi.org/project/pytest-konira/>`_
44  to write tests using behaviour-driven testing.
45
46* `pytest-timeout <https://pypi.org/project/pytest-timeout/>`_:
47  to timeout tests based on function marks or global definitions.
48
49* `pytest-pep8 <https://pypi.org/project/pytest-pep8/>`_:
50  a ``--pep8`` option to enable PEP8 compliance checking.
51
52* `pytest-flakes <https://pypi.org/project/pytest-flakes/>`_:
53  check source code with pyflakes.
54
55* `oejskit <https://pypi.org/project/oejskit/>`_:
56  a plugin to run javascript unittests in live browsers.
57
58To see a complete list of all plugins with their latest testing
59status against different pytest and Python versions, please visit
60`plugincompat <http://plugincompat.herokuapp.com/>`_.
61
62You may also discover more plugins through a `pytest- pypi.python.org search`_.
63
64.. _`pytest- pypi.python.org search`: https://pypi.org/search/?q=pytest-
65
66
67.. _`available installable plugins`:
68
69Requiring/Loading plugins in a test module or conftest file
70-----------------------------------------------------------
71
72You can require plugins in a test module or a conftest file like this::
73
74    pytest_plugins = "myapp.testsupport.myplugin",
75
76When the test module or conftest plugin is loaded the specified plugins
77will be loaded as well.
78
79    pytest_plugins = "myapp.testsupport.myplugin"
80
81which will import the specified module as a ``pytest`` plugin.
82
83.. note::
84    Requiring plugins using a ``pytest_plugins`` variable in non-root
85    ``conftest.py`` files is deprecated. See
86    :ref:`full explanation <requiring plugins in non-root conftests>`
87    in the Writing plugins section.
88
89.. _`findpluginname`:
90
91Finding out which plugins are active
92------------------------------------
93
94If you want to find out which plugins are active in your
95environment you can type::
96
97    pytest --trace-config
98
99and will get an extended test header which shows activated plugins
100and their names. It will also print local plugins aka
101:ref:`conftest.py <conftest.py plugins>` files when they are loaded.
102
103.. _`cmdunregister`:
104
105Deactivating / unregistering a plugin by name
106---------------------------------------------
107
108You can prevent plugins from loading or unregister them::
109
110    pytest -p no:NAME
111
112This means that any subsequent try to activate/load the named
113plugin will not work.
114
115If you want to unconditionally disable a plugin for a project, you can add
116this option to your ``pytest.ini`` file:
117
118.. code-block:: ini
119
120      [pytest]
121      addopts = -p no:NAME
122
123Alternatively to disable it only in certain environments (for example in a
124CI server), you can set ``PYTEST_ADDOPTS`` environment variable to
125``-p no:name``.
126
127See :ref:`findpluginname` for how to obtain the name of a plugin.
128
129.. _`builtin plugins`:
130