Rationale

For a mission critical application like a student information system, where consistency and security are essential, thorough testing is essential.  We must apply a common standard of testing for both contracted code and contributions by volunteers.  Therefore, the testing guidelines must require testing that is comprehensive, but not create an unnecessary disincentive for outside developers. 

We strongly endorse the use of doctests and testbrowser based functional tests as a means to create tests which are readable and useful to other developers.

Python API Code

Code which defines the Python API of a given package must be comprehensively unit tested, using doctests in text files with accompanying commentary in English.  The goals of testing and documentation are equally important for these files.  The test file should tell a story which describes how to use the API properly.  This file should demonstrate all code paths.  If this is not practical, additional doctests or Python-based unit tests must be provided. 

To make doctest-based documentation easily findable to new developers, primary doctest text file for a package should be named README.txt and located in the root of the package.  If the doctests are split into multiple text files for readability, they should all be referenced in README.txt.  For example, ZCML directives are commonly documented in directives.txt.  Python-based unit tests should be placed in a tests module.

Browser View Code

Whenever possible, browser view classes should not perform complex computations.  These should be handled by the Python API code.  The primary purpose of view code is simply passing results to page templates from Python API code, or implementing simple transformations of the data for the convienience of the template. When view classes are simple, functional tests, using the Zope testbrowser package, should be used. In these simple cases, proper unit tests, which are truly independent of the rest of the application, are impractical because the difficulty of setup outweighs the benefit of the test above and beyond the utility of the functional test.

When view classes must contain more complex functionality, then those classes should be unit tested in doctests or Python-based unit tests.

REST View Code

Like browser view classes, REST view classes should be as simple as possible.  However, because REST views themselves define an API, they should be tested with Python-based unit tests and functional tests.