Run Twisted Tests Reliably with trial3

You will finish with a repeatable way to run a Twisted test module, select one test when debugging, recognise the difference between failures and errors, and keep Trial's temporary files where you expect them. The examples use the installed trial3 from Twisted 24.3.0, provided here by python3-twisted version 24.3.0-1ubuntu0.2.

Allow about fifteen minutes for a first run. You need a shell, Python code containing Twisted tests, and permission to write in the directory where you start Trial. These commands are ordinary user commands. Nothing in this guide needs sudo.

1. Check the installed runner

Confirm the executable and version before comparing output with another machine:

$ command -v trial3
/usr/bin/trial3
$ trial3 --version
Twisted version: 24.3.0
$ dpkg-query -W -f='${Package} ${Version}\n' python3-twisted
python3-twisted 24.3.0-1ubuntu0.2

Option names and reporter defaults can vary between Twisted releases. The installed command is the useful contract here. Use trial3 --help if a command copied from another system is rejected.

2. Run a module or file

Trial accepts a filename or a fully qualified Python name. From the project directory, start with the smallest test collection that answers your question:

$ trial3 myproject/test/test_parser.py
...
-------------------------------------------------------------------------------
Ran 3 tests in 0.012s

PASSED (successes=3)

The exact progress lines and timing depend on the reporter and test suite. A final PASSED means the tests completed without an unexpected result. Trial normally creates _trial_temp below the current directory, changes into it while running, and places its default test.log there.

You can use the equivalent module form when the package is importable:

$ trial3 myproject.test.test_parser
$ printf 'exit status: %s\n' "$?"
exit status: 0

Pass several targets when order matters. Trial uses the order supplied on the command line, so put a focused module before a broad package rather than letting an accidental collection hide the result.

3. Narrow the run to one test

A fully qualified test case or method is useful when the full suite is noisy or slow. For example:

$ trial3 myproject.test.test_parser.ParserTests.test_empty_input
test_empty_input ...                                             [OK]

PASSED (successes=1)

The name must match the Python object that Trial can import. If it cannot find the module, case or method, check the package path and spelling before changing options. A narrow run is a diagnostic aid, not proof that the surrounding suite still passes.

By default, test methods in a TestCase run alphabetically. Ask Trial which ordering modes are available with trial3 --help-orders. To reproduce an order-dependent problem, use a specific order rather than relying on a remembered default.

4. Read the result categories correctly

Trial distinguishes several outcomes:

• successes passed their assertions and completed normally.
• failures made an assertion fail or called the test failure method.
• errors raised an unexpected exception, left the reactor unclean, exceeded a timeout, or produced another framework-level problem.
• skips were deliberately not run, often because a dependency was unavailable.
• expectedFailures failed in a way the test marked as expected.
• unexpectedSuccesses passed even though they were marked as expected failures.

Both failures and errors make the overall run unsuccessful. An error can be reported after the test method returns, so the count of result records can be greater than the number of test methods. Read the traceback and the reactor-cleanliness message together instead of fixing only the first assertion shown.

5. Choose useful diagnostics

For long-running work, -e or --rterrors prints tracebacks as they occur:

$ trial3 --rterrors myproject.test.test_parser
# traceback output appears when an error occurs
$ printf 'exit status: %s\n' "$?"
exit status: 1

Use -x or --exitfirst to stop after the first failure, error or unexpected success. This is useful for a quick feedback loop, but it cannot tell you whether later tests also fail. Do not combine it with --jobs; the installed help marks those options as incompatible.

For a test that sometimes fails, -u or --until-failure repeats the collection until an error or failure occurs:

$ trial3 --until-failure myproject.test.test_parser
# the run repeats until Trial records an error or failure

Stop it with the shell interrupt key when you have enough evidence. This mode can run indefinitely and may exercise external services repeatedly, so avoid using it against production endpoints or tests that change shared data.

6. Control parallelism and coverage

-j 2 starts two local process workers. Parallel execution can shorten an independent suite, but tests that share files, ports, databases or global reactor state may behave differently. Establish a serial baseline first. The options for debugging, stopping at the first result and profiling conflict with jobs in the installed runner.

--coverage writes per-module coverage files under a coverage directory inside Trial's temporary directory. These files contain annotated source, including lines that were not executed. Coverage is evidence about exercised lines, not a guarantee that the assertions are meaningful:

$ trial3 --coverage myproject.test.test_parser
$ find _trial_temp/coverage -type f -name '*.cover' -print
_trial_temp/coverage/myproject.test_parser.cover

7. Protect the temporary directory

Use a disposable, deliberately named directory when you need isolation:

$ trial3 --temp-directory /tmp/trial3-check-12345 myproject.test.test_parser
# inspect /tmp/trial3-check-12345 while diagnosing this run

Replace the example path with a directory you have checked and reserved for Trial. After you have saved any useful log or coverage file, remove that disposable directory with an explicit path, or leave it for later inspection. Never use a home directory, project root or shared data directory as the temporary directory.

There is no test-state rollback command. If your tests modify a database, filesystem or service, recovery belongs to that test fixture or service's own backup procedure. Trial only manages its runner workspace.