======================================
Writing plugins and extensions 
======================================


.. _`local plugin`: 

Local Plugins
==================================

You can easily specify a project-specific or "local" 
plugin by defining a ``ConftestPlugin`` in a ``conftest.py``
file like this::

    class ConftestPlugin:
        """ my local plugin. """ 


Learning by examples
=====================

XXX

adding custom options
----------------------

py.test supports adding of standard optparse_ Options. 
A plugin may implement the ``addoption`` hook for registering 
custom options:: 

    class ConftestPlugin:
        def pytest_addoption(self, parser):
            parser.addoption("-M", "--myopt", action="store", 
                help="specify string to set myopt")

        def pytest_configure(self, config):
            if config.option.myopt:
                # do action based on option value

.. _optparse: http://docs.python.org/library/optparse.html

Setting default values for test options
=======================================

You can see all available command line options by running::

    py.test -h 

py.test will lookup values of options in this order:

* option value supplied at command line 
* content of environment variable ``PYTEST_OPTION_NAME=...``
* ``name = ...`` setting in the nearest ``conftest.py`` file.

The name of an option usually is the one you find 
in the longform of the option, i.e. the name 
behind the ``--`` double-dash. 

IOW, you can set default values for options per project, per
home-directoray, per shell session or per test-run. 

.. _`collection process`: 

Test Collection process 
====================================================== 

The collecting process is iterative so that distribution
and execution of tests can start as soon as the first test
item is collected.  Collection nodes with children are 
called "Collectors" and terminal nodes are called "Items".  
Here is an example of such a tree, generated with the 
command ``py.test --collectonly py/xmlobj``:: 

    <Directory 'xmlobj'>
        <Directory 'testing'>
            <Module 'test_html.py' (py.__.xmlobj.testing.test_html)>
                <Function 'test_html_name_stickyness'>
                <Function 'test_stylenames'>
                <Function 'test_class_None'>
                <Function 'test_alternating_style'>
            <Module 'test_xml.py' (py.__.xmlobj.testing.test_xml)>
                <Function 'test_tag_with_text'>
                <Function 'test_class_identity'>
                <Function 'test_tag_with_text_and_attributes'>
                <Function 'test_tag_with_subclassed_attr_simple'>
                <Function 'test_tag_nested'>
                <Function 'test_tag_xmlname'>

By default all directories not starting with a dot are traversed, 
looking for ``test_*.py`` and ``*_test.py`` files.  Those Python 
files are imported under their `package name`_. 

The Module collector looks for test functions 
and test classes and methods. Test functions and methods
are prefixed ``test`` by default.  Test classes must 
start with a capitalized ``Test`` prefix. 

.. _`package name`: 

constructing the package name for test modules
-------------------------------------------------

Test modules are imported under their fully qualified 
name.  Given a filesystem ``fspath`` it is constructed as follows:

* walk the directories up to the last one that contains 
  an ``__init__.py`` file.  

* perform ``sys.path.insert(0, basedir)``.

* import the root package as ``root``

* determine the fully qualified name for ``fspath`` by either:

  * calling ``root.__pkg__.getimportname(fspath)`` if the
    ``__pkg__`` exists.` or 

  * otherwise use the relative path of the module path to
    the base dir and turn slashes into dots and strike
    the trailing ``.py``. 


Plugin hooks and events  
=======================================

XXX