Debian Codegraph @

tests/unit_tests/orca_test_context.py

raw
1 # Orca Test Context - Test Isolation Framework
2 #
3 # Copyright 2025 Igalia, S.L.
4 #
5 # This library is free software; you can redistribute it and/or
6 # modify it under the terms of the GNU Lesser General Public
7 # License as published by the Free Software Foundation; either
8 # version 2.1 of the License, or (at your option) any later version.
9 #
10 # This library is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 # Lesser General Public License for more details.
14 #
15 # You should have received a copy of the GNU Lesser General Public
16 # License along with this library; if not, write to the
17 # Free Software Foundation, Inc., Franklin Street, Fifth Floor,
18 # Boston MA 02110-1301 USA.
19
20 """Test isolation framework for Orca screen reader tests."""
21
22 from __future__ import annotations
23
24 import os
25 import sys
26 from typing import TYPE_CHECKING, Any
27
28 import gi
29
30 gi.require_version("Atspi", "2.0")
31 gi.require_version("Gio", "2.0")
32 from gi.repository import Atspi, Gio, GLib # pylint: disable=wrong-import-position
33
34 if TYPE_CHECKING:
35 from unittest.mock import MagicMock
36
37 from _pytest.monkeypatch import MonkeyPatch
38 from pytest_mock import MockerFixture
39
40
41 class OrcaTestContext:
42 """Test isolation framework for Orca tests."""
43
44 def __init__(self, mocker: MockerFixture, monkeypatch: MonkeyPatch):
45 """Initialize the test context."""
46
47 self.mocker: MockerFixture = mocker
48 self.monkeypatch: MonkeyPatch = monkeypatch
49 self.patches: dict[str, Any] = {}
50 self.mocks: dict[str, MagicMock] = {}
51
52 def patch(self, target: str, **kwargs) -> MagicMock:
53 """Convenience method for creating patches."""
54
55 return self.mocker.patch(target, **kwargs)
56
57 def patch_object(self, target: object, attribute: str, **kwargs) -> MagicMock:
58 """Convenience method for patching object attributes."""
59
60 return self.mocker.patch.object(target, attribute, **kwargs)
61
62 def Mock(self, **kwargs) -> MagicMock: # pylint: disable=invalid-name
63 """Convenience method for creating Mock objects."""
64
65 return self.mocker.Mock(**kwargs)
66
67 def patch_env(
68 self,
69 env_vars: dict[str, str],
70 remove_vars: list[str] | None = None,
71 ) -> MagicMock | None:
72 """Convenience method for patching environment variables."""
73
74 if remove_vars:
75 for var in remove_vars:
76 if var in os.environ:
77 del os.environ[var]
78
79 if env_vars:
80 return self.mocker.patch.dict(os.environ, env_vars)
81 return None
82
83 def patch_module(self, module_name: str, mock_module: Any) -> MagicMock:
84 """Convenience method for patching sys.modules entries."""
85
86 return self.mocker.patch.dict(sys.modules, {module_name: mock_module})
87
88 def patch_modules(self, modules: dict[str, Any]) -> MagicMock:
89 """Convenience method for patching multiple sys.modules entries."""
90
91 return self.mocker.patch.dict(sys.modules, modules)
92
93 def _setup_required_imports(self) -> None:
94 """Sets up commonly required module imports that real modules need."""
95
96 required_modules = [
97 "orca.orca_i18n",
98 "orca.cmdnames",
99 "orca.input_event",
100 "orca.keybindings",
101 "orca.messages",
102 "orca.text_attribute_names",
103 ]
104
105 for module_name in required_modules:
106 if module_name not in self.mocks:
107 mock_module = self.mocker.patch(module_name, create=True)
108 if module_name == "orca.orca_i18n":
109 mock_module._ = lambda x: x
110 self.mocks[module_name] = mock_module
111
112 def _setup_essential_modules(self, module_names: list[str]) -> dict[str, MagicMock]:
113 """Returns dictionary mapping module names to mock objects."""
114
115 essential_modules = {}
116 for module_name in module_names:
117 mock_module = self.mocker.Mock()
118 self.patch_module(module_name, mock_module)
119 essential_modules[module_name] = mock_module
120 return essential_modules
121
122 def setup_shared_dependencies(
123 self,
124 additional_modules: list[str] | None = None,
125 ) -> dict[str, MagicMock]:
126 """Returns common/shared dependencies used across most Orca test modules."""
127
128 core_modules = [
129 "orca.debug",
130 "orca.messages",
131 "orca.input_event",
132 "orca.keybindings",
133 "orca.cmdnames",
134 "orca.ax_object",
135 "orca.dbus_service",
136 "orca.script_manager",
137 "orca.orca_i18n",
138 "orca.guilabels",
139 "orca.text_attribute_names",
140 "orca.focus_manager",
141 "orca.braille",
142 "orca.orca_platform",
143 ]
144
145 if additional_modules:
146 core_modules.extend(additional_modules)
147
148 essential_modules = self._setup_essential_modules(core_modules)
149 self.configure_shared_module_behaviors(essential_modules)
150 return essential_modules
151
152 # pylint: disable-next=too-many-locals, too-many-statements, too-many-branches
153 def configure_shared_module_behaviors(self, essential_modules: dict[str, MagicMock]) -> None:
154 """Configure standard behaviors for shared modules to reduce duplication."""
155
156 if "orca.orca_i18n" in essential_modules:
157 i18n_mock = essential_modules["orca.orca_i18n"]
158 i18n_mock._ = lambda x: x
159 i18n_mock.C_ = lambda c, x: x
160 i18n_mock.ngettext = lambda s, p, n: s if n == 1 else p
161
162 if "orca.debug" in essential_modules:
163 debug_mock = essential_modules["orca.debug"]
164 debug_mock.LEVEL_INFO = 800
165 debug_mock.LEVEL_SEVERE = 1000
166 debug_mock.print_message = self.mocker.Mock()
167 debug_mock.print_tokens = self.mocker.Mock()
168 debug_mock.println = self.mocker.Mock()
169
170 if "orca.keybindings" in essential_modules:
171 keybindings_mock = essential_modules["orca.keybindings"]
172 bindings_instance = self.mocker.Mock()
173 bindings_instance.is_empty = self.mocker.Mock(return_value=True)
174 bindings_instance.add = self.mocker.Mock()
175 keybindings_mock.KeyBindings = self.mocker.Mock(return_value=bindings_instance)
176 keybindings_mock.KeyBinding = self.mocker.Mock(return_value=self.mocker.Mock())
177 keybindings_mock.DEFAULT_MODIFIER_MASK = 1
178 keybindings_mock.ORCA_SHIFT_MODIFIER_MASK = 2
179
180 if "orca.focus_manager" in essential_modules:
181 focus_manager_mock = essential_modules["orca.focus_manager"]
182 manager_instance = self.mocker.Mock()
183 manager_instance.get_locus_of_focus = self.mocker.Mock(return_value=None)
184 manager_instance.set_locus_of_focus = self.mocker.Mock()
185 manager_instance.in_say_all = self.mocker.Mock(return_value=False)
186 manager_instance.is_in_preferences_window = self.mocker.Mock(return_value=False)
187 manager_instance.get_active_mode_and_object_of_interest = self.mocker.Mock(
188 return_value=(None, None),
189 )
190 focus_manager_mock.get_manager = self.mocker.Mock(return_value=manager_instance)
191 focus_manager_mock.OBJECT_NAVIGATOR = "object-navigator"
192 essential_modules["focus_manager_instance"] = manager_instance
193
194 if "orca.dbus_service" in essential_modules:
195 dbus_service_mock = essential_modules["orca.dbus_service"]
196 controller_mock = self.mocker.Mock()
197 controller_mock.register_decorated_module = self.mocker.Mock()
198 dbus_service_mock.get_remote_controller = self.mocker.Mock(return_value=controller_mock)
199 dbus_service_mock.command = lambda func: func
200 dbus_service_mock.getter = lambda func: func
201 dbus_service_mock.setter = lambda func: func
202 dbus_service_mock.parameterized_command = lambda func: func
203
204 if "orca.script_manager" in essential_modules:
205 script_manager_mock = essential_modules["orca.script_manager"]
206 manager_instance = self.mocker.Mock()
207 script_instance = self.mocker.Mock()
208 script_instance.present_message = self.mocker.Mock()
209 script_instance.present_object = self.mocker.Mock()
210 script_instance.speak_message = self.mocker.Mock()
211 script_instance.update_braille = self.mocker.Mock()
212 speech_gen = self.mocker.Mock()
213 braille_gen = self.mocker.Mock()
214 script_instance.get_speech_generator = self.mocker.Mock(return_value=speech_gen)
215 script_instance.get_braille_generator = self.mocker.Mock(return_value=braille_gen)
216 manager_instance.get_active_script = self.mocker.Mock(return_value=script_instance)
217 manager_instance.get_script = self.mocker.Mock(return_value=script_instance)
218 manager_instance.get_manager = self.mocker.Mock(return_value=manager_instance)
219 script_manager_mock.get_manager = self.mocker.Mock(return_value=manager_instance)
220
221 if "orca.ax_object" in essential_modules:
222 ax_object_mock = essential_modules["orca.ax_object"]
223 ax_object_class_mock = self.mocker.Mock()
224 ax_object_class_mock.is_valid = self.mocker.Mock(return_value=True)
225 ax_object_class_mock.is_dead = self.mocker.Mock(return_value=False)
226 ax_object_class_mock.get_name = self.mocker.Mock(return_value="")
227 ax_object_class_mock.get_role = self.mocker.Mock(return_value=Atspi.Role.PANEL)
228 ax_object_class_mock.get_parent = self.mocker.Mock(return_value=None)
229 ax_object_class_mock.find_ancestor = self.mocker.Mock(return_value=None)
230 ax_object_class_mock.clear_cache = self.mocker.Mock()
231 ax_object_mock.AXObject = ax_object_class_mock
232
233 if "orca.ax_utilities" in essential_modules:
234 ax_utilities_mock = essential_modules["orca.ax_utilities"]
235 ax_utilities_class_mock = self.mocker.Mock()
236 ax_utilities_class_mock.is_focused = self.mocker.Mock(return_value=True)
237 ax_utilities_class_mock.is_table_cell_or_header = self.mocker.Mock(return_value=False)
238 ax_utilities_class_mock.is_list_item = self.mocker.Mock(return_value=False)
239 ax_utilities_class_mock.is_layout_only = self.mocker.Mock(return_value=False)
240 ax_utilities_class_mock.get_status_bar = self.mocker.Mock(return_value=None)
241 ax_utilities_class_mock.get_info_bar = self.mocker.Mock(return_value=None)
242 ax_utilities_class_mock.is_showing = self.mocker.Mock(return_value=True)
243 ax_utilities_class_mock.is_visible = self.mocker.Mock(return_value=True)
244 ax_utilities_class_mock.is_sensitive = self.mocker.Mock(return_value=True)
245 ax_utilities_mock.AXUtilities = ax_utilities_class_mock
246
247 if "orca.input_event" in essential_modules:
248 input_event_mock = essential_modules["orca.input_event"]
249 input_event_mock.KEY_PRESSED_EVENT = "key-pressed"
250 input_event_mock.KEY_RELEASED_EVENT = "key-released"
251 input_event_mock.MOUSE_BUTTON_CLICKED_EVENT = "mouse-clicked"
252
253 if "orca.orca_platform" in essential_modules:
254 orca_platform_mock = essential_modules["orca.orca_platform"]
255 orca_platform_mock.tablesdir = "/usr/share/liblouis/tables"
256
257 if "orca.braille_presenter" in essential_modules:
258 braille_presenter_mock = essential_modules["orca.braille_presenter"]
259 presenter_instance = self.mocker.Mock()
260 presenter_instance.use_braille = self.mocker.Mock(return_value=False)
261 presenter_instance.get_braille_is_enabled = self.mocker.Mock(return_value=False)
262 presenter_instance.get_flash_messages_are_enabled = self.mocker.Mock(return_value=False)
263 presenter_instance.get_flash_messages_are_detailed = self.mocker.Mock(
264 return_value=False,
265 )
266 presenter_instance.get_flashtime_from_settings = self.mocker.Mock(return_value=5000)
267 braille_presenter_mock.get_presenter = self.mocker.Mock(return_value=presenter_instance)
268
269 if "orca.presentation_manager" in essential_modules:
270 presentation_manager_mock = essential_modules["orca.presentation_manager"]
271 manager_instance = self.mocker.Mock()
272 manager_instance.interrupt_presentation = self.mocker.Mock()
273 manager_instance.present_message = self.mocker.Mock()
274 manager_instance.speak_message = self.mocker.Mock()
275 manager_instance.speak_character = self.mocker.Mock()
276 manager_instance.present_braille_message = self.mocker.Mock()
277 manager_instance.spell_item = self.mocker.Mock()
278 manager_instance.spell_phonetically = self.mocker.Mock()
279 manager_instance.play_sound = self.mocker.Mock()
280 manager_instance.speak_contents = self.mocker.Mock()
281 manager_instance.display_contents = self.mocker.Mock()
282 presentation_manager_mock.get_manager = self.mocker.Mock(return_value=manager_instance)
283
284 if "gi.repository" in essential_modules:
285 gi_repo_mock = essential_modules["gi.repository"]
286 gi_repo_mock.Gio = Gio
287 gi_repo_mock.GLib = GLib
288
289 def get_mock(self, name: str) -> MagicMock | None:
290 """Returns mock object if it exists, None otherwise."""
291
292 return self.mocks.get(name)
293
294 def __enter__(self) -> OrcaTestContext: # noqa: PYI034
295 """Enter the test context."""
296
297 return self
298
299 def __exit__(self, exc_type, exc_val, exc_tb) -> None:
300 """Exit the test context and clean up all patches."""
301
302 for patch_obj in self.patches.values():
303 patch_obj.stop()
304
305 self.patches.clear()
306 self.mocks.clear()