===============================================
ATTIC documentation 
===============================================

XXX REVIEW and remove the below  XXX


Customizing the testing process 
===============================

writing conftest.py files
-----------------------------------

You may put conftest.py files containing project-specific
configuration in your project's root directory, it's usually
best to put it just into the same directory level as your 
topmost ``__init__.py``.  In fact, ``py.test`` performs
an "upwards" search starting from the directory that you specify 
to be tested and will lookup configuration values right-to-left. 
You may have options that reside e.g. in your home directory 
but note that project specific settings will be considered
first.  There is a flag that helps you debugging your
conftest.py configurations::
    
    py.test --traceconfig


customizing the collecting and running process 
-----------------------------------------------

To introduce different test items you can create 
one or more ``conftest.py`` files in your project. 
When the collection process traverses directories 
and modules the default collectors will produce 
custom Collectors and Items if they are found 
in a local ``conftest.py`` file.  


Customizing the collection process in a module
---------------------------------------------- 

If you have a module where you want to take responsibility for
collecting your own test Items and possibly even for executing
a test then you can provide `generative tests`_ that yield 
callables and possibly arguments as a tuple.   This is especially
useful for calling application test machinery with different
parameter sets but counting each of the calls as a separate
tests. 

.. _`generative tests`: test-features.html#generative-tests

The other extension possibility is about 
specifying a custom test ``Item`` class which 
is responsible for setting up and executing an underlying 
test.  Or you can extend the collection process for a whole 
directory tree by putting Items in a ``conftest.py`` configuration file. 
The collection process dynamically consults the *chain of conftest.py* 
modules to determine collectors and items at ``Directory``, ``Module``, 
``Class``, ``Function`` or ``Generator`` level respectively.  

Customizing execution of Items and Functions 
----------------------------------------------------

- ``py.test.collect.Function`` test items control execution 
  of a test function through its ``function.runtest()`` method.
  This method is responsible for performing setup and teardown 
  ("Test Fixtures") for a test Function. 

- ``Function.execute(target, *args)`` methods are invoked by
  the default ``Function.run()`` to actually execute a python 
  function with the given (usually empty set of) arguments. 

.. _`py-dev mailing list`: http://codespeak.net/mailman/listinfo/py-dev