test_ok2/doc/test/plugins.txt

==========================
hooks and plugins 
==========================

py.test implements much of its functionality by calling **hooks**.  
A hook is a function with a ``pytest_`` prefixed name.  Hook functions
are usually defined in plugins.  A plugin is a regular python module or 
package that makes hook functions available. 

When loading a plugin module (which needs to have a ``pytest_`` prefix as well) 
py.test performs strict checking on the function signature.  Function 
and argument names need to match exactly the `original definition of the hook`_.
This allows for early mismatch reporting and minimizes version incompatibilites. 

.. _`original definition of the hook`: http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/api.py

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 by the ``pytest_plugins``
  variable in a ``conftest.py`` file 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 happens 
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. 

A plugin module may specify its dependencies via 
another ``pytest_plugins`` definition. 

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

You can find the source code of all default plugins in 

    http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/

Additionally you can check out some more contributed plugins here

    http://bitbucket.org/hpk42/py-trunk/src/tip/contrib/


Overview on available hooks 
====================================

"runtest" hooks 
-------------------

Each test item is usually executed by calling the following three hooks::

    pytest_runtest_setup(item) 
    pytest_runtest_call(item) 
    pytest_runtest_teardown(item) 

For each of the three invocations a `call object`_ encapsulates
information about the outcome of the call and is subsequently used 
to make a report object:: 

    report = hook.pytest_runtest_makereport(item, call)

For example, the `pytest_pdb plugin`_ uses this hook to activate
interactive debugging on failures when ``--pdb`` is specified on the
command line. 

Usually three reports will be generated for a single test item.  However, 
if the ``pytest_runtest_setup`` fails no call or teardown hooks 
will be called and only one report will be created. 

Each of the up to three reports is eventually fed to the logreport hook::

    pytest_runtest_logreport(report) 

A ``report`` object contains status and reporting information:: 

    report.longrepr = string/lines/object to print 
    report.when = "setup", "call" or "teardown" 
    report.shortrepr = letter for progress-report 
    report.passed = True or False
    report.failed = True or False
    report.skipped = True or False

The `pytest_terminal plugin`_ uses this hook to print information
about a test run. 
    
The protocol described here is implemented via this hook::
 
    pytest_runtest_protocol(item) -> True 

.. _`call object`: 

The call object contains information about a performed call::

    call.excinfo = ExceptionInfo object or None 
    call.when = "setup", "call" or "teardown" 
    call.outerr = None or tuple of strings representing captured stdout/stderr 

.. _`pytest_pdb plugin`: http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/pytest_pdb.py
.. _`pytest_terminal plugin`: http://bitbucket.org/hpk42/py-trunk/src/tip/py/test/plugin/pytest_terminal.py