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