How to test docstrings with 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):

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:

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:

"""
: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.