[TIP] specifying testfile patterns / RFC

[holger krekel]

Hi all, 

i am hacking on a new plugin to go into py.test-1.0.1 and i am
doing that in documentation-driven style.  So i am interested
in feedback and comments on the below soon-to-become reality
"pytest_testfiles" plugin.  

best & thanks,
holger

pytest_testfiles.py: determine test files for command line specified args. 
===========================================================================

usage example: specifying testfiles in a python module
-----------------------------------------------------

If you have a module ``mymodule.py`` you can specify test files like this::

    # content of: mymodule.py
   
    # relative paths 
    __testfiles__ = ['test/test_unittest.py', 'test/test_functional.py']

and if you then type:: 

    py.test mymodule.py 

then this will run the test files which were specified relatively 
to the directory of ``mymodule.py``.  

Ordering is significant: if you specify quick-running unit-tests 
first followed by slower running functional tests then issuing
commands like ``py.test -x`` allows to find failures quickly
and the easier-to-debug ones first. 


usage example: specifying project-specific testfile patterns
--------------------------------------------------------------

Suppose your project has this layout::

    app/
        sub1/
            module1.py 

    tests/
        unit/
            test_module1.py 
        functional/
            test_one.py 
            test_two.py 

you may specify filematching rules for finding tests like this::

    # contents of: conftest.py  
    conf_testfilepatterns = ["{topdir}/tests/unit/test_{basename}", 
                             "{topdir}/tests/functional/*.py"]

and if you then type::

    py.test app/sub1/module1.py 

the specified testfile patterns will be applied to check if there are matching test files.  In our example we will run test files in the following order:: 

    tests/unit/test_module.py 
    tests/functional/test_one.py
    tests/functional/test_two.py


default is to look for test files being close to code  
----------------------------------------------------------

If no ``conf_testfilepatterns`` are specified, py.test will use this
as a default setting::

    conf_testfilepatterns = [
        "*/test_{purebasename}.py", 
        "**/test_*.py", 
        "**/*_test.py"
    ]

Note that each matching test file will only be run at most once.  

Substitutions
-------------------

The following substitutions are performed for each file-or-directory command line argument:: 

    dirname        the dirname of the file 
    basename       basename of the file 
    purebasename   basename without the extension
    topdir         first upwards parent directory not containing __init__.py