TRIAL(1)

✨ NAME ✨

okay so trial (the manual page for trial(1)) is the thing that runs unit tests 🧪💖. bestie, this is your sign to learn it.

💅 SYNOPSIS 💅

trial [ options ] [ file | package | module | TestCase | testmethod ]
...

trial --help | -h

🌸 DESCRIPTION 🌸

okay so trial loads and runs a whole suite of unit tests 🦋, pulled from modules, packages and files you list on the command line. it's giving organized ✨.

trial will take either filenames or fully qualified Python names as arguments. so trial myproject/foo.py, trial myproject.foo and trial myproject.foo.SomeTestCase.test_method are all valid ways to call it 🫶. you can pass multiple arguments too, and their order decides the order the tests run in. main character energy 👑.

After running the suite, the default test reporter drops a summary 📝. it starts with the word "PASSED" (if every test ran as expected) or "FAILED" (if any test acted up 💀), followed by a count of each kind of result. the possible kinds of results are:

• successes — tests that passed all their assertions and finished without any error 🎀. these get marked "PASSED" in the normal output.
• failures — tests that failed an assertion, called self.fail(), or explicitly raised self.failureException for some reason 😭. these get marked "FAILED" in the normal output.
• errors — tests that raised an unexpected exception (including AssertionError) 💀, tests that made tearDown() raise an exception, tests that ran longer than the timeout interval ⏰, tests that caused something to call twisted.python.log.err() without then calling self.flushLoggedErrors(), tests that left the reactor in an unclean state, and so on 🙈. these get marked "ERROR" in the normal output.

ngl the errors one is a lot. because errors can happen after the actual test method returns, a single test can be reported as both an error and a failure. so the total number of results can be bigger than the number of tests that actually ran 🌈.

• skips — tests that got skipped, usually because of missing dependencies 🍓. these get marked "SKIPPED" in the normal output.
• expectedFailures — tests that failed, but were expected to fail, usually because the test is for a feature that hasn't been built yet 🧚. these get marked "TODO" in the normal output.
• unexpectedSuccesses — tests that should've been listed under expectedFailures, except for some reason the test succeeded 😳. these get marked "SUCCESS!?!" in the normal output.

🎀 OPTIONS 🎀

• -j, --jobs number — sets how many process workers run. it conflicts with the debug, exitfirst and profile options 🚫.
• -b, --debug — runs the tests in a debugger 🐛. if that debugger is pdb (the default when nothing's specified), a .pdbrc gets loaded from the current directory if it exists. also does post-mortem debugging on exceptions 🔍.
• -B, --debug-stacktraces — reports Deferred creation and callback stack traces 🦋.
• --coverage — generates coverage info in the coverage subdirectory of the trial temp directory (_trial_temp by default) 📊. for each Python module touched by the given tests, a file gets created in the coverage directory, named after the module's fully-qualified name with the suffix .cover. for example, since 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 has a copy of the module's Python source, with a prefix at the start of each line holding coverage info 💜. non-executable lines (blank lines, comments, etc.) get a blank prefix. executable lines that ran during the suite get a number showing how many times they ran 🔢. the string >>>>>> prefixes executable lines that did not run during the suite 😬.

heads up: this uses Python's sys.settrace() function, so tests that call sys.settrace() themselves are likely to break trial's coverage functionality ⚠️.

• --debugger — picks the debugger to use when --debug 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 — turns off the garbage collector for the whole test run 🗑️. every time a test runs, trial saves the TestResult objects, so Python's garbage collector has more non-garbage objects to wade through, which makes each collection a bit slower. disabling GC entirely can make some suites finish faster (compare --force-gc below), but it can increase memory consumption (possibly greatly) 📈. this option also makes tests a little more deterministic, which might help debugging in extreme circumstances 🔬.
• -e, --rterrors — prints tracebacks to standard output as soon as they happen 🚨.
• --force-gc — runs gc.collect() before and after each test case 🧹. this can help isolate errors that happen when objects get collected. this would be the default, except it makes tests run about ten times slower 🐢.
• -h, --help — prints a usage message to standard output, then exits 👋.
• --help-order — prints a list of the possible orders that TestCase test methods can run in, then exits 📋. the orders can be used with the --order option below.
• --help-reporters — prints a list of valid reporters to standard output, then exits 📣. reporters can be selected with the --reporter option below.
• --help-reactors — prints a list of possible reactors to standard output, then exits ⚛️. not every listed reactor is available on every platform, so heads up 🙃. reactors can be selected with the --reactor option below.
• -l, --logfile logfile — sends the log to a different file 📂. the default file is test.log. logfile is relative to _trial_temp.
• -n, --dry-run — goes through all the tests and makes them pass without actually running them 🪄.
• -N, --no-recurse — by default, trial recurses through packages to find every module inside every subpackage 🔁. unless, that is, you specify this option 🙅.
• --nopm — stops trial from automatically jumping into the debugger for post-mortem analysis of exceptions 🚫. only usable together with --debug.
• --order order — specifies what order to run the individual test methods within the given TestCases in 🔀. by default they run alphabetically. see --help-order for a list of other valid values.
• --profile — runs tests under the Python profiler 🕵️.
• -r, --reactor reactor — chooses which reactor to use 🎛️. see --help-reactors for a list.
• --recursionlimit limit — sets Python's recursion limit 🌀. see sys.setrecursionlimit().
• --reporter reporter — selects the reporter for trial's output 📰. use the --help-reporters option to see a list of valid reporters.
• -x, --exitfirst — stops the test run after the first test that doesn't succeed 🛑. that includes failures, errors, or unexpected successes. won't work with the --jobs option currently 😤.
• --spew — prints an insanely verbose log of everything that happens 🌊. useful when debugging freezes or locks in complex code 🧊.
• --tbformat format — the 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're 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 it to run the tests 🗂️. the log file and any coverage files are stored here. use this option if you want trial to run in a directory other than _trial_temp. be warned: trial will delete the directory before re-creating it 💀.

• --testmodule filename — asks 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 reports an error if the reactor is left unclean at the end of a test 🧽. this option helps with migrating from Twisted 2.5 to Twisted 8.0 and later, and turns those errors into warnings ⚠️.
• -u, --until-failure — keeps looping the tests until one of them raises an error or a failure 🔁. super useful for reproducing intermittent failures 🫠.
• --version — prints the Twisted version number and exits 🏷️.
• --without-module modulenames — simulates the lack of the specified comma-separated list of modules 🫥. it makes it look like those modules aren't present on the system, so tests can check behaviour for that configuration 🧪.
• -z, --random seed — runs the tests in random order using the specified seed 🎲. don't pass this option if you're also passing --order 🙅‍♀️.

🦋 SEE ALSO 🦋

the latest version of the trial documentation lives 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 🥺.

---

bestie that's the whole trial(1) page 🎀. it's from Jun 2013 and it's part of TRIAL(1) 💖. go run your tests and slay them all 🔥✨.