Debian Codegraph @

docs/source/traitsui_user_manual/testing/tutorials/test_with_nested_object.rst

raw
1
2 Testing with nested objects
3 ===========================
4
5 Suppose we have a GUI application like this::
6
7 from traits.api import Enum, HasStrictTraits, Instance, Float, observe, Str
8 from traitsui.api import Item, InstanceEditor, View
9
10
11 class PayCheck(HasStrictTraits):
12
13 name = Str()
14 pay = Float()
15
16
17 class App(HasStrictTraits):
18
19 min_hourly_wage = Float(10.0)
20 n_hours = Enum([25, 40, 45])
21 pay_check = Instance(PayCheck)
22
23 def _pay_check_default(self):
24 return PayCheck(pay=self.min_hourly_wage*self.n_hours)
25
26 @observe("min_hourly_wage")
27 @observe("n_hours")
28 def _pay_updated(self, event):
29 self.pay_check.pay = self.min_hourly_wage * self.n_hours
30
31 view = View(
32 Item("min_hourly_wage", label="Hourly wage"),
33 Item("n_hours", label="Number of work hours"),
34 Item("pay_check", editor=InstanceEditor(), style="custom"),
35 )
36
37 app = App()
38 app.configure_traits()
39
40
41 .. figure:: images/test_with_nested_object/init-app.png
42
43
44 When the user selects a different number of work hours in the combo box, the
45 pay is updated accordingly. This behavior is simple enough to be tested
46 without GUI, but we will to write a GUI test for demonstration purposes.
47
48 The test will need to:
49
50 #. Find the combo box for the number of work hours field
51 #. Locate a different item in the combo box
52 #. Click that item to modify the number of work hours
53 #. Find the nested 'pay' field inside 'PayCheck'
54 #. Check the pay is updated to the expected value
55
56
57 Step 1: Find the combo box for the number of work hours field
58 -------------------------------------------------------------
59
60 First of all, find the combo box using the name defined in |Item|::
61
62 from traitsui.testing.api import UITester
63
64 app = App()
65 tester = UITester()
66 with tester.create_ui(app) as ui:
67 n_hours_combobox = tester.find_by_name(ui, "n_hours")
68
69
70 Step 2: Locate a different item in the combo box
71 ------------------------------------------------
72
73 Let's take a look at the functionality supported with this
74 ``n_hours_combobox``.
75
76 .. code-block::
77
78 n_hours_combobox.help()
79
80 prints something like this (abbreviated for the purpose of this section)::
81
82 Interactions
83 ------------
84 <class 'traitsui.testing.tester.command.KeyClick'>
85 An object representing the user clicking a key on the keyboard.
86 ...
87
88 <class 'traitsui.testing.tester.command.KeySequence'>
89 An object representing the user typing a sequence of keys.
90 ...
91
92 <class 'traitsui.testing.tester.query.DisplayedText'>
93 An object representing an interaction to obtain the displayed (echoed)
94 plain text.
95 ...
96
97 <class 'traitsui.testing.tester.query.SelectedText'>
98 An object representing an interaction to obtain the displayed (echoed)
99 plain text which is currently selected.
100
101 E.g. For a Enum List, with one entry currently selected, the displayed
102 selected text would be the label of that entry.
103 ...
104
105 Locations
106 ---------
107 <class 'traitsui.testing.tester.locator.Index'>
108 A locator for locating a target that is uniquely specified by a single
109 0-based index.
110
111 The |Index| object allows us to locate an indexed item on the combo box.
112 Objects listed in the "Locations" section can be used with |UIWrapper.locate|.
113 So we add this line::
114
115 second_item = n_hours_combobox.locate(Index(1))
116
117 Now our test looks like this::
118
119 from traitsui.testing.api import Index, UITester
120
121 app = App()
122 tester = UITester(delay=500)
123 with tester.create_ui(app) as ui:
124 n_hours_combobox = tester.find_by_name(ui, "n_hours")
125 second_item = n_hours_combobox.locate(Index(1))
126
127
128 Step 3: Modify the number of work hours
129 ---------------------------------------
130
131 The returned value of |UIWrapper.locate| is another instance of |UIWrapper|.
132 We can find what are supported on ``second_item`` using the |UIWrapper.help|
133 method again.
134
135 .. code-block::
136
137 second_item.help()
138
139 prints something like this (abbreviated, again)::
140
141 Interactions
142 ------------
143 <class 'traitsui.testing.tester.command.MouseClick'>
144 An object representing the user clicking a mouse button.
145 Currently the left mouse button is assumed.
146
147 ...
148
149 Locations
150 ---------
151 No locations are supported.
152
153
154 This help message indicates that we can click this second item. In our
155 application context, this will select the second item in the combo box::
156
157 second_item.perform(MouseClick())
158
159 Now this is how the test looks like so far::
160
161 from traitsui.testing.api import Index, MouseClick, UITester
162
163 app = App()
164 tester = UITester()
165 with tester.create_ui(app) as ui:
166 n_hours_combobox = tester.find_by_name(ui, "n_hours")
167 second_item = n_hours_combobox.locate(Index(1))
168 second_item.perform(MouseClick())
169
170 Step 4: Find the nested 'pay' field inside 'PayCheck'
171 -----------------------------------------------------
172
173 This step is trickier. The ``pay`` field is nested inside the ``pay_check``
174 item, how do we get to it?
175
176 Let's get the ``pay_check`` object via the tester and see what we have::
177
178 pay_check_pane = tester.find_by_name(ui, "pay_check")
179 pay_check_pane.help()
180
181
182 The last line prints something like this (abbreviated, again)::
183
184 Interactions
185 ------------
186 No interactions are supported.
187
188 Locations
189 ---------
190 <class 'traitsui.testing.tester.locator.TargetById'>
191 A locator for locating the next UI target using an id.
192 ...
193
194 <class 'traitsui.testing.tester.locator.TargetByName'>
195 A locator for locating the next UI target using a name.
196 ...
197
198 We can see that |TargetById| and |TargetByName| are available for
199 locating the next GUI element. We can locate the text box for
200 ``pay_check.pay`` using |TargetByName|::
201
202 pay_field = pay_check_pane.locate(TargetByName("pay"))
203
204
205 In fact, |UIWrapper.find_by_id| and |UIWrapper.find_by_name| are simply
206 aliases for |TargetById| and |TargetByName| respectively, so you
207 can also write::
208
209 pay_field = pay_check_pane.find_by_name("pay")
210
211
212 Now this is how the test looks like so far::
213
214 from traitsui.testing.api import Index, MouseClick, UITester
215
216 app = App()
217 tester = UITester()
218 with tester.create_ui(app) as ui:
219 n_hours_combobox = tester.find_by_name(ui, "n_hours")
220 n_hours_combobox.locate(Index(1)).perform(MouseClick())
221
222 pay_field = tester.find_by_name(ui, "pay_check").find_by_name("pay")
223
224 Step 5: Check the pay is updated to the expected value
225 ------------------------------------------------------
226
227 ``pay_field`` wraps a text box. We have seen in
228 :ref:`testing-tutorial-first-test` how to obtain the displayed text::
229
230 from traitsui.testing.api import DisplayedText
231 displayed_pay = pay_field.inspect(DisplayedText())
232 assert displayed_pay == "400.0"
233
234
235 Our final test
236 --------------
237
238 .. code-block::
239
240 from traitsui.testing.api import Index, DisplayedText, MouseClick, UITester
241
242 app = App()
243 tester = UITester()
244 with tester.create_ui(app) as ui:
245
246 n_hours_combobox = tester.find_by_name(ui, "n_hours")
247 n_hours_combobox.locate(Index(1)).perform(MouseClick())
248
249 pay_field = tester.find_by_name(ui, "pay_check").find_by_name("pay")
250 displayed_pay = pay_field.inspect(DisplayedText())
251
252 assert displayed_pay == "400.0"
253
254
255 What did we learn?
256 ------------------
257
258 - From the output of |UIWrapper.help|, objects listed in the "Locations" can be
259 used with |UIWrapper.locate| for locating nested GUI components.
260 - |UIWrapper.find_by_name| and |UIWrapper.find_by_id| are aliases making use
261 of the |UIWrapper.locate| method.
262 - |UIWrapper.locate| returns an instance of |UIWrapper| on which
263 |UIWrapper.locate| can be called again; |UIWrapper.perform| and
264 |UIWrapper.inspect| can be used on the nested object located.
265
266
267 .. include:: ../substitutions.rst