<html lang="en">
<head>
<title>Trial - 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="Python-BuildSteps.html#Python-BuildSteps" title="Python BuildSteps">
<link rel="prev" href="PyLint.html#PyLint" title="PyLint">
<link rel="next" href="RemovePYCs.html#RemovePYCs" title="RemovePYCs">
<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"></a>
<p>
Next: <a rel="next" accesskey="n" href="RemovePYCs.html#RemovePYCs">RemovePYCs</a>,
Previous: <a rel="previous" accesskey="p" href="PyLint.html#PyLint">PyLint</a>,
Up: <a rel="up" accesskey="u" href="Python-BuildSteps.html#Python-BuildSteps">Python BuildSteps</a>
<hr>
</div>
<h5 class="subsubsection">4.12.6.4 Trial</h5>
<p><a name="index-buildbot_002esteps_002epython_005ftwisted_002eTrial-119"></a>
This step runs a unit test suite using <code>trial</code>, a unittest-like testing
framework that is a component of Twisted Python. Trial is used to implement
Twisted's own unit tests, and is the unittest-framework of choice for many
projects that use Twisted internally.
<p>Projects that use trial typically have all their test cases in a 'test'
subdirectory of their top-level library directory. For example, for a package
<code>petmail</code>, the tests might be in <code>petmail/test/test_*.py</code>. More
complicated packages (like Twisted itself) may have multiple test directories,
like <code>twisted/test/test_*.py</code> for the core functionality and
<code>twisted/mail/test/test_*.py</code> for the email-specific tests.
<p>To run trial tests manually, you run the <code>trial</code> executable and tell it
where the test cases are located. The most common way of doing this is with a
module name. For petmail, this might look like <code>trial petmail.test</code>, which
would locate all the <code>test_*.py</code> files under <code>petmail/test/</code>, running
every test case it could find in them. Unlike the <code>unittest.py</code> that
comes with Python, it is not necessary to run the <code>test_foo.py</code> as a
script; you always let trial do the importing and running. The step's
<code>tests</code> parameter controls which tests trial will run: it can be a string
or a list of strings.
<p>To find the test cases, the Python search path must allow something like
<code>import petmail.test</code> to work. For packages that don't use a separate
top-level <code>lib</code> directory, <code>PYTHONPATH=.</code> will work, and will use the
test cases (and the code they are testing) in-place.
<code>PYTHONPATH=build/lib</code> or <code>PYTHONPATH=build/lib.somearch</code> are also
useful when you do a <code>python setup.py build</code> step first. The
<code>testpath</code> attribute of this class controls what <code>PYTHONPATH</code> is set
to before running <code>trial</code>.
<p>Trial has the ability, through the <code>--testmodule</code> flag, to run only the
set of test cases named by special <code>test-case-name</code> tags in source files.
We can get the list of changed source files from our parent Build and provide
them to trial, thus running the minimal set of test cases needed to cover the
Changes. This is useful for quick builds, especially in trees with a lot of
test cases. The <code>testChanges</code> parameter controls this feature: if set, it
will override <code>tests</code>.
<p>The trial executable itself is typically just <code>trial</code>, and is typically
found in the shell search path. It can be overridden with the <code>trial</code>
parameter. This is useful for Twisted's own unittests, which want to use the
copy of bin/trial that comes with the sources.
<p>To influence the version of python being used for the tests, or to add flags to
the command, set the <code>python</code> parameter. This can be a string (like
<code>python2.2</code>) or a list (like <code>['python2.3', '-Wall']</code>).
<p>Trial creates and switches into a directory named <code>_trial_temp/</code> before
running the tests, and sends the twisted log (which includes all exceptions) to
a file named <code>test.log</code>. This file will be pulled up to the master where
it can be seen as part of the status output.
<pre class="example"> from buildbot.steps.python_twisted import Trial
f.addStep(Trial(tests='petmail.test'))
</pre>
</body></html>
