Testing Traits Futures code¶
This section gives some hints and tips for unit-testing code that uses Traits Futures. Those tests face two main challenges:
By design, Traits Futures relies on a running GUI event loop; that typically means that each test that uses Traits Futures will need to find some way to run the event loop in order for futures to deliver their results.
It’s important to fully shut down executors after each test, to avoid leaked threads and potential for test interactions.
An example test¶
example of testing a simple
""" Example of testing a simple future using the GuiTestAssistant. """ import unittest from pyface.toolkit import toolkit_object from traits_futures.api import submit_call, TraitsExecutor #: Maximum timeout for blocking calls, in seconds. A successful test should #: never hit this timeout - it's there to prevent a failing test from hanging #: forever and blocking the rest of the test suite. SAFETY_TIMEOUT = 5.0 #: Note that the GuiTestAssistant is currently only available for Qt, not #: for wxPython. To run this unit test, you'll need PyQt or PySide 2 installed. GuiTestAssistant = toolkit_object("util.gui_test_assistant:GuiTestAssistant") class TestMyFuture(GuiTestAssistant, unittest.TestCase): def setUp(self): GuiTestAssistant.setUp(self) self.traits_executor = TraitsExecutor() def tearDown(self): # Request the executor to stop, and wait for that stop to complete. self.traits_executor.shutdown(timeout=SAFETY_TIMEOUT) GuiTestAssistant.tearDown(self) def test_my_future(self): future = submit_call(self.traits_executor, pow, 3, 5) # Wait for the future to complete. self.assertEventuallyTrueInGui( lambda: future.done, timeout=SAFETY_TIMEOUT ) self.assertEqual(future.result, 243) if __name__ == "__main__": unittest.main()
Some points of interest in the above example:
In order for the result of our future execution to be delivered to the main thread (a.k.a. the GUI thread), the event loop for the main thread needs to be running. We make use of the
GuiTestAssistantclass from Pyface to make it easy to run the event loop until a particular condition occurs.
In the main test method, after submitting the call and receiving the
futurefuture, we want to wait until the future has completed and all communications from the background task have completed. We do that by using the
assertEventuallyTrueInGuimethod. At that point, we can check that the result of the future is the expected one.
We also need to shut down the executor itself at the end of the test; we use the
shutdownmethod for this.
In all potentially blocking calls, we provide a timeout. This should help prevent a failing test from blocking the entire test run if something goes wrong. However, note that if the timeout on the
shutdownmethod fails then in addition to the test failing you may see segmentation faults or other peculiar side-effects, especially at process termination time, as a result of pieces of cleanup occurring out of order.
If you don’t need the result of the future (for example because you’re using
the future for its side-effect rather than to perform a computation) then it’s
safe to remove the wait for
future.done, so long as you keep the