trial - run unit tests
trial [ options ] [ file | package | module | TestCase | testmethod ] ...
trial --help | -h
trial loads and executes a suite of unit tests, obtained from modules, packages and files
listed on the command line.
trial will take either filenames or fully qualified Python names as arguments. Thus
`trial myproject/foo.py', `trial myproject.foo' and `trial myproject.foo.SomeTest-
Case.test_method' are all valid ways to invoke trial.
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:
Tests that passed all their assertions and completed without error. These are
marked "PASSED" in the normal test output.
Tests that failed an assertion, called self.fail() or explicitly raised self.fail-
ureException for some reason. These are marked "FAILED" in the normal test output.
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.
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 exe-
skips Tests that were skipped, usually because of missing dependencies. These are marked
"SKIPPED" in the normal test output.
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
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.
Run the tests in the Python debugger. Also does post-mortem debugging on excep-
tions. Will load `.pdbrc' from current directory if it exists.
Report Deferred creation and callback stack traces
Generate coverage information in the `coverage' subdirectory of the trial temp
directory (`_trial_temp' by default). For each Python module touched by the execu-
tion 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.
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 collec-
tor 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.
Print tracebacks to standard output as soon as they occur
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.
Print a usage message to standard output, then exit.
Print a list of valid reporters to standard output, then exit. Reporters can be
selected with the --reporter option described below.
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 --reac-
tor option described below.
-l, --logfile logfile
Direct the log to a different file. The default file is `test.log'. logfile is
relative to _trial_temp.
Go through all the tests and make them pass without running.
By default, trial recurses through packages to find every module inside every sub-
package. Unless, that is, you specify this option.
--nopm Don't automatically jump into debugger for post-mortem analysis of exceptions.
Only usable in conjunction with --debug.
Run tests under the Python profiler.
-r, --reactor reactor
Choose which reactor to use. See --help-reactors for a list.
Set Python's recursion limit. See sys.setrecursionlimit()
Select the reporter to use for trial's output. Use the --help-reporters option to
see a list of valid reporters.
--spew Print an insanely verbose log of everything that happens. Useful when debugging
freezes or locks in complex code.
Format to display tracebacks with. Acceptable values are `default', `brief' and
`verbose'. `brief' produces tracebacks that play nicely with Emacs' GUD.
WARNING: Do not use this options 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 deletes 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 delete the directory before re-creating it.
Ask trial to look into filename and run any tests specified using the Emacs-style
buffer variable `test-case-name'.
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.
Keep looping the tests until one of them raises an error or a failure. This is
particularly useful for reproducing intermittent failures.
Prints the Twisted version number and exit.
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.
-z, --random [seed]
Run the tests in random order using the specified seed.
The latest version of the trial documentation can be found at http://twistedma-
Written by Jonathan M. Lange
To report a bug, visit http://twistedmatrix.com/trac/newticket
Copyright (C) 2003-2011 Twisted Matrix Laboratories
This is free software; see the source for copying conditions. There is NO warranty; not
even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Oct 2007 TRIAL(1)