doc/core/man/trial.1

   1 .TH TRIAL "1" "Oct 2007" "" ""
   2 .SH NAME
   3 trial \- run unit tests
   4 .SH SYNOPSIS
   5 \fBtrial\fR [ \fIoptions\fR ] [ \fIfile\fR | \fIpackage\fR | \fImodule\fR | \fITestCase\fR | \fItestmethod\fR ] ...
   6 .PP
   7 \fBtrial --help\fR | \fB-h\fR
   8 .SH DESCRIPTION
   9 .PP
  10 trial loads and executes a suite of unit tests, obtained from modules,
  11 packages and files listed on the command line.
  12 .PP
  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
  16 invoke trial.
  17 .PP
  18 After running the given test suite, the default test reporter prints a summary
  19 of the test run. This consists of the word "PASSED" (if all tests ran as
  20 expected) or "FAILED" (if any test behaved unexpectedly) followed by a count of
  21 the different kinds of test results encountered. The possible kinds of test
  22 results includes:
  23 .TP
  24 successes
  25 Tests that passed all their assertions and completed without error.
  26 These are marked "PASSED" in the normal test output.
  27 .TP
  28 failures
  29 Tests that failed an assertion, called self.fail() or explicitly raised
  30 self.failureException for some reason. These are marked "FAILED" in the
  31 normal test output.
  32 .TP
  33 errors
  34 Tests that raised an unexpected exception (including AssertionError),
  35 tests that caused the tearDown() method to raise an exception, tests
  36 that run for longer than the timeout interval, tests that caused
  37 something to call twisted.python.log.err() without subsequently calling
  38 self.flushLoggedErrors(), tests that leave the reactor in an unclean
  39 state, etc. These are marked "ERROR" in the normal test output.
  40 .IP
  41 Note that because errors can be caused after the actual test method
  42 returns, it is possible for a single test to be reported as both an
  43 error and a failure, and hence the total number of test results can be
  44 greater than the total number of tests executed.
  45 .TP
  46 skips
  47 Tests that were skipped, usually because of missing dependencies. These
  48 are marked "SKIPPED" in the normal test output.
  49 .TP
  50 expectedFailures
  51 Tests that failed, but were expected to fail, usually because the test
  52 is for a feature that hasn't been implemented yet. These are marked
  53 "TODO" in the normal test output.
  54 .TP
  55 unexpectedSuccesses
  56 Tests that should have been listed under expectedFailures, except that
  57 for some reason the test succeeded. These are marked "SUCCESS!?!" in
  58 the normal test output.
  59 .SH OPTIONS
  60 .TP
  61 \fB-b\fR, \fB--debug\fR
  62 Run the tests in the Python debugger. Also does post-mortem
  63 debugging on exceptions. Will load `.pdbrc' from current directory if
  64 it exists.
  65 .TP
  66 \fB-B\fR, \fB--debug-stacktraces\fR
  67 Report Deferred creation and callback stack traces
  68 .TP
  69 \fB--coverage\fR
  70 Generate coverage information in the `coverage' subdirectory of the trial temp
  71 directory (`_trial_temp' by default). For each Python module touched by the
  72 execution of the given tests, a file will be created in the coverage directory
  73 named for the module's fully-qualified name with the suffix `.cover'.  For
  74 example, because the trial test runner is written in Python, the coverage
  75 directory will almost always contain a file named `twisted.trial.runner.cover'.
  76
  77 Each `.cover' file contains a copy of the Python source of the module in
  78 question, with a prefix at the beginning of each line containing coverage
  79 information.  For lines that are not executable (blank lines, comments, etc.)
  80 the prefix is blank.  For executable lines that were run in the course of the
  81 test suite, the prefix is a number indicating the number of times that line was
  82 executed.  The string `>>>>>>' prefixes executable lines that were not executed
  83 in the course of the test suite.
  84
  85 Note that this functionality uses Python's sys.settrace() function, so tests
  86 that call sys.settrace() themselves are likely to break trial's coverage
  87 functionality.
  88 .TP
  89 \fB--disablegc\fR
  90 Disable the garbage collector for the duration of the test run. As each test is
  91 run, trial saves the TestResult objects, which means that Python's garbage
  92 collector has more non-garbage objects to wade through, making each
  93 garbage-collection run slightly slower. Disabling garbage collection entirely
  94 will make some test suites complete faster (contrast --force-gc, below), at the
  95 cost of increasing (possibly greatly) memory consumption. This option also makes
  96 tests slightly more deterministic, which might help debugging in extreme
  97 circumstances.
  98 .TP
  99 \fB-e\fR, \fB--rterrors\fR
 100 Print tracebacks to standard output as soon as they occur
 101 .TP
 102 \fB--force-gc\fR
 103 Run gc.collect() before and after each test case. This can be used to
 104 isolate errors that occur when objects get collected.  This option would be
 105 the default, except it makes tests run about ten times slower.
 106 .TP
 107 \fB-h\fR, \fB--help\fR
 108 Print a usage message to standard output, then exit.
 109 .TP
 110 \fB--help-reporters\fR
 111 Print a list of valid reporters to standard output, then exit. Reporters can
 112 be selected with the --reporter option described below.
 113 .TP
 114 \fB--help-reactors\fR
 115 Print a list of possible reactors to standard output, then exit. Not all listed
 116 reactors are available on every platform. Reactors can be selected with the
 117 --reactor option described below.
 118 .TP
 119 \fB-l\fR, \fB--logfile\fR \fIlogfile\fR
 120 Direct the log to a different file. The default file is `test.log'.
 121 \fIlogfile\fR is relative to _trial_temp.
 122 .TP
 123 \fB-n\fR, \fB--dry-run\fR
 124 Go through all the tests and make them pass without running.
 125 .TP
 126 \fB-N\fR, \fB--no-recurse\fR
 127 By default, trial recurses through packages to find every module inside
 128 every subpackage.  Unless, that is, you specify this option.
 129 .TP
 130 \fB--nopm\fR
 131 Don't automatically jump into debugger for post-mortem analysis of
 132 exceptions.  Only usable in conjunction with --debug.
 133 .TP
 134 \fB--profile\fR
 135 Run tests under the Python profiler.
 136 .TP
 137 \fB-r\fR, \fB--reactor\fR \fIreactor\fR
 138 Choose which reactor to use.  See --help-reactors for a list.
 139 .TP
 140 \fB--recursionlimit\fR
 141 Set Python's recursion limit. See sys.setrecursionlimit()
 142 .TP
 143 \fB--reporter\fR
 144 Select the reporter to use for trial's output.  Use the --help-reporters
 145 option to see a list of valid reporters.
 146 .TP
 147 \fB--spew\fR
 148 Print an insanely verbose log of everything that happens. Useful when
 149 debugging freezes or locks in complex code.
 150 .TP
 151 \fB--tbformat\fR \fIformat\fR
 152 Format to display tracebacks with. Acceptable values are `default', `brief'
 153 and `verbose'. `brief' produces tracebacks that play nicely with Emacs' GUD.
 154 .TP
 155 \fB--temp-directory\fR \fIdirectory\fR
 156 WARNING: Do not use this options unless you know what you are doing.
 157 By default, trial creates a directory called _trial_temp under the current
 158 working directory.  When trial runs, it first \fIdeletes\fR this directory,
 159 then creates it, then changes into the directory to run the tests. The log
 160 file and any coverage files are stored here. Use this option if you wish to
 161 have trial run in a directory other than _trial_temp. Be warned, trial
 162 will \fIdelete\fR the directory before re-creating it.
 163 .TP
 164 \fB--testmodule\fR \fIfilename\fR
 165 Ask trial to look into \fIfilename\fR and run any tests specified using the
 166 Emacs-style buffer variable `test-case-name'.
 167 .TP
 168 \fB--unclean-warnings\fR
 169 As of Twisted 8.0, trial will report an error if the reactor is left unclean
 170 at the end of the test. This option is provided to assist in migrating from
 171 Twisted 2.5 to Twisted 8.0 and later. Enabling this option will turn the errors
 172 into warnings.
 173 .TP
 174 \fB-u\fR, \fB--until-failure\fR
 175 Keep looping the tests until one of them raises an error or a failure.
 176 This is particularly useful for reproducing intermittent failures.
 177 .TP
 178 \fB--version\fR
 179 Prints the Twisted version number and exit.
 180 .TP
 181 \fB--without-module\fR \fImodulenames\fR
 182 Simulate the lack of the specified comma-separated list of modules. This makes
 183 it look like the modules are not present in the system, causing tests to check
 184 the behavior for that configuration.
 185 .TP
 186 \fB-z\fR, \fB--random\fR [\fIseed\fR]
 187 Run the tests in random order using the specified seed.
 188 .PP
 189 .SH SEE ALSO
 190 The latest version of the trial documentation can be found at
 191 http://twistedmatrix.com/documents/current/core/howto/testing.html
 192 .SH AUTHOR
 193 Written by Jonathan M. Lange
 194 .SH "REPORTING BUGS"
 195 To report a bug, visit http://twistedmatrix.com/trac/newticket
 196 .SH COPYRIGHT
 197 Copyright \(co 2003-2011 Twisted Matrix Laboratories
 198 .br
 199 This is free software; see the source for copying conditions.  There is NO
 200 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.