===============================================
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, ``pytest`` 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::

    pytest --trace-config


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`: 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
----------------------------------------------------

- ``pytest.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


.. _`test generators`: funcargs.html#test-generators

.. _`generative tests`:

generative tests: yielding parametrized tests
====================================================

Deprecated since 1.0 in favour of `test generators`_.

*Generative tests* are test methods that are *generator functions* which
``yield`` callables and their arguments.  This is useful for running a
test function multiple times against different parameters.  Example::

    def test_generative():
        for x in (42,17,49):
            yield check, x

    def check(arg):
        assert arg % 7 == 0   # second generated tests fails!

Note that ``test_generative()`` will cause three tests
to get run, notably ``check(42)``, ``check(17)`` and ``check(49)``
of which the middle one will obviously fail.

To make it easier to distinguish the generated tests it is possible to specify an explicit name for them, like for example::

    def test_generative():
        for x in (42,17,49):
            yield "case %d" % x, check, x


disabling a test class
----------------------

If you want to disable a complete test class you
can set the class-level attribute ``disabled``.
For example, in order to avoid running some tests on Win32::

    class TestPosixOnly(object):
        disabled = sys.platform == 'win32'

        def test_xxx(self):
            ...