doc/core/man/trial-man.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   2   <head>
   3 <title>Twisted Documentation: TRIAL.1</title>
   4 <link href="../howto/stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">TRIAL.1</h1>
   9     <div class="toc"><ol><li><a href="#auto0">NAME</a></li><li><a href="#auto1">SYNOPSIS</a></li><li><a href="#auto2">DESCRIPTION</a></li><li><a href="#auto3">OPTIONS</a></li><li><a href="#auto4">SEE ALSO</a></li><li><a href="#auto5">AUTHOR</a></li><li><a href="#auto6">REPORTING BUGS</a></li><li><a href="#auto7">COPYRIGHT</a></li></ol></div>
  10     <div class="content">
  11
  12 <span/>
  13
  14 <h2>NAME<a name="auto0"/></h2>
  15
  16 <p>trial - run unit tests
  17 </p>
  18
  19 <h2>SYNOPSIS<a name="auto1"/></h2>
  20
  21 <p><strong>trial</strong> [ <em>options</em> ] [ <em>file</em> | <em>package</em> | <em>module</em> | <em>TestCase</em> | <em>testmethod</em> ] ...
  22 </p>
  23
  24 <p><strong>trial --help</strong> | <strong>-h</strong>
  25 </p>
  26
  27 <h2>DESCRIPTION<a name="auto2"/></h2>
  28
  29 <p>trial loads and executes a suite of unit tests, obtained from modules,
  30 packages and files listed on the command line.
  31 </p>
  32
  33 <p>trial will take either filenames or fully qualified Python names as
  34 arguments.  Thus `trial myproject/foo.py', `trial myproject.foo' and
  35 `trial myproject.foo.SomeTestCase.test_method' are all valid ways to
  36 invoke trial.
  37 </p>
  38
  39 <p>After running the given test suite, the default test reporter prints a summary
  40 of the test run. This consists of the word <q>PASSED</q> (if all tests ran as
  41 expected) or <q>FAILED</q> (if any test behaved unexpectedly) followed by a count of
  42 the different kinds of test results encountered. The possible kinds of test
  43 results includes:
  44 <dl><dt>successes
  45 </dt><dd>Tests that passed all their assertions and completed without error.
  46 These are marked <q>PASSED</q> in the normal test output.
  47 </dd>
  48
  49 <dt>failures
  50 </dt><dd>Tests that failed an assertion, called self.fail() or explicitly raised
  51 self.failureException for some reason. These are marked <q>FAILED</q> in the
  52 normal test output.
  53 </dd>
  54
  55 <dt>errors
  56 </dt><dd>Tests that raised an unexpected exception (including AssertionError),
  57 tests that caused the tearDown() method to raise an exception, tests
  58 that run for longer than the timeout interval, tests that caused
  59 something to call twisted.python.log.err() without subsequently calling
  60 self.flushLoggedErrors(), tests that leave the reactor in an unclean
  61 state, etc. These are marked <q>ERROR</q> in the normal test output.
  62 Note that because errors can be caused after the actual test method
  63 returns, it is possible for a single test to be reported as both an
  64 error and a failure, and hence the total number of test results can be
  65 greater than the total number of tests executed.
  66 </dd>
  67
  68 <dt>skips
  69 </dt><dd>Tests that were skipped, usually because of missing dependencies. These
  70 are marked <q>SKIPPED</q> in the normal test output.
  71 </dd>
  72
  73 <dt>expectedFailures
  74 </dt><dd>Tests that failed, but were expected to fail, usually because the test
  75 is for a feature that hasn't been implemented yet. These are marked
  76 <q>TODO</q> in the normal test output.
  77 </dd>
  78
  79 <dt>unexpectedSuccesses
  80 </dt><dd>Tests that should have been listed under expectedFailures, except that
  81 for some reason the test succeeded. These are marked <q>SUCCESS!?!</q> in
  82 the normal test output.
  83 </dd>
  84
  85 </dl>
  86
  87 </p>
  88
  89 <h2>OPTIONS<a name="auto3"/></h2>
  90
  91 <dl><dt><strong>-b</strong>, <strong>--debug</strong>
  92 </dt><dd>Run the tests in the Python debugger. Also does post-mortem
  93 debugging on exceptions. Will load `.pdbrc' from current directory if
  94 it exists.
  95 </dd>
  96
  97 <dt><strong>-B</strong>, <strong>--debug-stacktraces</strong>
  98 </dt><dd>Report Deferred creation and callback stack traces
  99 </dd>
 100
 101 <dt><strong>--coverage</strong>
 102 </dt><dd>Generate coverage information in the `coverage' subdirectory of the trial temp
 103 directory (`_trial_temp' by default). For each Python module touched by the
 104 execution of the given tests, a file will be created in the coverage directory
 105 named for the module's fully-qualified name with the suffix `.cover'.  For
 106 example, because the trial test runner is written in Python, the coverage
 107 directory will almost always contain a file named `twisted.trial.runner.cover'.
 108
 109 Each `.cover' file contains a copy of the Python source of the module in
 110 question, with a prefix at the beginning of each line containing coverage
 111 information.  For lines that are not executable (blank lines, comments, etc.)
 112 the prefix is blank.  For executable lines that were run in the course of the
 113 test suite, the prefix is a number indicating the number of times that line was
 114 executed.  The string `&gt;&gt;&gt;&gt;&gt;&gt;' prefixes executable lines that were not executed
 115 in the course of the test suite.
 116
 117 Note that this functionality uses Python's sys.settrace() function, so tests
 118 that call sys.settrace() themselves are likely to break trial's coverage
 119 functionality.
 120 </dd>
 121
 122 <dt><strong>--disablegc</strong>
 123 </dt><dd>Disable the garbage collector for the duration of the test run. As each test is
 124 run, trial saves the TestResult objects, which means that Python's garbage
 125 collector has more non-garbage objects to wade through, making each
 126 garbage-collection run slightly slower. Disabling garbage collection entirely
 127 will make some test suites complete faster (contrast --force-gc, below), at the
 128 cost of increasing (possibly greatly) memory consumption. This option also makes
 129 tests slightly more deterministic, which might help debugging in extreme
 130 circumstances.
 131 </dd>
 132
 133 <dt><strong>-e</strong>, <strong>--rterrors</strong>
 134 </dt><dd>Print tracebacks to standard output as soon as they occur
 135 </dd>
 136
 137 <dt><strong>--force-gc</strong>
 138 </dt><dd>Run gc.collect() before and after each test case. This can be used to
 139 isolate errors that occur when objects get collected.  This option would be
 140 the default, except it makes tests run about ten times slower.
 141 </dd>
 142
 143 <dt><strong>-h</strong>, <strong>--help</strong>
 144 </dt><dd>Print a usage message to standard output, then exit.
 145 </dd>
 146
 147 <dt><strong>--help-reporters</strong>
 148 </dt><dd>Print a list of valid reporters to standard output, then exit. Reporters can
 149 be selected with the --reporter option described below.
 150 </dd>
 151
 152 <dt><strong>--help-reactors</strong>
 153 </dt><dd>Print a list of possible reactors to standard output, then exit. Not all listed
 154 reactors are available on every platform. Reactors can be selected with the
 155 --reactor option described below.
 156 </dd>
 157
 158 <dt><strong>-l</strong>, <strong>--logfile</strong> <em>logfile</em>
 159 </dt><dd>Direct the log to a different file. The default file is `test.log'.
 160 <em>logfile</em> is relative to _trial_temp.
 161 </dd>
 162
 163 <dt><strong>-n</strong>, <strong>--dry-run</strong>
 164 </dt><dd>Go through all the tests and make them pass without running.
 165 </dd>
 166
 167 <dt><strong>-N</strong>, <strong>--no-recurse</strong>
 168 </dt><dd>By default, trial recurses through packages to find every module inside
 169 every subpackage.  Unless, that is, you specify this option.
 170 </dd>
 171
 172 <dt><strong>--nopm</strong>
 173 </dt><dd>Don't automatically jump into debugger for post-mortem analysis of
 174 exceptions.  Only usable in conjunction with --debug.
 175 </dd>
 176
 177 <dt><strong>--profile</strong>
 178 </dt><dd>Run tests under the Python profiler.
 179 </dd>
 180
 181 <dt><strong>-r</strong>, <strong>--reactor</strong> <em>reactor</em>
 182 </dt><dd>Choose which reactor to use.  See --help-reactors for a list.
 183 </dd>
 184
 185 <dt><strong>--recursionlimit</strong>
 186 </dt><dd>Set Python's recursion limit. See sys.setrecursionlimit()
 187 </dd>
 188
 189 <dt><strong>--reporter</strong>
 190 </dt><dd>Select the reporter to use for trial's output.  Use the --help-reporters
 191 option to see a list of valid reporters.
 192 </dd>
 193
 194 <dt><strong>--spew</strong>
 195 </dt><dd>Print an insanely verbose log of everything that happens. Useful when
 196 debugging freezes or locks in complex code.
 197 </dd>
 198
 199 <dt><strong>--tbformat</strong> <em>format</em>
 200 </dt><dd>Format to display tracebacks with. Acceptable values are `default', `brief'
 201 and `verbose'. `brief' produces tracebacks that play nicely with Emacs' GUD.
 202 </dd>
 203
 204 <dt><strong>--temp-directory</strong> <em>directory</em>
 205 </dt><dd>WARNING: Do not use this options unless you know what you are doing.
 206 By default, trial creates a directory called _trial_temp under the current
 207 working directory.  When trial runs, it first <em>deletes</em> this directory,
 208 then creates it, then changes into the directory to run the tests. The log
 209 file and any coverage files are stored here. Use this option if you wish to
 210 have trial run in a directory other than _trial_temp. Be warned, trial
 211 will <em>delete</em> the directory before re-creating it.
 212 </dd>
 213
 214 <dt><strong>--testmodule</strong> <em>filename</em>
 215 </dt><dd>Ask trial to look into <em>filename</em> and run any tests specified using the
 216 Emacs-style buffer variable `test-case-name'.
 217 </dd>
 218
 219 <dt><strong>--unclean-warnings</strong>
 220 </dt><dd>As of Twisted 8.0, trial will report an error if the reactor is left unclean
 221 at the end of the test. This option is provided to assist in migrating from
 222 Twisted 2.5 to Twisted 8.0 and later. Enabling this option will turn the errors
 223 into warnings.
 224 </dd>
 225
 226 <dt><strong>-u</strong>, <strong>--until-failure</strong>
 227 </dt><dd>Keep looping the tests until one of them raises an error or a failure.
 228 This is particularly useful for reproducing intermittent failures.
 229 </dd>
 230
 231 <dt><strong>--version</strong>
 232 </dt><dd>Prints the Twisted version number and exit.
 233 </dd>
 234
 235 <dt><strong>--without-module</strong> <em>modulenames</em>
 236 </dt><dd>Simulate the lack of the specified comma-separated list of modules. This makes
 237 it look like the modules are not present in the system, causing tests to check
 238 the behavior for that configuration.
 239 </dd>
 240
 241 <dt><strong>-z</strong>, <strong>--random</strong> [<em>seed</em>]
 242 </dt><dd>Run the tests in random order using the specified seed.
 243 </dd>
 244
 245 </dl>
 246
 247 <h2>SEE ALSO<a name="auto4"/></h2>
 248
 249 <p>The latest version of the trial documentation can be found at
 250 http://twistedmatrix.com/documents/current/core/howto/testing.html
 251 </p>
 252
 253 <h2>AUTHOR<a name="auto5"/></h2>
 254
 255 <p>Written by Jonathan M. Lange
 256 </p>
 257
 258 <h2>REPORTING BUGS<a name="auto6"/></h2>
 259
 260 <p>To report a bug, visit http://twistedmatrix.com/trac/newticket
 261 </p>
 262
 263 <h2>COPYRIGHT<a name="auto7"/></h2>
 264
 265 <p>Copyright © 2003-2011 Twisted Matrix Laboratories
 266 This is free software; see the source for copying conditions.  There is NO
 267 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 268 </p>
 269
 270 </div>
 271
 272     <p><a href="../howto/index.html">Index</a></p>
 273     <span class="version">Version: 12.1.0</span>
 274   </body>
 275 </html>