Installing and Using plugins

This section talks about installing and using third party plugins. For writing your own plugins, please refer to 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. We have a page listing all 3rd party plugins and their status against the latest py.test version and here is a little annotated list for some popular plugins:

  • 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-capturelog: 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 xdist: pytest distributed testing plugin
  • 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-cache: to interactively re-run failing tests and help other plugins to store test run information across invocations.
  • pytest-pep8: a --pep8 option to enable PEP8 compliance checking.
  • oejskit: a plugin to run javascript unittests in life 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.

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.

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 files when they are loaded.

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 it already existing. See Finding out which plugins are active for how to obtain the name of a plugin.

Pytest default plugin reference

You can find the source code for the following plugins in the pytest repository.

_pytest.assertion support for presenting detailed information in failing assertions.
_pytest.capture per-test stdout/stderr capturing mechanism.
_pytest.config command line options, ini-file and processing.
_pytest.doctest discover and run doctests in modules and test files.
_pytest.genscript (deprecated) generate a single-file self-contained version of pytest
_pytest.helpconfig version info, help messages, tracing configuration.
_pytest.junitxml report test results in JUnit-XML format, for use with Hudson and build integration servers.
_pytest.mark generic mechanism for marking and selecting python functions.
_pytest.monkeypatch monkeypatching and mocking functionality.
_pytest.nose run test suites written for nose.
_pytest.pastebin submit failure or test session information to a pastebin service.
_pytest.pdb interactive debugging with PDB, the Python Debugger.
_pytest.pytester (disabled by default) support for testing pytest and pytest plugins.
_pytest.python Python test discovery, setup and run of test functions.
_pytest.recwarn recording warnings during test function execution.
_pytest.resultlog log machine-parseable test session result information in a plain
_pytest.runner basic collect and runtest protocol implementations
_pytest.main core implementation of testing process: init, session, runtest loop.
_pytest.skipping support for skip/xfail functions and markers.
_pytest.terminal terminal reporting of the full testing process.
_pytest.tmpdir support for providing temporary directories to test functions.
_pytest.unittest discovery and running of std-library “unittest” style tests.