.TH TRIAL "1" "Jun 2013" "" ""
.SH NAME
trial \- run unit tests
.SH SYNOPSIS
\fBtrial\fR [ \fIoptions\fR ] [ \fIfile\fR | \fIpackage\fR | \fImodule\fR | \fITestCase\fR | \fItestmethod\fR ] ...
.PP
\fBtrial --help\fR | \fB-h\fR
.SH DESCRIPTION
.PP
trial loads and executes a suite of unit tests, obtained from modules,
packages and files listed on the command line.
.PP
trial will take either filenames or fully qualified Python names as
arguments.  Thus `trial myproject/foo.py', `trial myproject.foo' and
`trial myproject.foo.SomeTestCase.test_method' are all valid ways to
invoke trial. Multiple such arguments are also accepted, and their order will
determine the order in which the corresponding tests are run.
.PP
After running the given test suite, the default test reporter prints a summary
of the test run. This consists of the word "PASSED" (if all tests ran as
expected) or "FAILED" (if any test behaved unexpectedly) followed by a count of
the different kinds of test results encountered. The possible kinds of test
results includes:
.TP
successes
Tests that passed all their assertions and completed without error.
These are marked "PASSED" in the normal test output.
.TP
failures
Tests that failed an assertion, called self.fail() or explicitly raised
self.failureException for some reason. These are marked "FAILED" in the
normal test output.
.TP
errors
Tests that raised an unexpected exception (including AssertionError),
tests that caused the tearDown() method to raise an exception, tests
that run for longer than the timeout interval, tests that caused
something to call twisted.python.log.err() without subsequently calling
self.flushLoggedErrors(), tests that leave the reactor in an unclean
state, etc. These are marked "ERROR" in the normal test output.
.IP
Note that because errors can be caused after the actual test method
returns, it is possible for a single test to be reported as both an
error and a failure, and hence the total number of test results can be
greater than the total number of tests executed.
.TP
skips
Tests that were skipped, usually because of missing dependencies. These
are marked "SKIPPED" in the normal test output.
.TP
expectedFailures
Tests that failed, but were expected to fail, usually because the test
is for a feature that hasn't been implemented yet. These are marked
"TODO" in the normal test output.
.TP
unexpectedSuccesses
Tests that should have been listed under expectedFailures, except that
for some reason the test succeeded. These are marked "SUCCESS!?!" in
the normal test output.
.SH OPTIONS
.TP
\fB-j\fR, \fB--jobs\fR \fInumber\fR
Set the number of process workers to run. It conflicts with the debug,
exitfirst and profile options.
.TP
\fB-b\fR, \fB--debug\fR
Run the tests in a debugger. If that debugger is 'pdb' (which is the default if
unspecified), a `.pdbrc' will be loaded from the current directory if it
exists. Also does post-mortem debugging on exceptions.
.TP
\fB-B\fR, \fB--debug-stacktraces\fR
Report Deferred creation and callback stack traces.
.TP
\fB--coverage\fR
Generate coverage information in the `coverage' subdirectory of the trial temp
directory (`_trial_temp' by default). For each Python module touched by the
execution of the given tests, a file will be created in the coverage directory
named for the module's fully-qualified name with the suffix `.cover'.  For
example, because the trial test runner is written in Python, the coverage
directory will almost always contain a file named `twisted.trial.runner.cover'.

Each `.cover' file contains a copy of the Python source of the module in
question, with a prefix at the beginning of each line containing coverage
information.  For lines that are not executable (blank lines, comments, etc.)
the prefix is blank.  For executable lines that were run in the course of the
test suite, the prefix is a number indicating the number of times that line was
executed.  The string `>>>>>>' prefixes executable lines that were not executed
in the course of the test suite.

Note that this functionality uses Python's sys.settrace() function, so tests
that call sys.settrace() themselves are likely to break trial's coverage
functionality.
.TP
\fB--debugger\fR
Specifies the debugger to use when the --debug option is passed. The argument
should be the fully qualified name of an object that implements the same
interface as the standard library's `pdb'.
.TP
\fB--disablegc\fR
Disable the garbage collector for the duration of the test run. As each test is
run, trial saves the TestResult objects, which means that Python's garbage
collector has more non-garbage objects to wade through, making each
garbage-collection run slightly slower. Disabling garbage collection entirely
will make some test suites complete faster (contrast --force-gc, below), at the
cost of increasing (possibly greatly) memory consumption. This option also makes
tests slightly more deterministic, which might help debugging in extreme
circumstances.
.TP
\fB-e\fR, \fB--rterrors\fR
Print tracebacks to standard output as soon as they occur.
.TP
\fB--force-gc\fR
Run gc.collect() before and after each test case. This can be used to
isolate errors that occur when objects get collected.  This option would be
the default, except it makes tests run about ten times slower.
.TP
\fB-h\fR, \fB--help\fR
Print a usage message to standard output, then exit.
.TP
\fB--help-order\fR
Print a list of possible orders that TestCase test methods can be run in, then
exit. The orders can be used with the --order option described below.
.TP
\fB--help-reporters\fR
Print a list of valid reporters to standard output, then exit. Reporters can
be selected with the --reporter option described below.
.TP
\fB--help-reactors\fR
Print a list of possible reactors to standard output, then exit. Not all listed
reactors are available on every platform. Reactors can be selected with the
--reactor option described below.
.TP
\fB-l\fR, \fB--logfile\fR \fIlogfile\fR
Direct the log to a different file. The default file is `test.log'.
\fIlogfile\fR is relative to _trial_temp.
.TP
\fB-n\fR, \fB--dry-run\fR
Go through all the tests and make them pass without running.
.TP
\fB-N\fR, \fB--no-recurse\fR
By default, trial recurses through packages to find every module inside
every subpackage.  Unless, that is, you specify this option.
.TP
\fB--nopm\fR
Don't automatically jump into debugger for post-mortem analysis of
exceptions.  Only usable in conjunction with --debug.
.TP
\fB--order\fR \fIorder\fR
Specify what order to run the individual test methods within the given
TestCases. By default, they are run alphabetically. See --help-order for a list
of other valid values.
.TP
\fB--profile\fR
Run tests under the Python profiler.
.TP
\fB-r\fR, \fB--reactor\fR \fIreactor\fR
Choose which reactor to use.  See --help-reactors for a list.
.TP
\fB--recursionlimit\fR \fIlimit\fR
Set Python's recursion limit. See sys.setrecursionlimit().
.TP
\fB--reporter\fR \fIreporter\fR
Select the reporter to use for trial's output.  Use the --help-reporters
option to see a list of valid reporters.
.TP
\fB-x\fR, \fB--exitfirst\fR
Stop the test run after the first test which does not succeed. This includes
failures, errors, or unexpected successes. Won't work with the --jobs option
currently.
.TP
\fB--spew\fR
Print an insanely verbose log of everything that happens. Useful when
debugging freezes or locks in complex code.
.TP
\fB--tbformat\fR \fIformat\fR
Format to display tracebacks with. Acceptable values are `default', `brief'
and `verbose'. `brief' produces tracebacks that play nicely with Emacs' GUD.
.TP
\fB--temp-directory\fR \fIdirectory\fR
WARNING: Do not use this option unless you know what you are doing.
By default, trial creates a directory called _trial_temp under the current
working directory.  When trial runs, it first \fIdeletes\fR this directory,
then creates it, then changes into the directory to run the tests. The log
file and any coverage files are stored here. Use this option if you wish to
have trial run in a directory other than _trial_temp. Be warned, trial
will \fIdelete\fR the directory before re-creating it.
.TP
\fB--testmodule\fR \fIfilename\fR
Ask trial to look into \fIfilename\fR and run any tests specified using the
Emacs-style buffer variable `test-case-name'.
.TP
\fB--unclean-warnings\fR
As of Twisted 8.0, trial will report an error if the reactor is left unclean
at the end of the test. This option is provided to assist in migrating from
Twisted 2.5 to Twisted 8.0 and later. Enabling this option will turn the errors
into warnings.
.TP
\fB-u\fR, \fB--until-failure\fR
Keep looping the tests until one of them raises an error or a failure.
This is particularly useful for reproducing intermittent failures.
.TP
\fB--version\fR
Prints the Twisted version number and exit.
.TP
\fB--without-module\fR \fImodulenames\fR
Simulate the lack of the specified comma-separated list of modules. This makes
it look like the modules are not present in the system, causing tests to check
the behavior for that configuration.
.TP
\fB-z\fR, \fB--random\fR \fIseed\fR
Run the tests in random order using the specified seed. Don't pass this option
if you also are passing --order.
.PP
.SH SEE ALSO
The latest version of the trial documentation can be found at
http://twistedmatrix.com/documents/current/core/howto/testing.html
.SH AUTHOR
Written by Jonathan M. Lange
.SH "REPORTING BUGS"
To report a bug, visit http://twistedmatrix.com/trac/newticket
.SH COPYRIGHT
Copyright \(co 2003-2013 Twisted Matrix Laboratories
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.