# 2.5.13.38. Trial

class buildbot.steps.python_twisted.Trial

This step runs a unit test suite using trial, a unittest-like testing framework that is a component of Twisted Python.

The `Trial` takes the following arguments:

`python`

  (string or list of strings, optional) Which python executable to use. Will form the start of the argv array that will launch `trial`. If you use this, you should set `trial` to an explicit path (like /usr/bin/trial or ./bin/trial). Defaults to `None`, which leaves it out entirely (running ‘trial args’ instead of python ./bin/trial args’). Likely values are `'python'`, `['python3.8']`, `['python', '-Wall']`, etc.

`trial`

  (string, optional) Which ‘trial’ executable to run Defaults to `'trial'`, which will cause `$PATH` to be searched and probably find `/usr/bin/trial`. If you set `python`, this should be set to an explicit path (because `python3.8 trial` will not work).

`trialMode`

  (list of strings, optional) A list of arguments to pass to trial to set the reporting mode. This defaults to `['-to']` which means ‘verbose colorless output’ to the trial that comes with Twisted-2.0.x and at least -2.1.0 . Newer versions of Twisted may come with a trial that prefers `['--reporter=bwverbose']`.

`trialArgs`

  (list of strings, optional) A list of arguments to pass to trial. This can be used to turn on any extra flags you like. Defaults to `[]`.

`jobs`

  (integer, optional) Defines the number of parallel jobs.

`tests`

  (list of strings, optional) Defines the test modules to run. For example, `['twisted.test.test_defer', 'twisted.test.test_process']` If this is a string, it will be converted into a one-item list.

`testChanges`

  (boolean, optional) Selects the tests according to the changes in the Build. If set, this will override the `tests` parameter and asks the Build for all the files that make up the Changes going into this build. The filenames will be passed to `trial` asking to run just the tests necessary to cover the changes.

`recurse`

  (boolean, optional) Selects the `--recurse` option of trial. This allows test cases to be found in deeper subdirectories of the modules listed in `tests`. When using `testChanges` this option is not necessary.

`reactor`

  (boolean, optional) Selects the reactor to use within Trial. For example, options are `gtk` or `java`. If not provided, the Twisted’s usual platform-dependent default is used.

`randomly`

  (boolean, optional) If `True`, adds the `--random=0` argument, which instructs trial to run the unit tests in a random order each time. This occasionally catches problems that might be masked when one module always runs before another.

`**kwargs`

  (dict, optional) The step inherits all arguments of `ShellMixin` except `command`.

Trial creates and switches into a directory named `_trial_temp/` before running the tests, and sends the twisted log (which includes all exceptions) to a file named `test.log`. This file will be pulled up to the master where it can be seen as part of the status output.

    from buildbot.plugins import steps

    f.addStep(steps.Trial(tests='petmail.test'))