<html lang="en"> <head> <title>Trial (Factory) - BuildBot Manual - 0.8.4p1</title> <meta http-equiv="Content-Type" content="text/html"> <meta name="description" content="BuildBot Manual - 0.8.4p1"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="start" href="index.html#Top"> <link rel="up" href="Build-Factories.html#Build-Factories" title="Build Factories"> <link rel="prev" href="Distutils.html#Distutils" title="Distutils"> <link rel="next" href="Build-Factory-Index.html#Build-Factory-Index" title="Build Factory Index"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <!-- This is the BuildBot manual for Buildbot version 0.8.4p1. Copyright (C) 2005, 2006, 2009, 2010 Brian Warner Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.--> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } --></style> </head> <body> <div class="node"> <a name="Trial-(Factory)"></a> <a name="Trial-_0028Factory_0029"></a> <p> Next: <a rel="next" accesskey="n" href="Build-Factory-Index.html#Build-Factory-Index">Build Factory Index</a>, Previous: <a rel="previous" accesskey="p" href="Distutils.html#Distutils">Distutils</a>, Up: <a rel="up" accesskey="u" href="Build-Factories.html#Build-Factories">Build Factories</a> <hr> </div> <h4 class="subsection">4.11.8 Trial</h4> <p><a name="index-buildbot_002eprocess_002efactory_002eTrial-77"></a> Twisted provides a unit test tool named <code>trial</code> which provides a few improvements over Python's built-in <code>unittest</code> 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: <pre class="example"> % python ./setup.py build % PYTHONPATH=build/lib.linux-i686-2.3 trial -v PROJECTNAME.test % python ./setup.py install </pre> <p>Unfortunately, the <samp><span class="file">build/lib</span></samp> 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 (<code>PYTHONPATH=.</code>). <p>In addition, the <var>PROJECTNAME</var> 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 <code>test</code> sub-module. This value cannot be guessed, the <code>Trial</code> class must be told where to find the test files. <p>The <code>Trial</code> 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. <p>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. <p>Another feature of trial is that you can give it a series of source .py files, and it will search them for special <code>test-case-name</code> 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. <p>Arguments: <dl> <dt><code>testpath</code><dd>Provides a directory to add to <code>PYTHONPATH</code> when running the unit tests, if tests are being run. Defaults to <code>.</code> to include the project files in-place. The generated build library is frequently architecture-dependent, but may simply be <samp><span class="file">build/lib</span></samp> for pure-python modules. <br><dt><code>python</code><dd>which python executable to use. This list will form the start of the argv array that will launch trial. If you use this, you should set <code>trial</code> to an explicit path (like <code>/usr/bin/trial</code> or <code>./bin/trial</code>). The parameter defaults to <code>None</code>, which leaves it out entirely (running <code>trial args</code> instead of <code>python ./bin/trial args</code>). Likely values are <code>['python']</code>, <code>['python2.2']</code>, or <code>['python', '-Wall']</code>. <br><dt><code>trial</code><dd>provides the name of the <code>trial</code> command. It is occasionally useful to use an alternate executable, such as <code>trial2.2</code> which might run the tests under an older version of Python. Defaults to <code>trial</code>. <br><dt><code>trialMode</code><dd>a list of arguments to pass to trial, specifically to set the reporting mode. This defaults to <code>['--reporter=bwverbose']</code>, which only works for Twisted-2.1.0 and later. <br><dt><code>trialArgs</code><dd>a list of arguments to pass to trial, available to turn on any extra flags you like. Defaults to <code>[]</code>. <br><dt><code>tests</code><dd>Provides a module name or names which contain the unit tests for this project. Accepts a string, typically <code>PROJECTNAME.test</code>, or a list of strings. Defaults to None, indicating that no tests should be run. You must either set this or <code>testChanges</code>. <br><dt><code>testChanges</code><dd>if True, ignore the <code>tests</code> 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. <br><dt><code>recurse</code><dd>If <code>True</code>, tells Trial (with the <code>--recurse</code> argument) to look in all subdirectories for additional test cases. <br><dt><code>reactor</code><dd>which reactor to use, like 'gtk' or 'java'. If not provided, the Twisted's usual platform-dependent default is used. <br><dt><code>randomly</code><dd>If <code>True</code>, tells Trial (with the <code>--random=0</code> argument) to run the test cases in random order, which sometimes catches subtle inter-test dependency bugs. Defaults to <code>False</code>. </dl> <p>The step can also take any of the <code>ShellCommand</code> arguments, e.g., <code>haltOnFailure</code>. <p>Unless one of <code>tests</code> or <code>testChanges</code> are set, the step will generate an exception. </body></html>