Debian Codegraph @

docs/source/traitsui_user_manual/testing/howtos/add_new_interaction.rst

raw
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