Debian Codegraph @

docs/source/traitsui_user_manual/testing/discussions/event_loop_and_exceptions.rst

raw
1 GUI event processing and exception handling
2 ===========================================
3
4 The testing API is designed such that GUI event processing is requested
5 automatically wherever there may be pending GUI events. While events are being
6 processed, the global exception handling is overridden temporarily in order to
7 capture any unhandled exceptions. If any exceptions are caught, a test error
8 is raised after all pending events are processed.
9
10 For example, |UIWrapper.locate|, |UIWrapper.perform| and |UIWrapper.inspect|
11 all request pending events to be processed before and/or after interacting
12 with GUI states. This automatic behavior is enabled by default, but it can be
13 disabled via the |UITester.auto_process_events| flag (see
14 :ref:`testing-with-modal-dialogs` for example).
15
16 Motivation
17 ----------
18
19 In production environments, the GUI event loop typically blocks as it waits
20 and processes new GUI events continuously, until the last window is closed.
21 In tests, the GUI event loop needs to be run programmatically for a limited
22 scope of commands and yield to test instructions every now and then while the
23 GUI is still open.
24
25 In production environments, some unhandled exceptions are tolerated and
26 suppressed by the GUI event loop, but some exceptions could cause the entire
27 runtime to abort abnormally. Neither of these conditions are desirable in
28 tests. Unhandled exceptions typically indicate bugs and should cause a test to
29 error. Abortion of the Python runtime prevents running and collecting
30 results from multiple tests in a test suite.
31
32 .. include:: ../substitutions.rst