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