Twisted provides a unit test tool named trial
which provides a
few improvements over Python's built-in unittest
module. Many
python projects which use Twisted for their networking or application
services also use trial for their unit tests. These modules are
usually built and tested with something like the following:
% python ./setup.py build % PYTHONPATH=build/lib.linux-i686-2.3 trial -v PROJECTNAME.test % python ./setup.py install
Unfortunately, the build/lib directory into which the
built/copied .py files are placed is actually architecture-dependent,
and I do not yet know of a simple way to calculate its value. For many
projects it is sufficient to import their libraries “in place” from
the tree's base directory (PYTHONPATH=.
).
In addition, the PROJECTNAME value where the test files are
located is project-dependent: it is usually just the project's
top-level library directory, as common practice suggests the unit test
files are put in the test
sub-module. This value cannot be
guessed, the Trial
class must be told where to find the test
files.
The Trial
class provides support for building and testing
projects which use distutils and trial. If the test module name is
specified, trial will be invoked. The library path used for testing
can also be set.
One advantage of trial is that the Buildbot happens to know how to parse trial output, letting it identify which tests passed and which ones failed. The Buildbot can then provide fine-grained reports about how many tests have failed, when individual tests fail when they had been passing previously, etc.
Another feature of trial is that you can give it a series of source
.py files, and it will search them for special test-case-name
tags that indicate which test cases provide coverage for that file.
Trial can then run just the appropriate tests. This is useful for
quick builds, where you want to only run the test cases that cover the
changed functionality.
Arguments:
testpath
PYTHONPATH
when running the unit
tests, if tests are being run. Defaults to .
to include the
project files in-place. The generated build library is frequently
architecture-dependent, but may simply be build/lib for
pure-python modules.
python
trial
to an explicit path (like
/usr/bin/trial
or ./bin/trial
). The parameter defaults to None
, which
leaves it out entirely (running trial args
instead of
python ./bin/trial args
). Likely values are ['python']
,
['python2.2']
, or ['python', '-Wall']
.
trial
trial
command. It is occasionally
useful to use an alternate executable, such as trial2.2
which
might run the tests under an older version of Python. Defaults to
trial
.
trialMode
['--reporter=bwverbose']
, which only works for
Twisted-2.1.0 and later.
trialArgs
[]
.
tests
PROJECTNAME.test
, or a
list of strings. Defaults to None, indicating that no tests should be
run. You must either set this or testChanges
.
testChanges
tests
parameter and instead ask the Build for all
the files that make up the Changes going into this build. Pass these filenames
to trial and ask it to look for test-case-name tags, running just the tests
necessary to cover the changes.
recurse
True
, tells Trial (with the --recurse
argument) to look in all
subdirectories for additional test cases.
reactor
randomly
True
, tells Trial (with the --random=0
argument) to
run the test cases in random order, which sometimes catches subtle
inter-test dependency bugs. Defaults to False
.
The step can also take any of the ShellCommand
arguments, e.g.,
haltOnFailure
.
Unless one of tests
or testChanges
are set, the step will
generate an exception.