Debian Codegraph @

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

raw
1
2 .. _testing-add-new-location:
3
4 Add support for locating a nested GUI element
5 =============================================
6
7 Support for |UIWrapper.locate| can be extended by registering additional
8 location type and resolution logic via |TargetRegistry.register_location| on
9 a |TargetRegistry|.
10
11 Suppose we have a custom UI editor that contains some buttons. The objective of
12 a test is to click a specific button with a given label. We will therefore need
13 to locate the button with the given label before a mouse click can be
14 performed.
15
16 The test code we wanted to achieve looks like this::
17
18 container = UITester().find_by_id(ui, "some_container")
19 button_wrapper = container.locate(LabelledButton("OK"))
20
21 Define the location type
22 ------------------------
23
24 We can define the new ``LabelledButton`` location type::
25
26 class LabelledButton:
27 ''' Locator for locating a push button by label.'''
28 def __init__(self, label):
29 self.label = label
30
31 Identify the target
32 -------------------
33
34 Next, we need to know which object implements the GUI component. This is where
35 implementation details start to come in (see
36 :ref:`testing-target-is-protected`). We can inspect the object being wrapped::
37
38 >>> container._target
39 <package.ui.qt.shiny_panel.ShinyPanel object at 0x7f940a3f10b8>
40 >>> button_wrapper._target
41 <package.ui.qt.shiny_button.ShinyButton object at 0x7fbcc3a63438>
42
43 Implement a solver
44 -------------------
45
46 Say ``ShinyPanel`` keeps track of the buttons with a dictionary called
47 ``_buttons`` where the names of the buttons are the keys of the dictionary.
48 Then the logic to retrieving a button from a
49 label can be written like this::
50
51 def get_button(wrapper, location):
52 """ Returns a ShinyButton from a UIWrapper wrapping ShinyPanel."""
53 # wrapper is an instance of UIWrapper
54 # location is an instance of LabelledButton
55 return wrapper.target._buttons[location.label]
56
57 The solvers can then be registered for the container UI target::
58
59 registry = TargetRegistry()
60 registry.register_location(
61 target_class=ShinyPanel,
62 locator_class=LabelledButton,
63 solver=get_button,
64 )
65
66 Similar to |TargetRegistry.register_interaction|, the signature of
67 ``get_button`` is required by the |TargetRegistry.register_location|
68 method. By setting the ``target_class`` and ``locator_class``, we restrict the
69 types of ``wrapper._target`` and ``location`` received by ``get_button``
70 respectively.
71
72 Apply it
73 --------
74
75 Finally, we can use this registry with |UITester|::
76
77 tester = UITester(registries=[custom_registry])
78
79 If we have also added a custom ``ManyMouseClick`` interaction (see section
80 :ref:`testing-add-new-interaction`), we can write test code like this::
81
82 container = UITester().find_by_id(ui, "some_container")
83 button_wrapper = container.locate(LabelledButton("OK"))
84 button_wrapper.perform(ManyMouseClick(n_times=10))
85
86 where both ``LabelledButton`` and ``ManyMouseClick`` are custom objects.
87
88 .. include:: ../substitutions.rst