[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