How to test docstrings with :mod:`z3c.testsetup`
************************************************

:Author: Peter Bengtsson, Uli Fouquet
:Version: This document is based on Grok <= 1.0
:Intended Audience: Developers

Purpose
=======

Show how to include the doc strings of your classes into the test
suite with `z3c.testsetup`.

.. note:: The usage of `z3c.testsetup` for testing is generally
          *deprecated* as Grok in general will switch to wider spread
          Python testing frameworks like `py.test` or `nose` in
          future. Heading for new life forms and new civilizations, to
          boldly go where no man has gone before, we start by using
          plain unittests and will then leave the sector of
          `zope.testrunner` deploying fancier forms of testing. If you
          want to follow this trek, please do not use `z3c.testsetup`
          (any more). Use plain unittests or `py.test` or `nose`
          instead and simply ignore this HowTo.


Prerequisities
==============

`easy_install` and an Internet connection.

Step by step
============

We're assuming that you don't already have a Grok project up and
running but if you already do it should be easy you understand where
this all fits in. For the sake of simplicity we'll go through from the
start. The first thing is to install grokproject and then modify it's
setup.py::

  $ cd /tmp
  $ grokproject Sample
  $ cd Sample
  $ emacs setup.py

The necessary change is to include `z3c.testsetup` in the
'install_requires' (if it is not there already):

.. code-block:: python

      install_requires=['setuptools',
                        'grok',
                        'z3c.testsetup',
                        ],

Once you've added that run `buildout` again::

 $ ./bin/buildout

Next add a file called ``tests.py`` which according to
``buildout.cfg`` automatically picks up. Let it contain the following
code:

.. code-block:: python

 import z3c.testsetup

 test_suite = z3c.testsetup.register_all_tests('sample',
                                 extensions=['.py','.txt','.rst'],
                                 )

The key here is to including doc string tests inside the Python files
is in adding ``.py`` to the parameter ``extensions``.

The next step is to modify the file ``app.py`` a little bit so that it
includes a naive but working test. So change ``app.py`` to look like
this:

.. code-block:: python

 """
 :Test-Layer: unit

 Documentation for the module.
 """

 class Sample(grok.Application, grok.Container):
    """
    Test something

      >>> from sample.app import Sample
      >>> sample= Sample()
      >>> sample.foo()
      'test'

    """
    def foo(self):
        return 'test'

The next step is of course to write the interesting code and a more
interesting test. But here's what you expect to happen when you run
the test runner::

 $ ./bin/test
 Running tests at level 1
 Running unit tests:
   Running:
 .
   Ran 1 tests with 0 failures and 0 errors in 0.004 seconds.

Further information
===================

The usage of `z3c.testsetup` for testing is generally deprecated as
Grok in general will switch to wider spread Python testing frameworks
like `py.test` or `nose` in future.