Context Navigation

Trial

Trial is two things. The first is a command-line test runner, which can be run on plain Python unit tests. It's very simple to use. For example, the fastest way to get going with Trial is to write a plain Python unit test like this:

Trial's test runner can do automated unit-test discovery across files, modules, or even arbitrarily nested packages. For example, you can run Twisted's own tests with it by just typing trial twisted in a shell.

Trial's test runner will also automatically catch errors that are logged but not ​explicitly handled. For example, this test will fail:

run your tests under PDB and automatically break into the debugger on failure

Trial also provides a ​plug-in interface for customizing and recording the output of test runs. You can type trial --help-reporters for more information about the plugins that are available on your system.

In addition to the test runner, Trial also includes a test library, derived from Python's unittest.TestCase. You can use this library by subclassing ​twisted.trial.unittest.TestCase rather than Python's built-in unittest.TestCase.

The main unique feature of this testing class is the ability to return a ​Deferred from a test-case method. A test method which returns a Deferred will not complete until that Deferred has fired; the reactor will be automatically set up and run for you, along with a timeout to make sure that tests don't run forever. If the Deferred fires successfully, the test passes. If it fires with an error, the test fails. This makes it possible to easily unit-test asynchronous event-driven code, or to use Twisted APIs that return Deferreds in order to write automated functional tests that communicate with a live running service.

Trial's TestCase also includes several ​convenience features which we find useful for testing Twisted itself; if you're writing Twisted code, it's likely you'll find them useful too.

Download

Trial is a core component of Twisted. As such, there is no need to download it separately. If you have downloaded the Twisted tarball, you'll find the Trial source code in the
twisted/trial directory.

Documentation

You can find Trial API documentation ​here. If you run trial --help from the command line, you'll see
a list of possible invocation arguments (the trial command can be found in bin in the tarball). Beyond, seeing as much of Twisted
itself is of course tested with Trial, you can examine the
test directories of the various Twisted projects to see examples of Trial use. And as ever, having a look through the source code is also instructive.