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 (
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
Trial class must be told where to find the test
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
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
PYTHONPATHwhen 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.
trialto an explicit path (like
./bin/trial). The parameter defaults to
None, which leaves it out entirely (running
trial argsinstead of
python ./bin/trial args). Likely values are
trialcommand. It is occasionally useful to use an alternate executable, such as
trial2.2which might run the tests under an older version of Python. Defaults to
['--reporter=bwverbose'], which only works for Twisted-2.1.0 and later.
PROJECTNAME.test, or a list of strings. Defaults to None, indicating that no tests should be run. You must either set this or
testsparameter 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.
True, tells Trial (with the
--recurseargument) to look in all subdirectories for additional test cases.
True, tells Trial (with the
--random=0argument) to run the test cases in random order, which sometimes catches subtle inter-test dependency bugs. Defaults to
The step can also take any of the
ShellCommand arguments, e.g.,
Unless one of
testChanges are set, the step will
generate an exception.