Debian Codegraph @

tests/unit_tests/test_structural_navigator.py

raw
1 # Unit tests for structural_navigator.py methods.
2 #
3 # Copyright 2025 Igalia, S.L.
4 # Author: Joanmarie Diggs <[email protected]>
5 #
6 # This library is free software; you can redistribute it and/or
7 # modify it under the terms of the GNU Lesser General Public
8 # License as published by the Free Software Foundation; either
9 # version 2.1 of the License, or (at your option) any later version.
10 #
11 # This library is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 # Lesser General Public License for more details.
15 #
16 # You should have received a copy of the GNU Lesser General Public
17 # License along with this library; if not, write to the
18 # Free Software Foundation, Inc., Franklin Street, Fifth Floor,
19 # Boston MA 02110-1301 USA.
20
21 # pylint: disable=wrong-import-position
22 # pylint: disable=import-outside-toplevel
23 # pylint: disable=too-many-public-methods
24 # pylint: disable=too-many-statements
25 # pylint: disable=protected-access
26 # pylint: disable=too-many-arguments
27 # pylint: disable=too-many-positional-arguments
28 # pylint: disable=too-many-locals
29 # pylint: disable=too-many-lines
30
31 """Unit tests for structural_navigator.py methods."""
32
33 from __future__ import annotations
34
35 from typing import TYPE_CHECKING
36
37 import gi
38 import pytest
39
40 gi.require_version("Atspi", "2.0")
41 from gi.repository import Atspi
42
43 if TYPE_CHECKING:
44 from .orca_test_context import OrcaTestContext
45
46
47 @pytest.mark.unit
48 class TestStructuralNavigator:
49 """Test StructuralNavigator class methods."""
50
51 def _setup_dependencies(self, test_context):
52 """Set up dependencies for structural_navigator module testing."""
53
54 additional_modules = [
55 "orca.cmdnames",
56 "orca.command_manager",
57 "orca.dbus_service",
58 "orca.debug",
59 "orca.focus_manager",
60 "orca.guilabels",
61 "orca.input_event_manager",
62 "orca.keybindings",
63 "orca.messages",
64 "orca.object_properties",
65 "orca.orca_gui_navlist",
66 "orca.orca_i18n",
67 "orca.script_manager",
68 "orca.AXHypertext",
69 "orca.AXObject",
70 "orca.AXTable",
71 "orca.AXText",
72 "orca.AXUtilities",
73 "orca.input_event",
74 "orca.braille_presenter",
75 "orca.presentation_manager",
76 ]
77 essential_modules = test_context.setup_shared_dependencies(additional_modules)
78 self._setup_mocks(test_context, essential_modules)
79
80 return essential_modules
81
82 def _setup_cycle_navigation_mode_mocks(
83 self,
84 test_context,
85 nav,
86 current_mode,
87 supports_collection=True,
88 ):
89 """Set up common navigator mocks for cycle_mode testing scenarios."""
90
91 mock_get_mode = test_context.Mock(return_value=current_mode)
92 test_context.patch_object(nav, "get_mode", new=mock_get_mode)
93
94 mock_set_mode = test_context.Mock()
95 test_context.patch_object(nav, "set_mode", new=mock_set_mode)
96
97 test_context.patch_object(nav, "_is_active_script", return_value=True)
98
99 mock_determine_root = None
100 if supports_collection:
101 mock_root = test_context.Mock()
102 mock_determine_root = test_context.Mock(return_value=mock_root)
103 test_context.patch_object(nav, "_determine_root_container", new=mock_determine_root)
104
105 return mock_get_mode, mock_set_mode, mock_determine_root
106
107 def _setup_mocks(self, test_context, essential_modules) -> None:
108 """Set up common mocks for StructuralNavigator tests."""
109
110 input_event_handler_mock = test_context.Mock()
111 essential_modules["orca.input_event"].InputEventHandler = test_context.Mock(
112 return_value=input_event_handler_mock,
113 )
114 key_bindings_instance = test_context.Mock()
115 essential_modules["orca.keybindings"].KeyBindings = test_context.Mock(
116 return_value=key_bindings_instance,
117 )
118 controller_mock = test_context.Mock()
119 controller_mock.register_decorated_module.return_value = None
120 essential_modules["orca.dbus_service"].get_remote_controller.return_value = controller_mock
121 essential_modules["orca.debug"].print_message = test_context.Mock()
122 essential_modules["orca.debug"].LEVEL_INFO = 800
123 focus_manager_instance = test_context.Mock()
124 focus_manager_instance.get_locus_of_focus.return_value = None
125 essential_modules["orca.focus_manager"].get_manager.return_value = focus_manager_instance
126 essential_modules["orca.AXObject"].get_parent.return_value = None
127 essential_modules["orca.AXObject"].supports_collection.return_value = True
128 essential_modules["orca.AXObject"].find_ancestor.return_value = None
129 essential_modules["orca.AXObject"].get_attributes_dict.return_value = {}
130 essential_modules["orca.AXUtilities"].is_web_application.return_value = False
131 essential_modules["orca.AXUtilities"].is_heading.return_value = False
132 essential_modules["orca.AXUtilities"].is_live_region.return_value = False
133 essential_modules["orca.AXUtilities"].find_descendant.return_value = None
134 script_manager_instance = test_context.Mock()
135 script_manager_instance.get_active_script.return_value = None
136 essential_modules["orca.script_manager"].get_manager.return_value = script_manager_instance
137 essential_modules["orca.orca_i18n"]._ = lambda msg: msg
138 essential_modules["orca.messages"].STRUCTURAL_NAVIGATION_KEYS_DOCUMENT = "Document mode"
139 essential_modules["orca.messages"].STRUCTURAL_NAVIGATION_KEYS_GUI = "GUI mode"
140 essential_modules["orca.messages"].STRUCTURAL_NAVIGATION_KEYS_OFF = "Off mode"
141 essential_modules[
142 "orca.messages"
143 ].STRUCTURAL_NAVIGATION_NOT_SUPPORTED_FULL = "Not supported full"
144 essential_modules[
145 "orca.messages"
146 ].STRUCTURAL_NAVIGATION_NOT_SUPPORTED_BRIEF = "Not supported brief"
147 essential_modules["orca.messages"].WRAPPING_TO_TOP = "Wrapping to top"
148 essential_modules["orca.messages"].WRAPPING_TO_BOTTOM = "Wrapping to bottom"
149 essential_modules["orca.cmdnames"].STRUCTURAL_NAVIGATION_MODE_CYCLE = "cycle_mode"
150 essential_modules["orca.cmdnames"].BLOCKQUOTE_PREV = "previous_blockquote"
151 essential_modules["orca.cmdnames"].BLOCKQUOTE_NEXT = "next_blockquote"
152 essential_modules["orca.cmdnames"].BLOCKQUOTE_LIST = "list_blockquotes"
153 essential_modules["orca.cmdnames"].BUTTON_PREV = "previous_button"
154 essential_modules["orca.cmdnames"].BUTTON_NEXT = "next_button"
155 essential_modules["orca.cmdnames"].BUTTON_LIST = "list_buttons"
156 essential_modules["orca.cmdnames"].CHECK_BOX_PREV = "previous_checkbox"
157 essential_modules["orca.cmdnames"].CHECK_BOX_NEXT = "next_checkbox"
158 essential_modules["orca.cmdnames"].CHECK_BOX_LIST = "list_checkboxes"
159 essential_modules["orca.cmdnames"].COMBO_BOX_PREV = "previous_combobox"
160 essential_modules["orca.cmdnames"].COMBO_BOX_NEXT = "next_combobox"
161 essential_modules["orca.cmdnames"].COMBO_BOX_LIST = "list_comboboxes"
162 essential_modules["orca.cmdnames"].ENTRY_PREV = "previous_entry"
163 essential_modules["orca.cmdnames"].ENTRY_NEXT = "next_entry"
164 essential_modules["orca.cmdnames"].ENTRY_LIST = "list_entries"
165 essential_modules["orca.cmdnames"].FORM_FIELD_PREV = "previous_form_field"
166 essential_modules["orca.cmdnames"].FORM_FIELD_NEXT = "next_form_field"
167 essential_modules["orca.cmdnames"].FORM_FIELD_LIST = "list_form_fields"
168 essential_modules["orca.cmdnames"].HEADING_PREV = "previous_heading"
169 essential_modules["orca.cmdnames"].HEADING_NEXT = "next_heading"
170 essential_modules["orca.cmdnames"].HEADING_LIST = "list_headings"
171 essential_modules["orca.cmdnames"].HEADING_AT_LEVEL_PREV = "previous_heading_level_%d"
172 essential_modules["orca.cmdnames"].HEADING_AT_LEVEL_NEXT = "next_heading_level_%d"
173 essential_modules["orca.cmdnames"].HEADING_AT_LEVEL_LIST = "list_headings_level_%d"
174 essential_modules["orca.cmdnames"].IFRAME_PREV = "previous_iframe"
175 essential_modules["orca.cmdnames"].IFRAME_NEXT = "next_iframe"
176 essential_modules["orca.cmdnames"].IFRAME_LIST = "list_iframes"
177 essential_modules["orca.cmdnames"].IMAGE_PREV = "previous_image"
178 essential_modules["orca.cmdnames"].IMAGE_NEXT = "next_image"
179 essential_modules["orca.cmdnames"].IMAGE_LIST = "list_images"
180 essential_modules["orca.cmdnames"].LANDMARK_PREV = "previous_landmark"
181 essential_modules["orca.cmdnames"].LANDMARK_NEXT = "next_landmark"
182 essential_modules["orca.cmdnames"].LANDMARK_LIST = "list_landmarks"
183 essential_modules["orca.cmdnames"].LIST_PREV = "previous_list"
184 essential_modules["orca.cmdnames"].LIST_NEXT = "next_list"
185 essential_modules["orca.cmdnames"].LIST_LIST = "list_lists"
186 essential_modules["orca.cmdnames"].LIST_ITEM_PREV = "previous_list_item"
187 essential_modules["orca.cmdnames"].LIST_ITEM_NEXT = "next_list_item"
188 essential_modules["orca.cmdnames"].LIST_ITEM_LIST = "list_list_items"
189 essential_modules["orca.cmdnames"].LIVE_REGION_PREV = "previous_live_region"
190 essential_modules["orca.cmdnames"].LIVE_REGION_NEXT = "next_live_region"
191 essential_modules["orca.cmdnames"].LIVE_REGION_LAST = "last_live_region"
192 essential_modules["orca.cmdnames"].PARAGRAPH_PREV = "previous_paragraph"
193 essential_modules["orca.cmdnames"].PARAGRAPH_NEXT = "next_paragraph"
194 essential_modules["orca.cmdnames"].PARAGRAPH_LIST = "list_paragraphs"
195 essential_modules["orca.cmdnames"].RADIO_BUTTON_PREV = "previous_radio_button"
196 essential_modules["orca.cmdnames"].RADIO_BUTTON_NEXT = "next_radio_button"
197 essential_modules["orca.cmdnames"].RADIO_BUTTON_LIST = "list_radio_buttons"
198 essential_modules["orca.cmdnames"].SEPARATOR_PREV = "previous_separator"
199 essential_modules["orca.cmdnames"].SEPARATOR_NEXT = "next_separator"
200 essential_modules["orca.cmdnames"].TABLE_PREV = "previous_table"
201 essential_modules["orca.cmdnames"].TABLE_NEXT = "next_table"
202 essential_modules["orca.cmdnames"].TABLE_LIST = "list_tables"
203 essential_modules["orca.cmdnames"].LINK_PREV = "previous_link"
204 essential_modules["orca.cmdnames"].LINK_NEXT = "next_link"
205 essential_modules["orca.cmdnames"].LINK_LIST = "list_links"
206 essential_modules["orca.cmdnames"].UNVISITED_LINK_PREV = "previous_unvisited_link"
207 essential_modules["orca.cmdnames"].UNVISITED_LINK_NEXT = "next_unvisited_link"
208 essential_modules["orca.cmdnames"].UNVISITED_LINK_LIST = "list_unvisited_links"
209 essential_modules["orca.cmdnames"].VISITED_LINK_PREV = "previous_visited_link"
210 essential_modules["orca.cmdnames"].VISITED_LINK_NEXT = "next_visited_link"
211 essential_modules["orca.cmdnames"].VISITED_LINK_LIST = "list_visited_links"
212 essential_modules["orca.cmdnames"].LARGE_OBJECT_PREV = "previous_large_object"
213 essential_modules["orca.cmdnames"].LARGE_OBJECT_NEXT = "next_large_object"
214 essential_modules["orca.cmdnames"].LARGE_OBJECT_LIST = "list_large_objects"
215 essential_modules["orca.cmdnames"].CLICKABLE_PREV = "previous_clickable"
216 essential_modules["orca.cmdnames"].CLICKABLE_NEXT = "next_clickable"
217 essential_modules["orca.cmdnames"].CLICKABLE_LIST = "list_clickables"
218
219 def test_init(self, test_context: OrcaTestContext) -> None:
220 """Test StructuralNavigator initialization through get_navigator function."""
221
222 self._setup_dependencies(test_context)
223 from orca import command_manager
224 from orca.structural_navigator import get_navigator
225
226 nav = get_navigator()
227 assert (
228 nav._last_input_event is None or nav._last_input_event is not None
229 ) # May be set by other tests
230 assert isinstance(nav._suspended, bool)
231 assert isinstance(nav._mode_for_script, dict)
232 # Verify commands are registered in CommandManager
233 cmd_manager = command_manager.get_manager()
234 assert cmd_manager.get_command("structural_navigator_mode_cycle") is not None
235 assert cmd_manager.get_command("previous_button") is not None
236 assert cmd_manager.get_command("next_button") is not None
237
238 def test_commands_registered(self, test_context: OrcaTestContext) -> None:
239 """Test StructuralNavigator.setup registers commands with CommandManager."""
240
241 self._setup_dependencies(test_context)
242 from orca import command_manager
243 from orca.structural_navigator import get_navigator
244
245 nav = get_navigator()
246 nav.set_up_commands()
247 # Commands are now registered in CommandManager
248 cmd_manager = command_manager.get_manager()
249 assert cmd_manager.get_command("structural_navigator_mode_cycle") is not None
250 assert cmd_manager.get_command("previous_button") is not None
251 assert cmd_manager.get_command("next_button") is not None
252 assert cmd_manager.get_command("list_buttons") is not None
253
254 def test_setup_creates_heading_level_commands(self, test_context: OrcaTestContext) -> None:
255 """Test StructuralNavigator.setup creates heading level commands."""
256
257 self._setup_dependencies(test_context)
258 from orca import command_manager
259 from orca.structural_navigator import get_navigator
260
261 nav = get_navigator()
262 nav.set_up_commands()
263 cmd_manager = command_manager.get_manager()
264 for level in range(1, 7):
265 assert cmd_manager.get_command(f"previous_heading_level_{level}") is not None
266 assert cmd_manager.get_command(f"next_heading_level_{level}") is not None
267 assert cmd_manager.get_command(f"list_headings_level_{level}") is not None
268
269 @pytest.mark.parametrize(
270 "current_mode, expected_next_mode, supports_collection",
271 [
272 pytest.param("OFF", "DOCUMENT", True, id="off_to_document"),
273 pytest.param("DOCUMENT", "GUI", True, id="document_to_gui"),
274 pytest.param("GUI", "OFF", False, id="gui_to_off"),
275 ],
276 )
277 def test_cycle_mode_transitions(
278 self,
279 test_context: OrcaTestContext,
280 current_mode,
281 expected_next_mode,
282 supports_collection,
283 ) -> None:
284 """Test StructuralNavigator.cycle_mode transitions."""
285
286 essential_modules = self._setup_dependencies(test_context)
287 mock_script = test_context.Mock()
288 from orca.structural_navigator import NavigationMode, get_navigator
289
290 nav = get_navigator()
291 current_nav_mode = getattr(NavigationMode, current_mode)
292 expected_nav_mode = getattr(NavigationMode, expected_next_mode)
293
294 mock_get_mode, mock_set_mode = self._setup_cycle_navigation_mode_mocks(
295 test_context,
296 nav,
297 current_nav_mode,
298 supports_collection=supports_collection,
299 )[:2]
300
301 if supports_collection:
302 essential_modules["orca.AXObject"].supports_collection.return_value = True
303
304 pres_manager = essential_modules["orca.presentation_manager"].get_manager()
305 pres_manager.present_message.reset_mock()
306 result = nav.cycle_mode(mock_script, None, True)
307 assert result is True
308 mock_get_mode.assert_called_once_with(mock_script)
309 mock_set_mode.assert_called_once_with(mock_script, expected_nav_mode)
310 pres_manager.present_message.assert_called()
311
312 @pytest.mark.parametrize(
313 "scenario, notify_user, is_active_script, expected_result, expects_message_call",
314 [
315 pytest.param("no_notify", False, True, True, False, id="no_notify_no_message"),
316 pytest.param(
317 "inactive_script",
318 True,
319 False,
320 False,
321 None,
322 id="inactive_script_returns_false",
323 ),
324 ],
325 )
326 def test_cycle_mode_edge_scenarios(
327 self,
328 test_context: OrcaTestContext,
329 scenario,
330 notify_user,
331 is_active_script,
332 expected_result,
333 expects_message_call,
334 ) -> None:
335 """Test StructuralNavigator.cycle_mode edge scenarios."""
336
337 essential_modules = self._setup_dependencies(test_context)
338 mock_script = test_context.Mock()
339 from orca.structural_navigator import NavigationMode, get_navigator
340
341 nav = get_navigator()
342
343 if scenario == "no_notify":
344 self._setup_cycle_navigation_mode_mocks(test_context, nav, NavigationMode.OFF)
345 essential_modules["orca.AXObject"].supports_collection.return_value = True
346 else:
347 mock_is_active_script = test_context.Mock(return_value=is_active_script)
348 test_context.patch_object(nav, "_is_active_script", new=mock_is_active_script)
349
350 result = nav.cycle_mode(mock_script, None, notify_user)
351 assert result is expected_result
352
353 pres_manager = essential_modules["orca.presentation_manager"].get_manager()
354 if expects_message_call is False:
355 pres_manager.present_message.assert_not_called()
356 elif scenario == "inactive_script":
357 mock_is_active_script.assert_called_once_with(mock_script)
358
359 @pytest.mark.parametrize(
360 "suspend_value, is_active, initial_suspended, expected_suspended, expects_debug, "
361 "expects_cmd_mgr",
362 [
363 pytest.param(True, True, False, True, True, True, id="suspend_navigation"),
364 pytest.param(False, True, True, False, True, True, id="resume_navigation"),
365 pytest.param(
366 True,
367 False,
368 False,
369 False,
370 False,
371 False,
372 id="inactive_script_no_change",
373 ),
374 ],
375 )
376 def test_suspend_commands_scenarios(
377 self,
378 test_context: OrcaTestContext,
379 suspend_value,
380 is_active,
381 initial_suspended,
382 expected_suspended,
383 expects_debug,
384 expects_cmd_mgr,
385 ) -> None:
386 """Test StructuralNavigator.suspend_commands various scenarios."""
387
388 essential_modules = self._setup_dependencies(test_context)
389
390 # Mock command_manager
391 mock_cmd_mgr = test_context.Mock()
392 essential_modules["orca.command_manager"].get_manager.return_value = mock_cmd_mgr
393
394 mock_script = test_context.Mock()
395 from orca.structural_navigator import get_navigator
396
397 nav = get_navigator()
398 nav._suspended = initial_suspended
399 test_context.patch_object(nav, "_is_active_script", return_value=is_active)
400 mock_cmd_mgr = test_context.Mock()
401 essential_modules["orca.command_manager"].get_manager.return_value = mock_cmd_mgr
402
403 nav.suspend_commands(mock_script, suspend_value, "test reason")
404
405 assert nav._suspended == expected_suspended
406
407 if expects_debug:
408 essential_modules["orca.debug"].print_message.assert_any_call(
409 essential_modules["orca.debug"].LEVEL_INFO,
410 f"STRUCTURAL NAVIGATOR: Suspended: {suspend_value}: test reason",
411 True,
412 )
413
414 if expects_cmd_mgr:
415 mock_cmd_mgr.set_group_suspended.assert_called_once()
416 else:
417 mock_cmd_mgr.set_group_suspended.assert_not_called()
418
419 def test_get_object_in_direction_empty_objects(self, test_context: OrcaTestContext) -> None:
420 """Test StructuralNavigator._get_object_in_direction with empty objects list."""
421
422 self._setup_dependencies(test_context)
423 mock_script = test_context.Mock()
424 from orca.structural_navigator import get_navigator
425
426 nav = get_navigator()
427 result = nav._get_object_in_direction(mock_script, [], True)
428 assert result is None
429
430 def test_get_object_in_direction_next_object(self, test_context: OrcaTestContext) -> None:
431 """Test StructuralNavigator._get_object_in_direction returns next object."""
432
433 essential_modules = self._setup_dependencies(test_context)
434 from orca.structural_navigator import get_navigator
435
436 nav = get_navigator()
437 mock_obj1 = test_context.Mock()
438 mock_obj2 = test_context.Mock()
439 mock_obj3 = test_context.Mock()
440 objects = [mock_obj1, mock_obj2, mock_obj3]
441
442 essential_modules[
443 "orca.focus_manager"
444 ].get_manager.return_value.get_locus_of_focus.return_value = mock_obj2
445 essential_modules["orca.AXObject"].get_parent.return_value = mock_obj2
446
447 def mock_get_path(obj):
448 if obj == mock_obj1:
449 return [0, 0]
450 if obj == mock_obj2:
451 return [0, 1]
452 if obj == mock_obj3:
453 return [0, 2]
454 return []
455
456 essential_modules["orca.AXObject"].get_path.side_effect = mock_get_path
457
458 mock_script = test_context.Mock()
459
460 def mock_path_comparison(path1, _path2):
461 if path1 == [0, 0]: # obj1
462 return -1
463 if path1 == [0, 1]: # obj2
464 return 0
465 if path1 == [0, 2]: # obj3
466 return 1
467 return 0
468
469 mock_script.utilities.path_comparison.side_effect = mock_path_comparison
470
471 result = nav._get_object_in_direction(mock_script, objects, True)
472 assert result == mock_obj3
473
474 def test_get_object_in_direction_previous_object(self, test_context: OrcaTestContext) -> None:
475 """Test StructuralNavigator._get_object_in_direction returns previous object."""
476
477 essential_modules = self._setup_dependencies(test_context)
478 from orca import ax_utilities
479 from orca.structural_navigator import get_navigator
480
481 nav = get_navigator()
482 test_context.patch_object(ax_utilities.AXUtilities, "is_live_region", return_value=False)
483 mock_obj1 = test_context.Mock()
484 mock_obj2 = test_context.Mock()
485 mock_obj3 = test_context.Mock()
486 objects = [mock_obj1, mock_obj2, mock_obj3]
487
488 essential_modules[
489 "orca.focus_manager"
490 ].get_manager.return_value.get_locus_of_focus.return_value = mock_obj2
491 essential_modules["orca.AXObject"].get_parent.return_value = mock_obj2
492
493 def mock_get_path(obj):
494 if obj == mock_obj1:
495 return [0, 0]
496 if obj == mock_obj2:
497 return [0, 1]
498 if obj == mock_obj3:
499 return [0, 2] # Later in tree
500 return []
501
502 essential_modules["orca.AXObject"].get_path.side_effect = mock_get_path
503
504 mock_script = test_context.Mock()
505
506 def mock_path_comparison(path1, _path2):
507 if path1 == [0, 0]: # obj1
508 return -1
509 if path1 == [0, 1]: # obj2
510 return 0
511 if path1 == [0, 2]: # obj3
512 return 1
513 return 0
514
515 mock_script.utilities.path_comparison.side_effect = mock_path_comparison
516
517 result = nav._get_object_in_direction(mock_script, objects, False)
518 assert result == mock_obj1
519
520 def test_get_object_in_direction_wrap_to_beginning(self, test_context: OrcaTestContext) -> None:
521 """Test StructuralNavigator._get_object_in_direction wraps to beginning when at end."""
522
523 self._setup_dependencies(test_context)
524 from orca.structural_navigator import get_navigator
525
526 nav = get_navigator()
527 mock_result = test_context.Mock()
528 mock_script = test_context.Mock()
529
530 test_context.patch_object(nav, "_get_object_in_direction", return_value=mock_result)
531
532 result = nav._get_object_in_direction(mock_script, [], True, True)
533 assert result == mock_result
534
535 def test_get_object_in_direction_wrap_to_end(self, test_context: OrcaTestContext) -> None:
536 """Test StructuralNavigator._get_object_in_direction wraps to end when at beginning."""
537
538 self._setup_dependencies(test_context)
539 from orca.structural_navigator import get_navigator
540
541 nav = get_navigator()
542 mock_result = test_context.Mock()
543 mock_script = test_context.Mock()
544
545 test_context.patch_object(nav, "_get_object_in_direction", return_value=mock_result)
546
547 result = nav._get_object_in_direction(mock_script, [], False, True)
548 assert result == mock_result
549
550 def test_get_object_in_direction_no_wrap_at_end(self, test_context: OrcaTestContext) -> None:
551 """Test StructuralNavigator._get_object_in_direction returns None at end when no wrap."""
552
553 self._setup_dependencies(test_context)
554 from orca.structural_navigator import get_navigator
555
556 nav = get_navigator()
557 mock_script = test_context.Mock()
558
559 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
560
561 result = nav._get_object_in_direction(mock_script, [], True, False)
562 assert result is None
563
564 def test_previous_button_method(self, test_context: OrcaTestContext) -> None:
565 """Test StructuralNavigator.previous_button method."""
566
567 self._setup_dependencies(test_context)
568 mock_script = test_context.Mock()
569 mock_event = test_context.Mock()
570 from orca.structural_navigator import get_navigator
571
572 nav = get_navigator()
573 mock_get_buttons = test_context.Mock(return_value=[])
574 test_context.patch_object(nav, "_get_all_buttons", new=mock_get_buttons)
575 mock_get_in_direction = test_context.Mock(return_value=None)
576 test_context.patch_object(nav, "_get_object_in_direction", new=mock_get_in_direction)
577 mock_present = test_context.Mock()
578 test_context.patch_object(nav, "_present_object", new=mock_present)
579 result = nav.previous_button(mock_script, mock_event, True)
580 assert result is True
581 mock_get_buttons.assert_called_once_with(mock_script)
582 mock_get_in_direction.assert_called_once()
583 mock_present.assert_called_once()
584
585 def test_next_button_method(self, test_context: OrcaTestContext) -> None:
586 """Test StructuralNavigator.next_button method."""
587
588 self._setup_dependencies(test_context)
589 mock_script = test_context.Mock()
590 mock_event = test_context.Mock()
591 from orca.structural_navigator import get_navigator
592
593 nav = get_navigator()
594 mock_get_buttons = test_context.Mock(return_value=[])
595 test_context.patch_object(nav, "_get_all_buttons", new=mock_get_buttons)
596 mock_get_in_direction = test_context.Mock(return_value=None)
597 test_context.patch_object(nav, "_get_object_in_direction", new=mock_get_in_direction)
598 mock_present = test_context.Mock()
599 test_context.patch_object(nav, "_present_object", new=mock_present)
600 result = nav.next_button(mock_script, mock_event, True)
601 assert result is True
602 mock_get_buttons.assert_called_once_with(mock_script)
603 mock_get_in_direction.assert_called_once()
604 mock_present.assert_called_once()
605
606 def test_list_buttons_method(self, test_context: OrcaTestContext) -> None:
607 """Test StructuralNavigator.list_buttons method."""
608
609 self._setup_dependencies(test_context)
610 mock_script = test_context.Mock()
611 mock_event = test_context.Mock()
612 from orca.structural_navigator import get_navigator
613
614 nav = get_navigator()
615 mock_get_buttons = test_context.Mock(return_value=[])
616 test_context.patch_object(nav, "_get_all_buttons", new=mock_get_buttons)
617 mock_present = test_context.Mock()
618 test_context.patch_object(nav, "_present_object_list", new=mock_present)
619 result = nav.list_buttons(mock_script, mock_event)
620 assert result is True
621 mock_get_buttons.assert_called_once_with(mock_script)
622 mock_present.assert_called_once()
623
624 @pytest.mark.parametrize(
625 "is_same_script,expected",
626 [
627 (True, True),
628 (False, False),
629 ],
630 )
631 def test_is_active_script(
632 self,
633 test_context: OrcaTestContext,
634 is_same_script: bool,
635 expected: bool,
636 ) -> None:
637 """Test StructuralNavigator._is_active_script with active and inactive scripts."""
638
639 essential_modules = self._setup_dependencies(test_context)
640 mock_script = test_context.Mock()
641 mock_active_script = mock_script if is_same_script else test_context.Mock()
642 essential_modules[
643 "orca.script_manager"
644 ].get_manager.return_value.get_active_script.return_value = mock_active_script
645 from orca.structural_navigator import get_navigator
646
647 nav = get_navigator()
648 result = nav._is_active_script(mock_script)
649 assert result is expected
650
651 def test_get_mode_default(self, test_context: OrcaTestContext) -> None:
652 """Test StructuralNavigator.get_mode returns default mode for new script."""
653
654 self._setup_dependencies(test_context)
655 mock_script = test_context.Mock()
656 from orca.structural_navigator import NavigationMode, get_navigator
657
658 nav = get_navigator()
659 result = nav.get_mode(mock_script)
660 assert result == NavigationMode.OFF
661
662 def test_get_mode_cached(self, test_context: OrcaTestContext) -> None:
663 """Test StructuralNavigator.get_mode returns cached mode for known script."""
664
665 self._setup_dependencies(test_context)
666 mock_script = test_context.Mock()
667 from orca.structural_navigator import NavigationMode, get_navigator
668
669 nav = get_navigator()
670 nav._mode_for_script[mock_script] = NavigationMode.DOCUMENT
671 result = nav.get_mode(mock_script)
672 assert result == NavigationMode.DOCUMENT
673
674 def test_set_mode(self, test_context: OrcaTestContext) -> None:
675 """Test StructuralNavigator.set_mode sets mode for script."""
676
677 self._setup_dependencies(test_context)
678 mock_script = test_context.Mock()
679 from orca.structural_navigator import NavigationMode, get_navigator
680
681 nav = get_navigator()
682 nav.set_mode(mock_script, NavigationMode.GUI)
683 assert nav._mode_for_script[mock_script] == NavigationMode.GUI
684
685 def test_determine_root_container_document_mode(self, test_context: OrcaTestContext) -> None:
686 """Test StructuralNavigator._determine_root_container for document mode."""
687 essential_modules = self._setup_dependencies(test_context)
688 mock_script = test_context.Mock()
689 mock_focus = test_context.Mock()
690 mock_document = test_context.Mock()
691
692 essential_modules[
693 "orca.focus_manager"
694 ].get_manager().get_locus_of_focus.return_value = mock_focus
695 essential_modules["orca.AXObject"].find_ancestor_inclusive.side_effect = (
696 lambda focus, predicate: None
697 )
698 mock_script.utilities.get_top_level_document_for_object.return_value = mock_document
699
700 from orca.structural_navigator import get_navigator
701
702 nav = get_navigator()
703 test_context.patch_object(nav, "_determine_root_container", return_value=mock_document)
704
705 result = nav._determine_root_container(mock_script)
706 assert result == mock_document
707
708 def test_determine_root_container_fallback(self, test_context: OrcaTestContext) -> None:
709 """Test StructuralNavigator._determine_root_container fallback to app."""
710
711 essential_modules = self._setup_dependencies(test_context)
712 mock_script = test_context.Mock()
713 mock_app = test_context.Mock(spec=Atspi.Accessible)
714 mock_script.app = mock_app
715 essential_modules["orca.AXUtilities"].is_web_application.return_value = False
716 essential_modules["orca.AXObject"].find_ancestor_inclusive.return_value = mock_app
717 from orca.structural_navigator import get_navigator
718
719 nav = get_navigator()
720 test_context.patch_object(nav, "_determine_root_container", return_value=mock_app)
721 result = nav._determine_root_container(mock_script)
722 assert result == mock_app
723
724 @pytest.mark.parametrize(
725 "element_type,ax_method",
726 [
727 pytest.param("buttons", "find_all_buttons", id="get_all_buttons"),
728 pytest.param("headings", "find_all_headings", id="get_all_headings"),
729 pytest.param("links", "find_all_links", id="get_all_links"),
730 pytest.param("tables", "find_all_tables", id="get_all_tables"),
731 pytest.param("lists", "find_all_lists", id="get_all_lists"),
732 pytest.param("checkboxes", "find_all_check_boxes", id="get_all_checkboxes"),
733 pytest.param("entries", "find_all_editable_objects", id="get_all_entries"),
734 pytest.param("form_fields", "find_all_form_fields", id="get_all_form_fields"),
735 pytest.param("images", "find_all_images_and_image_maps", id="get_all_images"),
736 pytest.param("landmarks", "find_all_landmarks", id="get_all_landmarks"),
737 pytest.param("paragraphs", "find_all_paragraphs", id="get_all_paragraphs"),
738 ],
739 )
740 def test_get_all_elements(
741 self,
742 test_context: OrcaTestContext,
743 element_type: str,
744 ax_method: str,
745 ) -> None:
746 """Test StructuralNavigator._get_all_* methods with various element types."""
747
748 self._setup_dependencies(test_context)
749 mock_script = test_context.Mock()
750 from orca.structural_navigator import get_navigator
751
752 nav = get_navigator()
753 mock_elements = [test_context.Mock(), test_context.Mock()]
754
755 if element_type == "lists":
756 test_context.patch(
757 f"orca.structural_navigator.AXUtilities.{ax_method}",
758 side_effect=lambda root,
759 include_description_lists=False,
760 include_tab_lists=False,
761 pred=None: mock_elements,
762 )
763 elif element_type == "paragraphs":
764 test_context.patch(
765 f"orca.structural_navigator.AXUtilities.{ax_method}",
766 side_effect=lambda root, include_items=False, pred=None: mock_elements,
767 )
768 else:
769 test_context.patch(
770 f"orca.structural_navigator.AXUtilities.{ax_method}",
771 side_effect=lambda root, pred=None: mock_elements,
772 )
773
774 if element_type in ["links", "entries", "images"]:
775 mock_root = test_context.Mock()
776 test_context.patch_object(
777 nav,
778 "_determine_root_container",
779 side_effect=lambda script: mock_root,
780 )
781
782 navigation_method = getattr(nav, f"_get_all_{element_type}")
783 result = navigation_method(mock_script)
784 assert result == mock_elements
785
786 def test_get_mode(self, test_context: OrcaTestContext) -> None:
787 """Test StructuralNavigator.get_mode method."""
788
789 self._setup_dependencies(test_context)
790 mock_script = test_context.Mock()
791 from orca.structural_navigator import NavigationMode, get_navigator
792
793 nav = get_navigator()
794 result = nav.get_mode(mock_script)
795 assert result == NavigationMode.OFF
796
797 def test_last_input_event_was_navigation_command(self, test_context: OrcaTestContext) -> None:
798 """Test StructuralNavigator.last_input_event_was_navigation_command method."""
799
800 essential_modules = self._setup_dependencies(test_context)
801 essential_modules[
802 "orca.input_event_manager"
803 ].get_manager().last_event_equals_or_is_release_for_event.return_value = True
804 from orca.structural_navigator import get_navigator
805
806 nav = get_navigator()
807 mock_event = test_context.Mock()
808 mock_event.as_single_line_string = test_context.Mock(return_value="mock event")
809 nav._last_input_event = mock_event
810
811 result = nav.last_input_event_was_navigation_command()
812 assert isinstance(result, bool)
813 assert result is True
814
815 def test_get_state_string(self, test_context: OrcaTestContext) -> None:
816 """Test StructuralNavigator._get_state_string method."""
817
818 essential_modules = self._setup_dependencies(test_context)
819 mock_obj = test_context.Mock()
820 from orca.structural_navigator import get_navigator
821
822 nav = get_navigator()
823 essential_modules["orca.AXObject"].get_state_set.return_value = None
824 essential_modules["orca.AXUtilities"].is_switch.return_value = False
825 essential_modules["orca.AXUtilities"].is_checked.return_value = False
826 essential_modules["orca.AXUtilities"].is_expanded.return_value = False
827 essential_modules["orca.AXUtilities"].is_pressed.return_value = False
828 essential_modules["orca.AXUtilities"].is_selected.return_value = False
829 test_context.patch_object(nav, "_get_state_string", return_value="test state")
830 result = nav._get_state_string(mock_obj)
831 assert isinstance(result, str)
832 assert result == "test state"
833
834 def test_get_item_string(self, test_context: OrcaTestContext) -> None:
835 """Test StructuralNavigator._get_item_string method."""
836
837 self._setup_dependencies(test_context)
838 mock_script = test_context.Mock()
839 mock_obj = test_context.Mock()
840 from orca.structural_navigator import get_navigator
841
842 nav = get_navigator()
843 test_context.patch_object(
844 nav,
845 "_get_item_string",
846 return_value="Test Object: Test Description",
847 )
848 result = nav._get_item_string(mock_script, mock_obj)
849 assert isinstance(result, str)
850 assert "Test Description" in result
851
852 def test_is_non_document_object(self, test_context: OrcaTestContext) -> None:
853 """Test StructuralNavigator._is_non_document_object method."""
854
855 essential_modules = self._setup_dependencies(test_context)
856 mock_obj = test_context.Mock()
857 from orca.structural_navigator import get_navigator
858
859 nav = get_navigator()
860 essential_modules["orca.AXUtilities"].is_application.return_value = False
861 essential_modules["orca.AXUtilities"].is_document.return_value = False
862 essential_modules["orca.AXUtilities"].is_frame.return_value = False
863 essential_modules["orca.AXObject"].get_role.return_value = None
864 result = nav._is_non_document_object(mock_obj)
865 assert isinstance(result, bool)
866
867 def test_previous_heading_method(self, test_context: OrcaTestContext) -> None:
868 """Test StructuralNavigator.previous_heading method."""
869 self._setup_dependencies(test_context)
870 mock_script = test_context.Mock()
871 mock_event = test_context.Mock()
872 from orca.structural_navigator import get_navigator
873
874 nav = get_navigator()
875 test_context.patch_object(nav, "_get_all_headings", return_value=[])
876 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
877 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
878 result = nav.previous_heading(mock_script, mock_event, True)
879 assert result is True
880
881 def test_next_heading_method(self, test_context: OrcaTestContext) -> None:
882 """Test StructuralNavigator.next_heading method."""
883
884 self._setup_dependencies(test_context)
885 mock_script = test_context.Mock()
886 mock_event = test_context.Mock()
887 from orca.structural_navigator import get_navigator
888
889 nav = get_navigator()
890 test_context.patch_object(nav, "_get_all_headings", return_value=[])
891 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
892 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
893 result = nav.next_heading(mock_script, mock_event, True)
894 assert result is True
895
896 def test_list_headings_method(self, test_context: OrcaTestContext) -> None:
897 """Test StructuralNavigator.list_headings method."""
898
899 self._setup_dependencies(test_context)
900 mock_script = test_context.Mock()
901 mock_event = test_context.Mock()
902 from orca.structural_navigator import get_navigator
903
904 nav = get_navigator()
905 test_context.patch_object(nav, "_get_all_headings", return_value=[])
906 test_context.patch_object(nav, "_present_object_list", new=test_context.Mock())
907 result = nav.list_headings(mock_script, mock_event)
908 assert result is True
909
910 def test_previous_link_method(self, test_context: OrcaTestContext) -> None:
911 """Test StructuralNavigator.previous_link method."""
912
913 self._setup_dependencies(test_context)
914 mock_script = test_context.Mock()
915 mock_event = test_context.Mock()
916 from orca.structural_navigator import get_navigator
917
918 nav = get_navigator()
919 test_context.patch_object(nav, "_get_all_links", return_value=[])
920 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
921 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
922 result = nav.previous_link(mock_script, mock_event, True)
923 assert result is True
924
925 def test_next_link_method(self, test_context: OrcaTestContext) -> None:
926 """Test StructuralNavigator.next_link method."""
927
928 self._setup_dependencies(test_context)
929 mock_script = test_context.Mock()
930 mock_event = test_context.Mock()
931 from orca.structural_navigator import get_navigator
932
933 nav = get_navigator()
934 test_context.patch_object(nav, "_get_all_links", return_value=[])
935 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
936 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
937 result = nav.next_link(mock_script, mock_event, True)
938 assert result is True
939
940 def test_list_links_method(self, test_context: OrcaTestContext) -> None:
941 """Test StructuralNavigator.list_links method."""
942
943 self._setup_dependencies(test_context)
944 mock_script = test_context.Mock()
945 mock_event = test_context.Mock()
946 from orca.structural_navigator import get_navigator
947
948 nav = get_navigator()
949 test_context.patch_object(nav, "_get_all_links", return_value=[])
950 test_context.patch_object(nav, "_present_object_list", new=test_context.Mock())
951 result = nav.list_links(mock_script, mock_event)
952 assert result is True
953
954 def test_previous_table_method(self, test_context: OrcaTestContext) -> None:
955 """Test StructuralNavigator.previous_table method."""
956
957 self._setup_dependencies(test_context)
958 mock_script = test_context.Mock()
959 mock_event = test_context.Mock()
960 from orca.structural_navigator import get_navigator
961
962 nav = get_navigator()
963 test_context.patch_object(nav, "_get_all_tables", return_value=[])
964 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
965 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
966 result = nav.previous_table(mock_script, mock_event, True)
967 assert result is True
968
969 def test_next_table_method(self, test_context: OrcaTestContext) -> None:
970 """Test StructuralNavigator.next_table method."""
971
972 self._setup_dependencies(test_context)
973 mock_script = test_context.Mock()
974 mock_event = test_context.Mock()
975 from orca.structural_navigator import get_navigator
976
977 nav = get_navigator()
978 test_context.patch_object(nav, "_get_all_tables", return_value=[])
979 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
980 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
981 result = nav.next_table(mock_script, mock_event, True)
982 assert result is True
983
984 def test_list_tables_method(self, test_context: OrcaTestContext) -> None:
985 """Test StructuralNavigator.list_tables method."""
986
987 self._setup_dependencies(test_context)
988 mock_script = test_context.Mock()
989 mock_event = test_context.Mock()
990 from orca.structural_navigator import get_navigator
991
992 nav = get_navigator()
993 test_context.patch_object(nav, "_get_all_tables", return_value=[])
994 test_context.patch_object(nav, "_present_object_list", new=test_context.Mock())
995 result = nav.list_tables(mock_script, mock_event)
996 assert result is True
997
998 def test_previous_list_method(self, test_context: OrcaTestContext) -> None:
999 """Test StructuralNavigator.previous_list method."""
1000
1001 self._setup_dependencies(test_context)
1002 mock_script = test_context.Mock()
1003 mock_event = test_context.Mock()
1004 from orca.structural_navigator import get_navigator
1005
1006 nav = get_navigator()
1007 test_context.patch_object(nav, "_get_all_lists", return_value=[])
1008 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1009 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1010 result = nav.previous_list(mock_script, mock_event, True)
1011 assert result is True
1012
1013 def test_next_list_method(self, test_context: OrcaTestContext) -> None:
1014 """Test StructuralNavigator.next_list method."""
1015
1016 self._setup_dependencies(test_context)
1017 mock_script = test_context.Mock()
1018 mock_event = test_context.Mock()
1019 from orca.structural_navigator import get_navigator
1020
1021 nav = get_navigator()
1022 test_context.patch_object(nav, "_get_all_lists", return_value=[])
1023 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1024 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1025 result = nav.next_list(mock_script, mock_event, True)
1026 assert result is True
1027
1028 def test_list_lists_method(self, test_context: OrcaTestContext) -> None:
1029 """Test StructuralNavigator.list_lists method."""
1030
1031 self._setup_dependencies(test_context)
1032 mock_script = test_context.Mock()
1033 mock_event = test_context.Mock()
1034 from orca.structural_navigator import get_navigator
1035
1036 nav = get_navigator()
1037 test_context.patch_object(nav, "_get_all_lists", return_value=[])
1038 test_context.patch_object(nav, "_present_object_list", new=test_context.Mock())
1039 result = nav.list_lists(mock_script, mock_event)
1040 assert result is True
1041
1042 def test_previous_blockquote_method(self, test_context: OrcaTestContext) -> None:
1043 """Test StructuralNavigator.previous_blockquote method."""
1044
1045 self._setup_dependencies(test_context)
1046 mock_script = test_context.Mock()
1047 mock_event = test_context.Mock()
1048 from orca.structural_navigator import get_navigator
1049
1050 nav = get_navigator()
1051 test_context.patch_object(nav, "_get_all_blockquotes", return_value=[])
1052 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1053 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1054 result = nav.previous_blockquote(mock_script, mock_event, True)
1055 assert result is True
1056
1057 def test_next_blockquote_method(self, test_context: OrcaTestContext) -> None:
1058 """Test StructuralNavigator.next_blockquote method."""
1059
1060 self._setup_dependencies(test_context)
1061 mock_script = test_context.Mock()
1062 mock_event = test_context.Mock()
1063 from orca.structural_navigator import get_navigator
1064
1065 nav = get_navigator()
1066 test_context.patch_object(nav, "_get_all_blockquotes", return_value=[])
1067 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1068 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1069 result = nav.next_blockquote(mock_script, mock_event, True)
1070 assert result is True
1071
1072 def test_previous_checkbox_method(self, test_context: OrcaTestContext) -> None:
1073 """Test StructuralNavigator.previous_checkbox method."""
1074
1075 self._setup_dependencies(test_context)
1076 mock_script = test_context.Mock()
1077 mock_event = test_context.Mock()
1078 from orca.structural_navigator import get_navigator
1079
1080 nav = get_navigator()
1081 test_context.patch_object(nav, "_get_all_checkboxes", return_value=[])
1082 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1083 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1084 result = nav.previous_checkbox(mock_script, mock_event, True)
1085 assert result is True
1086
1087 def test_next_checkbox_method(self, test_context: OrcaTestContext) -> None:
1088 """Test StructuralNavigator.next_checkbox method."""
1089
1090 self._setup_dependencies(test_context)
1091 mock_script = test_context.Mock()
1092 mock_event = test_context.Mock()
1093 from orca.structural_navigator import get_navigator
1094
1095 nav = get_navigator()
1096 test_context.patch_object(nav, "_get_all_checkboxes", return_value=[])
1097 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1098 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1099 result = nav.next_checkbox(mock_script, mock_event, True)
1100 assert result is True
1101
1102 def test_previous_entry_method(self, test_context: OrcaTestContext) -> None:
1103 """Test StructuralNavigator.previous_entry method."""
1104
1105 self._setup_dependencies(test_context)
1106 mock_script = test_context.Mock()
1107 mock_event = test_context.Mock()
1108 from orca.structural_navigator import get_navigator
1109
1110 nav = get_navigator()
1111 test_context.patch_object(nav, "_get_all_entries", return_value=[])
1112 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1113 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1114 result = nav.previous_entry(mock_script, mock_event, True)
1115 assert result is True
1116
1117 def test_next_entry_method(self, test_context: OrcaTestContext) -> None:
1118 """Test StructuralNavigator.next_entry method."""
1119
1120 self._setup_dependencies(test_context)
1121 mock_script = test_context.Mock()
1122 mock_event = test_context.Mock()
1123 from orca.structural_navigator import get_navigator
1124
1125 nav = get_navigator()
1126 test_context.patch_object(nav, "_get_all_entries", return_value=[])
1127 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1128 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1129 result = nav.next_entry(mock_script, mock_event, True)
1130 assert result is True
1131
1132 def test_previous_form_field_method(self, test_context: OrcaTestContext) -> None:
1133 """Test StructuralNavigator.previous_form_field method."""
1134
1135 self._setup_dependencies(test_context)
1136 mock_script = test_context.Mock()
1137 mock_event = test_context.Mock()
1138 from orca.structural_navigator import get_navigator
1139
1140 nav = get_navigator()
1141 test_context.patch_object(nav, "_get_all_form_fields", return_value=[])
1142 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1143 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1144 result = nav.previous_form_field(mock_script, mock_event, True)
1145 assert result is True
1146
1147 def test_next_form_field_method(self, test_context: OrcaTestContext) -> None:
1148 """Test StructuralNavigator.next_form_field method."""
1149
1150 self._setup_dependencies(test_context)
1151 mock_script = test_context.Mock()
1152 mock_event = test_context.Mock()
1153 from orca.structural_navigator import get_navigator
1154
1155 nav = get_navigator()
1156 test_context.patch_object(nav, "_get_all_form_fields", return_value=[])
1157 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1158 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1159 result = nav.next_form_field(mock_script, mock_event, True)
1160 assert result is True
1161
1162 def test_previous_image_method(self, test_context: OrcaTestContext) -> None:
1163 """Test StructuralNavigator.previous_image method."""
1164
1165 self._setup_dependencies(test_context)
1166 mock_script = test_context.Mock()
1167 mock_event = test_context.Mock()
1168 from orca.structural_navigator import get_navigator
1169
1170 nav = get_navigator()
1171 test_context.patch_object(nav, "_get_all_images", return_value=[])
1172 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1173 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1174 result = nav.previous_image(mock_script, mock_event, True)
1175 assert result is True
1176
1177 def test_next_image_method(self, test_context: OrcaTestContext) -> None:
1178 """Test StructuralNavigator.next_image method."""
1179
1180 self._setup_dependencies(test_context)
1181 mock_script = test_context.Mock()
1182 mock_event = test_context.Mock()
1183 from orca.structural_navigator import get_navigator
1184
1185 nav = get_navigator()
1186 test_context.patch_object(nav, "_get_all_images", return_value=[])
1187 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1188 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1189 result = nav.next_image(mock_script, mock_event, True)
1190 assert result is True
1191
1192 def test_previous_landmark_method(self, test_context: OrcaTestContext) -> None:
1193 """Test StructuralNavigator.previous_landmark method."""
1194
1195 self._setup_dependencies(test_context)
1196 mock_script = test_context.Mock()
1197 mock_event = test_context.Mock()
1198 from orca.structural_navigator import get_navigator
1199
1200 nav = get_navigator()
1201 test_context.patch_object(nav, "_get_all_landmarks", return_value=[])
1202 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1203 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1204 result = nav.previous_landmark(mock_script, mock_event, True)
1205 assert result is True
1206
1207 def test_next_landmark_method(self, test_context: OrcaTestContext) -> None:
1208 """Test StructuralNavigator.next_landmark method."""
1209
1210 self._setup_dependencies(test_context)
1211 mock_script = test_context.Mock()
1212 mock_event = test_context.Mock()
1213 from orca.structural_navigator import get_navigator
1214
1215 nav = get_navigator()
1216 test_context.patch_object(nav, "_get_all_landmarks", return_value=[])
1217 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1218 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1219 result = nav.next_landmark(mock_script, mock_event, True)
1220 assert result is True
1221
1222 def test_previous_paragraph_method(self, test_context: OrcaTestContext) -> None:
1223 """Test StructuralNavigator.previous_paragraph method."""
1224
1225 self._setup_dependencies(test_context)
1226 mock_script = test_context.Mock()
1227 mock_event = test_context.Mock()
1228 from orca.structural_navigator import get_navigator
1229
1230 nav = get_navigator()
1231 test_context.patch_object(nav, "_get_all_paragraphs", return_value=[])
1232 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1233 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1234 result = nav.previous_paragraph(mock_script, mock_event, True)
1235 assert result is True
1236
1237 def test_next_paragraph_method(self, test_context: OrcaTestContext) -> None:
1238 """Test StructuralNavigator.next_paragraph method."""
1239
1240 self._setup_dependencies(test_context)
1241 mock_script = test_context.Mock()
1242 mock_event = test_context.Mock()
1243 from orca.structural_navigator import get_navigator
1244
1245 nav = get_navigator()
1246 test_context.patch_object(nav, "_get_all_paragraphs", return_value=[])
1247 test_context.patch_object(nav, "_get_object_in_direction", return_value=None)
1248 test_context.patch_object(nav, "_present_object", new=test_context.Mock())
1249 result = nav.next_paragraph(mock_script, mock_event, True)
1250 assert result is True
1251
1252 @pytest.mark.parametrize(
1253 "expected_next_method,expected_prev_method",
1254 [
1255 pytest.param("next_heading_level_1", "previous_heading_level_1", id="heading_level_1"),
1256 pytest.param("next_heading_level_2", "previous_heading_level_2", id="heading_level_2"),
1257 pytest.param("next_heading_level_3", "previous_heading_level_3", id="heading_level_3"),
1258 pytest.param("next_heading_level_4", "previous_heading_level_4", id="heading_level_4"),
1259 pytest.param("next_heading_level_5", "previous_heading_level_5", id="heading_level_5"),
1260 pytest.param("next_heading_level_6", "previous_heading_level_6", id="heading_level_6"),
1261 ],
1262 )
1263 def test_heading_level_navigation_methods_exist(
1264 self,
1265 test_context: OrcaTestContext,
1266 expected_next_method: str,
1267 expected_prev_method: str,
1268 ) -> None:
1269 """Test StructuralNavigator has navigation methods for each heading level."""
1270
1271 essential_modules = test_context.setup_shared_dependencies(
1272 [
1273 "orca.keybindings",
1274 "orca.dbus_service",
1275 "orca.debug",
1276 "orca.focus_manager",
1277 "orca.AXObject",
1278 "orca.AXUtilities",
1279 ],
1280 )
1281 self._setup_mocks(test_context, essential_modules)
1282
1283 from orca.structural_navigator import StructuralNavigator
1284
1285 navigator = StructuralNavigator()
1286 assert hasattr(navigator, expected_next_method)
1287 assert hasattr(navigator, expected_prev_method)
1288 assert callable(getattr(navigator, expected_next_method))
1289 assert callable(getattr(navigator, expected_prev_method))
1290
1291 @pytest.mark.parametrize(
1292 "mode_value",
1293 [
1294 pytest.param("OFF", id="off_mode"),
1295 pytest.param("DOCUMENT", id="document_mode"),
1296 pytest.param("GUI", id="gui_mode"),
1297 ],
1298 )
1299 def test_navigation_mode_values(
1300 self,
1301 test_context: OrcaTestContext,
1302 mode_value: str,
1303 ) -> None:
1304 """Test NavigationMode enum values."""
1305
1306 essential_modules = test_context.setup_shared_dependencies(
1307 [
1308 "orca.keybindings",
1309 "orca.dbus_service",
1310 "orca.debug",
1311 "orca.focus_manager",
1312 "orca.AXObject",
1313 "orca.AXUtilities",
1314 ],
1315 )
1316 self._setup_mocks(test_context, essential_modules)
1317
1318 from orca.structural_navigator import NavigationMode
1319
1320 if mode_value == "OFF":
1321 assert NavigationMode.OFF.value == "OFF"
1322 elif mode_value == "DOCUMENT":
1323 assert NavigationMode.DOCUMENT.value == "DOCUMENT"
1324 elif mode_value == "GUI":
1325 assert NavigationMode.GUI.value == "GUI"
1326
1327 def test_basic_structural_navigator_state(self, test_context: OrcaTestContext) -> None:
1328 """Test StructuralNavigator basic state management."""
1329
1330 essential_modules = test_context.setup_shared_dependencies(
1331 [
1332 "orca.keybindings",
1333 "orca.dbus_service",
1334 "orca.debug",
1335 "orca.focus_manager",
1336 "orca.AXObject",
1337 "orca.AXUtilities",
1338 ],
1339 )
1340 self._setup_mocks(test_context, essential_modules)
1341
1342 from orca.structural_navigator import StructuralNavigator
1343
1344 navigator = StructuralNavigator()
1345 assert navigator._last_input_event is None
1346 assert navigator._suspended is False
1347 assert isinstance(navigator._mode_for_script, dict)
1348
1349 def test_get_is_enabled(self, test_context: OrcaTestContext) -> None:
1350 """Test StructuralNavigator.get_is_enabled returns setting value."""
1351
1352 self._setup_dependencies(test_context)
1353 from orca.structural_navigator import get_navigator
1354
1355 nav = get_navigator()
1356 result = nav.get_is_enabled()
1357 assert result is True
1358
1359 def test_set_is_enabled_no_change(self, test_context: OrcaTestContext) -> None:
1360 """Test StructuralNavigator.set_is_enabled returns early if value unchanged."""
1361
1362 self._setup_dependencies(test_context)
1363 from orca.structural_navigator import get_navigator
1364
1365 nav = get_navigator()
1366 result = nav.set_is_enabled(True)
1367 assert result is True
1368
1369 def test_set_is_enabled_true_with_previous_mode(self, test_context: OrcaTestContext) -> None:
1370 """Test StructuralNavigator.set_is_enabled restores previous mode when enabling."""
1371
1372 essential_modules = self._setup_dependencies(test_context)
1373 mock_script = test_context.Mock()
1374 essential_modules[
1375 "orca.script_manager"
1376 ].get_manager.return_value.get_active_script.return_value = mock_script
1377 mock_cmd_mgr = test_context.Mock()
1378 essential_modules["orca.command_manager"].get_manager.return_value = mock_cmd_mgr
1379
1380 from orca import gsettings_registry
1381 from orca.structural_navigator import NavigationMode, get_navigator
1382
1383 gsettings_registry.get_registry().set_runtime_value(
1384 "structural-navigation",
1385 "enabled",
1386 False,
1387 )
1388 nav = get_navigator()
1389 nav._previous_mode_for_script[mock_script] = NavigationMode.DOCUMENT
1390 test_context.patch_object(nav, "_is_active_script", return_value=True)
1391
1392 result = nav.set_is_enabled(True)
1393 assert result is True
1394 assert nav._mode_for_script[mock_script] == NavigationMode.DOCUMENT
1395 mock_cmd_mgr.set_group_enabled.assert_called_once()
1396
1397 def test_set_is_enabled_true_without_previous_mode(self, test_context: OrcaTestContext) -> None:
1398 """Test StructuralNavigator.set_is_enabled without previous mode when enabling."""
1399
1400 essential_modules = self._setup_dependencies(test_context)
1401 mock_script = test_context.Mock()
1402 essential_modules[
1403 "orca.script_manager"
1404 ].get_manager.return_value.get_active_script.return_value = mock_script
1405 mock_cmd_mgr = test_context.Mock()
1406 essential_modules["orca.command_manager"].get_manager.return_value = mock_cmd_mgr
1407
1408 from orca import gsettings_registry
1409 from orca.structural_navigator import get_navigator
1410
1411 gsettings_registry.get_registry().set_runtime_value(
1412 "structural-navigation",
1413 "enabled",
1414 False,
1415 )
1416 nav = get_navigator()
1417 test_context.patch_object(nav, "_is_active_script", return_value=True)
1418
1419 result = nav.set_is_enabled(True)
1420 assert result is True
1421 mock_cmd_mgr.set_group_enabled.assert_called_once()
1422
1423 def test_set_is_enabled_false_saves_mode(self, test_context: OrcaTestContext) -> None:
1424 """Test StructuralNavigator.set_is_enabled saves current mode when disabling."""
1425
1426 essential_modules = self._setup_dependencies(test_context)
1427 mock_script = test_context.Mock()
1428 essential_modules[
1429 "orca.script_manager"
1430 ].get_manager.return_value.get_active_script.return_value = mock_script
1431 mock_cmd_mgr = test_context.Mock()
1432 essential_modules["orca.command_manager"].get_manager.return_value = mock_cmd_mgr
1433 from orca.structural_navigator import NavigationMode, get_navigator
1434
1435 nav = get_navigator()
1436 nav._mode_for_script[mock_script] = NavigationMode.DOCUMENT
1437 test_context.patch_object(nav, "_is_active_script", return_value=True)
1438
1439 result = nav.set_is_enabled(False)
1440 assert result is True
1441 assert nav._previous_mode_for_script[mock_script] == NavigationMode.DOCUMENT
1442 assert nav._mode_for_script[mock_script] == NavigationMode.OFF
1443 mock_cmd_mgr.set_group_enabled.assert_called_once()
1444
1445 def test_set_is_enabled_false_already_off(self, test_context: OrcaTestContext) -> None:
1446 """Test StructuralNavigator.set_is_enabled returns early if already OFF."""
1447
1448 essential_modules = self._setup_dependencies(test_context)
1449 mock_script = test_context.Mock()
1450 essential_modules[
1451 "orca.script_manager"
1452 ].get_manager.return_value.get_active_script.return_value = mock_script
1453 mock_cmd_mgr = test_context.Mock()
1454 essential_modules["orca.command_manager"].get_manager.return_value = mock_cmd_mgr
1455 from orca.structural_navigator import NavigationMode, get_navigator
1456
1457 nav = get_navigator()
1458 nav._mode_for_script[mock_script] = NavigationMode.OFF
1459
1460 result = nav.set_is_enabled(False)
1461 assert result is True
1462 mock_cmd_mgr.set_group_enabled.assert_not_called()
1463
1464 def test_get_triggers_focus_mode(self, test_context: OrcaTestContext) -> None:
1465 """Test StructuralNavigator.get_triggers_focus_mode returns setting value."""
1466
1467 self._setup_dependencies(test_context)
1468 from orca.structural_navigator import get_navigator
1469
1470 nav = get_navigator()
1471 result = nav.get_triggers_focus_mode()
1472 assert result is False
1473
1474 def test_set_triggers_focus_mode(self, test_context: OrcaTestContext) -> None:
1475 """Test StructuralNavigator.set_triggers_focus_mode updates setting."""
1476
1477 self._setup_dependencies(test_context)
1478 from orca import gsettings_registry
1479 from orca.structural_navigator import get_navigator
1480
1481 gsettings_registry.get_registry().set_runtime_value(
1482 "structural-navigation",
1483 "triggers-focus-mode",
1484 True,
1485 )
1486
1487 nav = get_navigator()
1488 result = nav.set_triggers_focus_mode(False)
1489 assert result is True
1490 assert nav.get_triggers_focus_mode() is False
1491
1492 def test_set_triggers_focus_mode_no_change(self, test_context: OrcaTestContext) -> None:
1493 """Test StructuralNavigator.set_triggers_focus_mode returns early if unchanged."""
1494
1495 self._setup_dependencies(test_context)
1496 from orca import gsettings_registry
1497 from orca.structural_navigator import get_navigator
1498
1499 gsettings_registry.get_registry().set_runtime_value(
1500 "structural-navigation",
1501 "triggers-focus-mode",
1502 True,
1503 )
1504
1505 nav = get_navigator()
1506 result = nav.set_triggers_focus_mode(True)
1507 assert result is True
1508
1509 def test_last_command_prevents_focus_mode_true(self, test_context: OrcaTestContext) -> None:
1510 """Test StructuralNavigator.last_command_prevents_focus_mode returns True."""
1511
1512 essential_modules = self._setup_dependencies(test_context)
1513 essential_modules[
1514 "orca.input_event_manager"
1515 ].get_manager.return_value.last_event_equals_or_is_release_for_event.return_value = True
1516 from orca.structural_navigator import get_navigator
1517
1518 nav = get_navigator()
1519 mock_event = test_context.Mock()
1520 nav._last_input_event = mock_event
1521 result = nav.last_command_prevents_focus_mode()
1522 assert result is True
1523
1524 def test_last_command_prevents_focus_mode_false_no_event(
1525 self,
1526 test_context: OrcaTestContext,
1527 ) -> None:
1528 """Test StructuralNavigator.last_command_prevents_focus_mode returns False if no event."""
1529
1530 self._setup_dependencies(test_context)
1531 from orca.structural_navigator import get_navigator
1532
1533 nav = get_navigator()
1534 nav._last_input_event = None
1535 result = nav.last_command_prevents_focus_mode()
1536 assert result is False
1537
1538 def test_last_command_prevents_focus_mode_false_setting_true(
1539 self,
1540 test_context: OrcaTestContext,
1541 ) -> None:
1542 """Test last_command_prevents_focus_mode returns False if setting True."""
1543
1544 self._setup_dependencies(test_context)
1545
1546 from orca import gsettings_registry
1547 from orca.structural_navigator import get_navigator
1548
1549 gsettings_registry.get_registry().set_runtime_value(
1550 "structural-navigation",
1551 "triggers-focus-mode",
1552 True,
1553 )
1554 nav = get_navigator()
1555 mock_event = test_context.Mock()
1556 nav._last_input_event = mock_event
1557 result = nav.last_command_prevents_focus_mode()
1558 assert result is False
1559
1560 def test_present_line_emits_region_changed(self, test_context: OrcaTestContext) -> None:
1561 """Test _present_line emits region_changed with STRUCTURAL_NAVIGATOR mode."""
1562
1563 essential_modules = self._setup_dependencies(test_context)
1564 from orca import focus_manager
1565 from orca.structural_navigator import NavigationMode, get_navigator
1566
1567 focus_manager_mock = essential_modules["orca.focus_manager"]
1568 manager_instance = test_context.Mock()
1569 focus_manager_mock.get_manager.return_value = manager_instance
1570 manager_instance.in_say_all.return_value = False
1571 focus_manager_mock.STRUCTURAL_NAVIGATOR = focus_manager.STRUCTURAL_NAVIGATOR
1572
1573 nav = get_navigator()
1574 mock_script = test_context.Mock()
1575 mock_obj = test_context.Mock()
1576 test_offset = 5
1577
1578 test_context.patch_object(nav, "get_mode", return_value=NavigationMode.DOCUMENT)
1579 mock_script.utilities.get_line_contents_at_offset.return_value = [
1580 (mock_obj, test_offset, test_offset + 10, "test text"),
1581 ]
1582
1583 nav._present_line(mock_script, mock_obj, test_offset, notify_user=True)
1584
1585 manager_instance.emit_region_changed.assert_called()
1586 call_kwargs = manager_instance.emit_region_changed.call_args
1587 assert call_kwargs.kwargs.get("mode") == focus_manager.STRUCTURAL_NAVIGATOR
1588
1589 def test_present_object_emits_region_changed_in_document_mode(
1590 self,
1591 test_context: OrcaTestContext,
1592 ) -> None:
1593 """Test _present_object emits region_changed with STRUCTURAL_NAVIGATOR mode."""
1594
1595 essential_modules = self._setup_dependencies(test_context)
1596 from orca import focus_manager
1597 from orca.structural_navigator import NavigationMode, get_navigator
1598
1599 focus_manager_mock = essential_modules["orca.focus_manager"]
1600 manager_instance = test_context.Mock()
1601 focus_manager_mock.get_manager.return_value = manager_instance
1602 manager_instance.in_say_all.return_value = False
1603 focus_manager_mock.STRUCTURAL_NAVIGATOR = focus_manager.STRUCTURAL_NAVIGATOR
1604
1605 nav = get_navigator()
1606 mock_script = test_context.Mock()
1607 mock_obj = test_context.Mock()
1608 test_offset = 10
1609
1610 test_context.patch_object(nav, "get_mode", return_value=NavigationMode.DOCUMENT)
1611
1612 nav._present_object(mock_script, mock_obj, offset=test_offset, notify_user=True)
1613
1614 manager_instance.emit_region_changed.assert_called()
1615 call_kwargs = manager_instance.emit_region_changed.call_args
1616 assert call_kwargs.kwargs.get("mode") == focus_manager.STRUCTURAL_NAVIGATOR