Debian Codegraph @

tests/unit_tests/test_braille.py

raw
1 # Unit tests for braille.py functionality.
2 #
3 # Copyright 2026 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 # pylint: disable=protected-access
21 # pylint: disable=import-outside-toplevel
22
23 """Unit tests for braille.py functionality."""
24
25 from __future__ import annotations
26
27 from typing import TYPE_CHECKING
28
29 import pytest
30
31 if TYPE_CHECKING:
32 from .orca_test_context import OrcaTestContext
33
34
35 @pytest.mark.unit
36 class TestBrailleLineRanges:
37 """Tests for braille line range computation."""
38
39 def _setup_dependencies(self, test_context: OrcaTestContext) -> None:
40 debug_mock = test_context.Mock()
41 debug_mock.LEVEL_INFO = 800
42 debug_mock.print_message = test_context.Mock()
43 debug_mock.print_tokens = test_context.Mock()
44
45 ax_event_synthesizer_mock = test_context.Mock()
46 ax_event_synthesizer_mock.AXEventSynthesizer = test_context.Mock()
47
48 ax_hypertext_mock = test_context.Mock()
49 ax_hypertext_mock.AXHypertext = test_context.Mock()
50
51 ax_object_mock = test_context.Mock()
52 ax_object_mock.AXObject = test_context.Mock()
53
54 ax_text_mock = test_context.Mock()
55 ax_text_mock.AXText = test_context.Mock()
56 ax_text_mock.AXTextAttribute = test_context.Mock()
57
58 ax_utilities_mock = test_context.Mock()
59 ax_utilities_mock.AXUtilities = test_context.Mock()
60
61 platform_mock = test_context.Mock()
62 platform_mock.tablesdir = "/tmp"
63
64 braille_presenter_mock = test_context.Mock()
65 braille_presenter_mock.get_presenter.return_value.use_braille.return_value = True
66
67 test_context.patch_modules(
68 {
69 "orca.braille_monitor": test_context.Mock(),
70 "orca.braille_presenter": braille_presenter_mock,
71 "orca.brltablenames": test_context.Mock(),
72 "orca.cmdnames": test_context.Mock(),
73 "orca.debug": debug_mock,
74 "orca.script_manager": test_context.Mock(),
75 "orca.text_attribute_manager": test_context.Mock(),
76 "orca.ax_event_synthesizer": ax_event_synthesizer_mock,
77 "orca.ax_hypertext": ax_hypertext_mock,
78 "orca.ax_object": ax_object_mock,
79 "orca.ax_text": ax_text_mock,
80 "orca.ax_utilities": ax_utilities_mock,
81 "orca.orca_platform": platform_mock,
82 },
83 )
84
85 def test_compute_ranges_basic(self, test_context: OrcaTestContext) -> None:
86 """Compute ranges across words when the display width is exceeded."""
87
88 self._setup_dependencies(test_context)
89 from orca import braille
90
91 ranges = braille._compute_ranges("Hello world", -1, 10)
92 assert ranges == [[0, 6], [6, 11]]
93
94 def test_compute_ranges_long_word(self, test_context: OrcaTestContext) -> None:
95 """Compute ranges for a single long word."""
96
97 self._setup_dependencies(test_context)
98 from orca import braille
99
100 ranges = braille._compute_ranges("abcdefghijk", -1, 4)
101 assert ranges == [[0, 4], [4, 8], [8, 11]]
102
103 def test_compute_ranges_splits_on_focus_offset(self, test_context: OrcaTestContext) -> None:
104 """Compute ranges that split on the focus offset."""
105
106 self._setup_dependencies(test_context)
107 from orca import braille
108
109 ranges = braille._compute_ranges("abc def", 4, 10)
110 assert ranges == [[0, 4], [4, 7]]
111
112 def test_get_region_at_cell_returns_region(self, test_context: OrcaTestContext) -> None:
113 """Return the region and offset for a given cell."""
114
115 self._setup_dependencies(test_context)
116 from orca import braille
117
118 braille._clear()
119 region = braille.Region("abc", 0)
120 line = braille.Line(region)
121 braille._set_lines([line])
122
123 region_info = braille.get_region_at_cell(2)
124 braille_region, offset_in_region = region_info
125 assert braille_region is region
126 assert offset_in_region == 1
127
128 def test_get_caret_context_non_text(self, test_context: OrcaTestContext) -> None:
129 """Return no caret context for non-text regions."""
130
131 self._setup_dependencies(test_context)
132 from orca import braille
133
134 braille._clear()
135 region = braille.Region("abc", 0)
136 braille._set_lines([braille.Line(region)])
137
138 event = test_context.Mock()
139 event.event = {"argument": 0}
140 context = braille.get_caret_context(event)
141 obj, offset = context
142 assert obj is None
143 assert offset == -1
144
145 def test_focus_invalidation_updates_focus_offset(self, test_context: OrcaTestContext) -> None:
146 """Ensure cache invalidation updates focus offsets when focus changes."""
147
148 self._setup_dependencies(test_context)
149 from orca import braille
150
151 braille._clear()
152 region_one = braille.Region("one", 0)
153 region_two = braille.Region("two", 0)
154 line = braille.Line()
155 line.add_regions([region_one, region_two])
156 braille._set_lines([line])
157
158 braille._set_focus(region_one)
159 first_info = line.get_info()
160 assert first_info.focus_offset == 0
161
162 braille._set_focus(region_two)
163 second_info = line.get_info()
164 assert second_info.focus_offset == len(region_one.string)
165
166 def test_display_message_sets_focus(self, test_context: OrcaTestContext) -> None:
167 """Display message should create a line and set focus."""
168
169 self._setup_dependencies(test_context)
170 from orca import braille
171
172 braille.refresh = test_context.Mock()
173
174 braille.display_message("hello", flash_time=0)
175
176 assert len(braille._STATE.lines) == 1
177 line = braille._STATE.lines[0]
178 regions = line.get_regions()
179 assert len(regions) == 1
180 assert braille._STATE.region_with_focus is regions[0]
181
182 def test_kill_flash_restores_state(self, test_context: OrcaTestContext) -> None:
183 """Kill flash should restore the saved state when present."""
184
185 self._setup_dependencies(test_context)
186 from orca import braille
187
188 braille.refresh = test_context.Mock()
189
190 region = braille.Region("restore", 0)
191 saved_line = braille.Line(region)
192 saved_state = braille._FlashState([saved_line], region, [3, 0], 500)
193 braille._STATE.saved = saved_state
194 braille._STATE.lines = []
195 braille._STATE.region_with_focus = None
196 braille._STATE.viewport = [0, 0]
197 braille._STATE.flash_event_source_id = -1
198
199 braille.kill_flash(restore_saved=True)
200
201 assert braille._STATE.lines == saved_state.lines
202 assert braille._STATE.region_with_focus is saved_state.region_with_focus
203 assert braille._STATE.viewport == saved_state.viewport
204 assert braille._STATE.flash_event_source_id == 0
205
206 def test_setup_key_ranges_skips_when_constants_missing(
207 self,
208 test_context: OrcaTestContext,
209 ) -> None:
210 """setup_key_ranges should no-op if required constants are missing."""
211
212 self._setup_dependencies(test_context)
213 from orca import braille
214
215 original_range_all = braille.BRLAPI_RANGE_TYPE_ALL
216 original_range_command = braille.BRLAPI_RANGE_TYPE_COMMAND
217 original_key_type = braille.BRLAPI_KEY_TYPE_CMD
218 original_key_route = braille.BRLAPI_KEY_CMD_ROUTE
219
220 braille.BRLAPI_RANGE_TYPE_ALL = None
221 braille.BRLAPI_RANGE_TYPE_COMMAND = None
222 braille.BRLAPI_KEY_TYPE_CMD = None
223 braille.BRLAPI_KEY_CMD_ROUTE = None
224 braille._STATE.brlapi_running = True
225 braille._STATE.brlapi = test_context.Mock()
226 braille._STATE.brlapi.ignoreKeys = test_context.Mock()
227
228 try:
229 braille.setup_key_ranges([1, 2, 3])
230 braille._STATE.brlapi.ignoreKeys.assert_not_called()
231 finally:
232 braille.BRLAPI_RANGE_TYPE_ALL = original_range_all
233 braille.BRLAPI_RANGE_TYPE_COMMAND = original_range_command
234 braille.BRLAPI_KEY_TYPE_CMD = original_key_type
235 braille.BRLAPI_KEY_CMD_ROUTE = original_key_route
236
237 def test_prepare_refresh_disabled_shuts_down(self, test_context: OrcaTestContext) -> None:
238 """_prepare_refresh should shut down and reset state when braille is disabled."""
239
240 self._setup_dependencies(test_context)
241 from orca import braille, braille_presenter
242
243 mock_presenter = braille_presenter.get_presenter.return_value # type: ignore[attr-defined] # pylint: disable=no-member
244 mock_presenter.use_braille.return_value = False
245 braille._STATE.brlapi_running = True
246 braille._STATE.last_text_info = braille._TextInfo(object(), 1, 2, 3)
247 braille.shutdown = test_context.Mock()
248
249 assert braille._prepare_refresh(stop_flash=False) is False
250 braille.shutdown.assert_called_once()
251 assert braille._STATE.last_text_info == braille._empty_text_info()
252
253 def test_prepare_refresh_empty_lines_clears_braille(
254 self,
255 test_context: OrcaTestContext,
256 ) -> None:
257 """_prepare_refresh should clear braille and reset state with no lines."""
258
259 self._setup_dependencies(test_context)
260 from orca import braille
261
262 braille._STATE.lines = []
263 braille._STATE.last_text_info = braille._TextInfo(object(), 1, 2, 3)
264 braille._clear_braille = test_context.Mock()
265
266 assert braille._prepare_refresh(stop_flash=False) is False
267 braille._clear_braille.assert_called_once()
268 assert braille._STATE.last_text_info == braille._empty_text_info()
269
270 def test_set_contracted_braille_toggles_for_keyboard_event(
271 self,
272 test_context: OrcaTestContext,
273 ) -> None:
274 """Non-braille events should toggle contracted braille."""
275
276 self._setup_dependencies(test_context)
277 from orca import braille
278
279 braille._STATE.enable_contracted_braille = False
280 braille.refresh = test_context.Mock()
281 event = test_context.Mock()
282 event.type = "keyboard"
283
284 braille.toggle_contracted_braille(event)
285
286 assert braille._STATE.enable_contracted_braille is True
287
288 def test_set_contracted_braille_uses_braille_flags(self, test_context: OrcaTestContext) -> None:
289 """Braille events should use the BrlAPI toggle flag."""
290
291 self._setup_dependencies(test_context)
292 from orca import braille
293
294 original_toggle = braille.BRLAPI_KEY_FLG_TOGGLE_ON
295 braille.refresh = test_context.Mock()
296 braille.BRLAPI_KEY_FLG_TOGGLE_ON = 1
297 event = test_context.Mock()
298 event.type = "braille"
299 event.event = {"flags": 1}
300
301 try:
302 braille.toggle_contracted_braille(event)
303 assert braille._STATE.enable_contracted_braille is True
304 finally:
305 braille.BRLAPI_KEY_FLG_TOGGLE_ON = original_toggle