trial(1)
NAME
trial - run unit tests
SYNOPSIS
trial [ options ] [ file | package | module | TestCase | testmethod ] ... trial --help | -h
DESCRIPTION
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.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.
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:
successes
Tests that passed all their assertions and completed without
error. These are marked "PASSED" in the normal test output.
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.
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
executed.
skips Tests that were skipped, usually because of missing
dependencies. These are marked "SKIPPED" in the normal test
output.
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.
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.
OPTIONS
-j, --jobs number
Set the number of process workers to run. It conflicts with the
debug, exitfirst and profile options.
-b, --debug
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.
-B, --debug-stacktraces
Report Deferred creation and callback stack traces.
--coverage
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.
--debugger
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'.
--disablegc
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.
-e, --rterrors
Print tracebacks to standard output as soon as they occur.
--force-gc
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.
-h, --help
Print a usage message to standard output, then exit.
--help-order
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.
--help-reporters
Print a list of valid reporters to standard output, then exit.
Reporters can be selected with the --reporter option described
below.
--help-reactors
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.
-l, --logfile logfile
Direct the log to a different file. The default file is
`test.log'. logfile is relative to _trial_temp.
-n, --dry-run
Go through all the tests and make them pass without running.
-N, --no-recurse
By default, trial recurses through packages to find every module
inside every subpackage. 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.
--order order
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.
--profile
Run tests under the Python profiler.
-r, --reactor reactor
Choose which reactor to use. See --help-reactors for a list.
--recursionlimit limit
Set Python's recursion limit. See sys.setrecursionlimit().
--reporter reporter
Select the reporter to use for trial's output. Use the --help-
reporters option to see a list of valid reporters.
-x, --exitfirst
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.
--spew Print an insanely verbose log of everything that happens. Useful
when debugging freezes or locks in complex code.
--tbformat format
Format to display tracebacks with. Acceptable values are
`default', `brief' and `verbose'. `brief' produces tracebacks
that play nicely with Emacs' GUD.
--temp-directory directory
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
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.
--testmodule filename
Ask trial to look into filename and run any tests specified
using the Emacs-style buffer variable `test-case-name'.
--unclean-warnings
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.
-u, --until-failure
Keep looping the tests until one of them raises an error or a
failure. This is particularly useful for reproducing
intermittent failures.
--version
Prints the Twisted version number and exit.
--without-module modulenames
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. Don't
pass this option if you also are passing --order.
SEE ALSO
The latest version of the trial documentation can be found at http://twistedmatrix.com/documents/current/core/howto/testing.html
AUTHOR
Written by Jonathan M. Lange
REPORTING BUGS
To report a bug, visit http://twistedmatrix.com/trac/newticket
COPYRIGHT
Copyright 2003-2013 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.
Jun 2013 TRIAL(1)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
