==========================
py.test plugins 
==========================

Much of py.test's functionality is implemented as a plugin. 

Included plugins
================

You can find the source code of all default plugins in 
http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/

plugins that add reporting asepcts
-----------------------------------

pytest_terminal: default reporter for writing info to terminals 

pytest_resultlog: log test results in machine-readable form to a file 

plugins for adding new test types 
-----------------------------------

pytest_unittest: run traditional unittest TestCase instances

pytest_doctest: run doctests in python modules or .txt files

pytest_restdoc: provide RestructuredText syntax and link checking

plugins for python test functions
-----------------------------------

pytest_xfail: provides "expected to fail" test marker 

pytest_tmpdir: provide temporary directories to test functions 

pytest_plugintester: generic plugin apichecks, support for functional plugin tests 

Loading plugins and specifying dependencies 
============================================

py.test loads and configures plugins at tool startup:

* by reading the ``PYTEST_PLUGINS`` environment variable 
  and importing the comma-separated list of plugin names. 

* by pre-scanning the command line for the ``-p name`` option
  and loading the specified plugin *before actual command line parsing*. 

* by loading all plugins specified via a ``pytest_plugins``
  variable in ``conftest.py`` files or test modules. 

Specifying a plugin in a test module or ``conftest.py`` will
only lead to activitation when ``py.test`` actually sees the
directory and the file during the collection process.  This is
already after command line parsing and there is no try to do 
a "pre-scan of all subdirs" as this would mean a potentially
very large delay.  As long as you don't add command line 
options this detail does not need to worry you. 


ensure a plugin is loaded 
-----------------------------------

If you create a ``conftest.py`` file with the following content:: 

    pytest_plugins = "pytest_myextension",

then all tests in and below that directory will consult the hooks
defined in the imported ``pytest_myextension``.  A plugin 
may specify its dependencies via another ``pytest_plugins`` 
definition.