| 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 |