DESIGN.txt

testflo is a python testing framework that uses a pipeline of
iterators to process test specifications, run the tests, and process the
results.

The testflo API consists of a single callable that takes
an input iterator of Test objects as an argument and returns an
output iterator of Test objects.  The source of the pipeline is a plain
python iterator since it doesn't need an input iterator. By simply adding
members to the testflo pipeline, it's easy to add new features.

The pipeline starts with an iterator of strings that I'll call
'general test specifiers'.  These can have any of the following forms:

<module or file path>
<module or file path>:<TestCase class name>.<method name>
<module or file path>:<function name>
<directory path>

where <module or file path> is either the filesystem pathname of the
python file containing the test(s) or the python module path, e.g.,
'foo.bar.baz'.

The general test specifiers are iterated over by the TestDiscoverer, who
generates an output iterator of Test objects. There is a Test object for each
individual test.  As of version 1.1, the objects in the TestDiscoverer's
output iterator can be either individual Test objects or lists of Test
objects. This change was necessary to support module level and TestCase
class level setup and teardown functions.  The thought was that all tests
under either a module level setup/teardown or a TestCase class level
setup/teardown should be grouped and executed in the same process, so
when these functions are present, the Test objects are grouped into a list
and sent together to the ConcurrentTestRunner.  After execution, the rest
of the pipeline sees only individual Test objects.

The ConcurrentTestRunner
executes each test and passes an iterator of those to the ResultPrinter,
who then passes them on to the ResultSummary.

The multiprocessing library is used in the ConcurrentTestRunner to support concurrent
execution of tests.  It adds Test objects to a shared Queue that the
worker processes pull from. Then the workers place the finished Test objects in
a 'done' Queue that the ConcurrentTestRunner pulls from and passes downstream for
display, summary, or whatever.