Add documentation and fix failing assertion

master/buildbot/test/unit/test_steps_python_twisted.py

@@ -139,15 +139,11 @@ def test_run_jobs(self):
         included since Twisted 12.3.0), and make corresponding changes to
         logfiles and progressMetrics.
         """
-        step = python_twisted.Trial(workdir='build',
+        step = self.setupStep(python_twisted.Trial(workdir='build',
                                     tests = 'testname',
                                     testpath = None,
-                                    trialJobs=2)
-        self.setupStep(step)
+                                    trialJobs=2))
 
-        def check(r):
-            self.assertEqual(step.progressMetrics, ('output', 'tests',
-                                                   'test.0.log', 'test.1.log'))
         self.expectCommands(
             ExpectShell(workdir='build',
                         command=['trial', '--reporter=bwverbose', '--jobs=2',
@@ -162,10 +158,13 @@ def check(r):
                             'out.1.log': '_trial_temp/1/out.log',
                         })
             + ExpectShell.log('stdio', stdout="Ran 1 tests\n")
-            + ExpectShell.behavior(check)
             + 0
         )
         self.expectOutcome(result=SUCCESS, status_text=['1 test', 'passed'])
+
+        def check(r):
+            self.assertEqual(step.progressMetrics, ('output', 'tests',
+                                                   'test.0.log', 'test.1.log'))
         return self.runStep().addCallback(check)
 
     def test_run_jobs_Properties(self):

master/docs/manual/cfg-buildsteps.rst

@@ -2263,6 +2263,19 @@ it can be seen as part of the status output. ::
     from buildbot.steps.python_twisted import Trial
     f.addStep(Trial(tests='petmail.test'))
 
+Trial has the ability to run tests on several workers in parallel (beginning
+with Twisted 12.3.0).  Set ``trialJobs`` to the number of workers you want to
+run.  Note that running :command:`trial` in this way will create multiple log
+files (named :file:`test.N.log`, :file:`err.N.log` and :file:`out.N.log`
+starting with ``N=0``) rather than a single :file:`test.log`.
+
+This step takes the following arguments:
+
+``trialJobs``
+   (optional) Number of slave-resident workers to use when running the tests.
+   Defaults to 1 worker.  Only works with Twisted>=12.3.0.
+
+
 .. bb:step:: RemovePYCs
 
 RemovePYCs