[Buildbot-commits] buildbot/docs factories.xhtml,1.5,1.6
Brian Warner
warner at users.sourceforge.net
Tue Nov 23 01:13:56 UTC 2004
Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15915/docs
Modified Files:
factories.xhtml
Log Message:
* buildbot/process/step_twisted.py (Trial): update docs a bit
* docs/factories.xhtml: fix Trial factory docs to match reality.
Closes: SF#1049758.
* buildbot/process/factory.py (Trial.__init__): add args for
randomly= and recurse=, making them available to instantiators
instead of only to subclassers. Closes: SF#1049759.
Index: factories.xhtml
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/factories.xhtml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- factories.xhtml 30 Aug 2004 08:40:31 -0000 1.5
+++ factories.xhtml 23 Nov 2004 01:13:53 -0000 1.6
@@ -306,10 +306,15 @@
<p>Unfortunately, the <q>build/lib</q> 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. In addition, the
-<q>PROJECTNAME</q> value 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 <q>test</q> sub-module.</p>
+know of a simple way to calculate its value. For many projects it is
+sufficient to import their libraries <q>in place</q> from the tree's base
+directory (<code>PYTHONPATH=.</code>).</p>
+
+<p>In addition, the <q>PROJECTNAME</q> 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 <q>test</q> sub-module. This value cannot be guessed, the
+<code>Trial</code> class must be told where to find the test files.</p>
<p>The <code>Trial</code> class provides support for building and testing
projects which use distutils and trial. If the test module name is
@@ -333,37 +338,107 @@
<li><code>source</code> (required): A step specification tuple, that that
used by GNUAutoconf.</li>
- <li><code>python</code>: A string which specifies the <q>python</q>
- executable to use. Defaults to just <q>python</q>.</li>
+ <li><code>buildpython</code>: A list (argv array) of strings which
+ specifies the <q>python</q> executable to use when building the package.
+ Defaults to just <code>['python']</code>. It may be useful to add flags
+ here, to supress warnings during compilation of extension modules. This
+ list is extended with <code>['./setup.py', 'build']</code> and then
+ executed in a ShellCommand.</li>
- <li><code>trialModule</code>: Provides a module name which contains 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.</li>
+ <li><code>testpath</code>: 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 <q>build/lib</q> for pure-python modules.</li>
+
+ <li><code>trialpython</code>: Another list of strings used to build the
+ command that actually runs trial. This is prepended to the contents of the
+ <code>trial</code> argument below. It may be useful to add <q>-W</q> flags
+ here to supress warnings that occur while tests are being run. Defaults to
+ an empty list, meaning <code>trial</code> will be run without an explicit
+ interpreter, which is generally what you want if you're using
+ /usr/bin/trial instead of, say, the ./bin/trial that lives in the Twisted
+ source tree.</li>
<li><code>trial</code>: provides the name of the <q>trial</q> command. It
is occasionally useful to use an alternate executable, such as
<q>trial2.2</q> which might run the tests under an older version of
Python. Defaults to <q>trial</q>.</li>
-
- <li><code>testPath</code>: 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 <q>build/lib</q> for pure-python modules.</li>
- <li><code>trialArgs</code>: Provides a list of additional arguments to
- give to trial. <code>["--reactor", "gtk2"]</code> would use an alternate
- reactor, <code>["--random", "0"]</code> would run the tests in a random
- order each time. Defaults to an empty list.</li>
+ <li><code>tests</code>: 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>useTestCaseNames</code> to do anyting useful with the Trial
+ factory.</li>
<li><code>useTestCaseNames</code>: Tells the Step to provide the names of
all changed .py files to trial, so it can look for test-case-name tags and
run just the matching test cases. Suitable for use in quick builds.
Defaults to False.</li>
+
+ <li><code>randomly</code>: If <q>True</q>, 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
+ <q>False</q>.</li>
+
+ <li><code>recurse</code>: If <q>True</q>, tells Trial (with the
+ <code>--recurse</code> argument) to look in all subdirectories for
+ additional test cases. It isn't clear to me how this works, but it may be
+ useful to deal with the unknown-PROJECTNAME problem described above, and
+ is currently used in the Twisted buildbot to accomodate the fact that test
+ cases are now distributed through multiple twisted.SUBPROJECT.test
+ directories.</li>
+
</ul>
<p>Unless one of <code>trialModule</code> or <code>useTestCaseNames</code>
are set, no tests will be run.</p>
+<p>Some quick examples follow. Most of these examples assume that the target
+python code (the <q>code under test</q>) can be reached directly from the
+root of the target tree, rather than being in a lib/ subdirectory.</p>
+
+<pre>
+# Trial(source, tests="toplevel.test") does:
+# python ./setup.py build
+# PYTHONPATH=. trial -to toplevel.test
+
+# Trial(source, tests=["toplevel.test", "other.test"]) does:
+# python ./setup.py build
+# PYTHONPATH=. trial -to toplevel.test other.test
+
+# Trial(source, useTestCaseNames=True) does:
+# python ./setup.py build
+# PYTHONPATH=. trial -to --testmodule=foo/bar.py.. (from Changes)
+
+# Trial(source, buildpython=["python2.3", "-Wall"], tests="foo.tests") does:
+# python2.3 -Wall ./setup.py build
+# PYTHONPATH=. trial -to foo.tests
+
+# Trial(source, trialpython="python2.3", trial="/usr/bin/trial",
+# tests="foo.tests") does:
+# python2.3 -Wall ./setup.py build
+# PYTHONPATH=. python2.3 /usr/bin/trial -to foo.tests
+
+# For running trial out of the tree being tested (only useful when the tree
+# being built is Twisted itself):
+# Trial(source, trialpython=["python2.3", "-Wall"], trial="./bin/trial",
+# tests="foo.tests") does:
+# python2.3 -Wall ./setup.py build
+# PYTHONPATH=. python2.3 -Wall ./bin/trial -to foo.tests
+</pre>
+
+<p>If the output directory of <q>./setup.py build</q> is known, you can pull
+the python code from the built location instead of the source directories.
+This should be able to handle variations in where the source comes from, as
+well as accomodating binary extension modules:</p>
+
+<pre>
+# Trial(source, tests="toplevel.test", testpath='build/lib.linux-i686-2.3')
+# does:
+# python ./setup.py build
+# PYTHONPATH=build/lib.linux-i686-2.3 trial -to toplevel.test
+</pre>
+
</body> </html>
More information about the Commits
mailing list