tl.testing.thread¶
Working with threads in test code.
Classes¶
-
class
tl.testing.thread.
ExceptionReportingThread
(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)[source]¶ Bases:
tl.testing.thread._ExceptionHandlingThread
Thread implementation which reports exceptions to a test result object.
The reporting-thread class is not useful if instantiated directly; it must be bound to an instance of the
ThreadAwareTestCase
first. It gets thus access to the test result object, to which it will report if an exception occurs in the thread’s business code. AnAssertionError
will be reported as a test failure, any other exception will be reported as a test error.
-
class
tl.testing.thread.
ExceptionSilencingThread
(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)[source]¶ Bases:
tl.testing.thread._ExceptionHandlingThread
Thread implementation which swallows unhandled exceptions.
Swallowing exceptions is useful if it is clear that they are of no interest and shall not mix with more useful test output.
-
class
tl.testing.thread.
ThreadAwareTestCase
(*args)[source]¶ Bases:
unittest.case.TestCase
TestCase implementation that adds some features for handling threads.
While the default
unittest.TestCase
doesn’t concern itself with threading at all, this implementation adds the following:- interplay with threads such that exceptions and failures that occur in a thread get collected along those from the main thread
- reporting of threads left behind by a test
- a convenience helper for running code in a daemon thread
- a convenience helper for counting threads started during the current test method’s execution
The
ThreadAwareTestCase
is instantiated the same way asunittest.TestCase
.-
active_count
()[source]¶ Count threads started during the current test method’s execution.
Returns an integer.
-
run_in_thread
(func, report=True)[source]¶ Run the given function in a daemon thread that handles exceptions.
Using this thread helper is necessary in order for the thread to play with
ThreadAwareTestCase
‘s reporting of errors and failures that occurred in threads.Passing a false value for the
report
option causes unhandled exceptions in the thread to be swallowed instead of reported. This prevents them from appearing in the middle of more interesting test output in the case that they are of no concern themselves.This method starts the thread in daemon mode and blocks until the thread has actually started executing.
Returns the thread object.
-
format_report_on_threads_left_behind
(threads)[source]¶ Formatting hook for the report on threads left behind by a test.
Represent the collection of threads passed to this method as a piece of text useful to a human who operates the test runner. The output of this method is used by the default implementation of the reporting hook,
report_threads_left_behind
.Returns a multi-line string.
-
report_threads_left_behind
(threads)[source]¶ Hook reporting threads left behind by a test to the test runner.
This hook is meant to do whatever the test runner being used needs to be done to display information on the collection of threads passed to this hook. The default implementation is meant for a console test runner: it formats the threads as a piece of text using the
format_report_on_threads_left_behind
hook and prints that to standard output.
-
class
tl.testing.thread.
ThreadJoiner
(timeout, check_alive=True)[source]¶ Bases:
object
Context manager that tries to join any threads started by its suite.
This context manager is instantiated with a mandatory
timeout
parameter and an optionalcheck_alive
switch. The time-out is applied when joining each of the new threads started while executing the context manager’s code suite. Ifcheck_alive
has a true value (the default), aRuntimeError
is raised if a thread is still alive after the attempt to join timed out.Returns an instance of itself upon entering. This instance has a
before
attribute that is a collection of all threads active when the manager was entered. After the manager exited, the instance has another attribute,left_behind
, that is a collection of any threads that could not be joined within the time-out period. The latter is obviously only useful ifcheck_alive
is set to a false value.