| 1 |
|
| 2 |
.. _testing-add-new-interaction: |
| 3 |
|
| 4 |
Add support for performing actions or inspecting states |
| 5 |
======================================================= |
| 6 |
|
| 7 |
Support for |UIWrapper.perform| and |UIWrapper.inspect| can be extended by |
| 8 |
registering additional interaction type and handling logic via |
| 9 |
|TargetRegistry.register_interaction| on a |TargetRegistry|. |
| 10 |
|
| 11 |
Suppose we want to perform many mouse clicks on a UI component in a test, but |
| 12 |
instead of calling ``perform(MouseClick())`` many times in a loop like this:: |
| 13 |
|
| 14 |
my_widget = UITester().find_by_id(ui, "some_id") |
| 15 |
for _ in range(10): |
| 16 |
my_widget.perform(MouseClick()) |
| 17 |
|
| 18 |
We want to exercise the mouse click many times by invoking |UIWrapper.perform| |
| 19 |
once only:: |
| 20 |
|
| 21 |
my_widget = UITester().find_by_id(ui, "some_id") |
| 22 |
my_widget.perform(ManyMouseClick(n_times=10)) |
| 23 |
|
| 24 |
Define the interaction |
| 25 |
---------------------- |
| 26 |
|
| 27 |
We can define this ``ManyMouseClick`` object simply like this:: |
| 28 |
|
| 29 |
class ManyMouseClick: |
| 30 |
def __init__(self, n_times): |
| 31 |
self.n_times = n_times |
| 32 |
|
| 33 |
Identify the target |
| 34 |
------------------- |
| 35 |
|
| 36 |
Next, we need to know which object implements the GUI component. This is where |
| 37 |
implementation details start to come in (see |
| 38 |
:ref:`testing-target-is-protected`). We can inspect the object being wrapped:: |
| 39 |
|
| 40 |
>>> my_widget |
| 41 |
<traitsui.testing.tester.ui_wrapper.UIWrapper object at 0x7f940a3f10b8> |
| 42 |
>>> my_widget._target |
| 43 |
<package.ui.qt.shiny_button.ShinyButton object at 0x7fc90fb3b570> |
| 44 |
|
| 45 |
The target is an instance of a ``ShinyButton`` class (made up |
| 46 |
for this document). In this object, there is an instance of Qt QPushButton |
| 47 |
widget which we want to click with the mouse:: |
| 48 |
|
| 49 |
>>> my_widget._target.control |
| 50 |
<PyQt5.QtWidgets.QPushButton object at 0x7fbcc3ac3558> |
| 51 |
|
| 52 |
Implement a handler |
| 53 |
------------------- |
| 54 |
|
| 55 |
So now all we need to do, is to tell |UITester| how to perform |
| 56 |
``ManyMouseClick`` on an instance of ``ShinyButton``. |
| 57 |
|
| 58 |
We define a function to perform the mouse clicks:: |
| 59 |
|
| 60 |
def many_mouse_click(wrapper, interaction): |
| 61 |
# wrapper is an instance of UIWrapper |
| 62 |
# interaction is an instance of ManyMouseClick |
| 63 |
for _ in range(interaction.n_times): |
| 64 |
wrapper._target.control.click() |
| 65 |
|
| 66 |
Then we need to register this function with an instance of |TargetRegistry|:: |
| 67 |
|
| 68 |
from traitsui.testing.api import TargetRegistry |
| 69 |
from package.ui.qt.shiny_button import ShinyButton |
| 70 |
|
| 71 |
custom_registry = TargetRegistry() |
| 72 |
custom_registry.register_interaction( |
| 73 |
target_class=ShinyButton, |
| 74 |
interaction_class=ManyMouseClick, |
| 75 |
handler=many_mouse_click, |
| 76 |
) |
| 77 |
|
| 78 |
The signature of ``many_mouse_click`` is required by the |TargetRegistry.register_interaction| |
| 79 |
method on |TargetRegistry|. By setting the ``target_class`` and |
| 80 |
``interaction_class``, we restrict the types of ``wrapper._target`` and |
| 81 |
``interaction`` received by ``many_mouse_click`` respectively. |
| 82 |
|
| 83 |
Apply it |
| 84 |
-------- |
| 85 |
|
| 86 |
Finally, we can use this registry with the |UITester|:: |
| 87 |
|
| 88 |
tester = UITester(registries=[custom_registry]) |
| 89 |
my_widget = tester.find_by_id(ui, "some_id") |
| 90 |
my_widget.perform(ManyMouseClick(n_times=10)) |
| 91 |
|
| 92 |
All the builtin testing support for TraitsUI editors are still present, but now |
| 93 |
this tester can perform the additional, custom user interaction. |
| 94 |
|
| 95 |
Inspecting states |
| 96 |
----------------- |
| 97 |
|
| 98 |
The distinction between |UIWrapper.perform| and |UIWrapper.inspect| is merely |
| 99 |
in their returned values. |
| 100 |
|
| 101 |
We can call |UIWrapper.inspect| with the ``ManyMouseClick`` object we just |
| 102 |
created:: |
| 103 |
|
| 104 |
value = my_widget.inspect(ManyMouseClick(n_times=10)) |
| 105 |
|
| 106 |
The returned value is the value returned by ``many_mouse_click``, the handler |
| 107 |
registered for ``ManyMouseClick`` and ``ShinyButton``. In this case, the |
| 108 |
value is ``None``. |
| 109 |
|
| 110 |
|
| 111 |
.. include:: ../substitutions.rst |