1
.TH TRIAL "1" "January 2003" "" ""
1
.TH TRIAL "1" "July 2006" "" ""
3
3
trial \- run unit tests
6
[-b] [-v|-o|-j] [--coverage \fIcoverdir\fR] [-r \fIreactor\fR] [-l \fIlogfile\fR] [-m \fImodule\fR [-m \fImodule\fR ... ]] [-p \fIpackage\fR [-p \fIpackage\fR ... ]] \fIfile\fR|\fImodule\fR|\fIpackage\fR|\fITestCase\fR|\fItestMethod ...
5
.B trial [options] [[file|package|module|TestCase|testmethod]...]
11
trial loads and executes a suite of unit tests, obtained from modules and
12
packages listed on the command line.
13
The \fB\--help\fR option prints out a usage message to standard output.
15
\fB-s\fR, \fB--summary\fR
16
Print out just a machine-parseable summary of the results.
18
\fB-v\fR, \fB--verbose\fR
19
Be more verbose. Without this option, trial prints out a single character
20
for each test. (e.g. An 'F' for a failure, a '.' for a success, a 'S' for
21
skipped test, a 'T' for a todo and '!' for unexpected success). With this
22
option, trial prints a single line for each test. This is especially useful
23
for gauging how long each test takes.
25
\fB-o\fR, \fB--bwverbose\fR
26
Be verbose, but do not attempt to use colors (more log-file friendly)
28
\fB-j\fR, \fB--jelly\fR
29
Report results in a machine-readable jelly stream.
32
Report results with timing information for each test.
34
\fB--tbformat\fR <format>
35
Format to display tracebacks with. Valid values are 'plain' and 'emacs',
36
default being 'plain'.
38
\fB-m\fR, \fB--module\fR <module>
39
Module containing test cases.
41
\fB--testmodule\fR <module>
42
Find the test case for a named file
44
\fB-p\fR, \fB--package\fR <package>
45
Package containing modules that contain test cases.
46
trial loads modules named 'test_' within the given package.
48
\fB-l\fR, \fB--logfile\fR <logfile>
49
Log exceptions (and other things) to the given logfile.
51
\fB-r\fR, \fB--reactor\fR <reactor>
52
Use this reactor for running the tests. The reactor names are the same as
53
those accepted by twistd: c, qt, gtk2, and so on.
55
\fB--coverage\fR <coverdir>
56
Generate coverage information in the given directory (relative to
57
_trial_temp). Requires Python 2.3.3.
10
trial loads and executes a suite of unit tests, obtained from modules,
11
packages and files listed on the command line.
13
trial will take either filenames or fully qualified Python names as
14
arguments. Thus 'trial myproject/foo.py', 'trial myproject.foo' and
15
'trial myproject.foo.SomeTestCase.test_method' are all valid ways to
59
18
\fB-b\fR, \fB--debug\fR
60
19
Run the tests in the Python debugger. Also does post-mortem
61
20
debugging on exceptions.
63
\fB-R\fR, \fB--recurse\fR
64
Recursively search the specified packages for test modules.
22
\fB-B\fR, \fB--debug-stacktraces\fR
23
Report Deferred creation and callback stack traces
26
Generate coverage information in _trial_temp/coverage/. Requires Python 2.3
30
Disable the garbage collector. I don't know why this is in trial.
32
\fB-e\fR, \fB--rterrors\fR
33
Print tracebacks to standard output as soon as they occur
36
Run gc.collect() before and after each test case. This can be used to
37
isolate errors that occur when objects get collected. This option would be
38
the default, except it makes tests run about ten times slower.
40
\fB-h\fR, \fB--help\fR
41
Print a usage message to standard output, then exit.
43
\fB--help-reporters\fR
44
Print a list of valid reporters to standard output, then exit.
47
List the names of possibly available reactors.
49
\fB-l\fR, \fB--logfile\fR <logfile>
50
Direct the log to a different file. The default file is 'test.log'.
51
<logfile> is relative to _trial_temp.
53
\fB-n\fR, \fB--dry-run\fR
54
Go through all the tests and make them pass without running.
56
\fB-N\fR, \fB--no-recurse\fR
57
By default, trial recurses through packages to find every module inside
58
every subpackage. Unless, that is, you specify this option.
61
Don't automatically jump into debugger for post-mortem analysis of
62
exceptions. Only usable in conjunction with --debug.
65
I don't know what this option does.
67
\fB\-r\fR, \fB\--reactor\fR \fI<reactor>\fR
68
Choose which reactor to use. See --help-reactors for a list.
70
\fB--recursionlimit\fR
71
Set Python's recursion limit. I don't know why this is in trial.
74
Select the reporter to use for Trial's output. Use the --help-reporters
75
option to see a list of valid reporters.
78
Print an insanely verbose log of everything that happens. Useful when
79
debugging freezes or locks in complex code.
81
\fB--tbformat\fR <format>
82
Format to display tracebacks with. Acceptable values are 'default', 'brief'
83
and 'verbose'. 'brief' produces tracebacks that play nicely with Emacs' GUD.
85
\fB--temp-directory <directory>\fR
86
WARNING: Do not use this options unless you know what you are doing.
87
By default, trial creates a directory called _trial_temp under the current
88
working directory. When trial runs, it first \fIdeletes\fR this directory,
89
then creates it, then changes into the directory to run the tests. The log
90
file and any coverage files are stored here. Use this option if you wish to
91
have trial run in a directory other than _trial_temp. Be warned, trial
92
will \fIdelete\fR the directory before re-creating it.
94
\fB--testmodule <filename>\fR
95
Ask trial to look into <filename> and run any tests specified using the
96
Emacs-style buffer variable 'test-case-name'.
98
\fB-u\fR, \fB--until-failure\fR
99
Keep looping the tests until one of them raises an error or a failure.
100
This is particularly useful for reproducing intermittent failures.
102
\fB-z\fR, \fB--random [<seed>]\fR
103
Run the tests in random order using the specified seed.
67
106
Written by Jonathan M. Lange
68
107
.SH "REPORTING BUGS"
69
108
To report a bug, visit \fIhttp://twistedmatrix.com/bugs/\fR
71
Copyright \(co 2003 Matthew W. Lefkowitz
110
Copyright \(co 2003-2006 Twisted Matrix Laboratories
73
112
This is free software; see the source for copying conditions. There is NO
74
113
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
added
removed
doc/man/trial.1
