Debian Codegraph @

tests/README.md

raw
1 # Orca Tests: Work in Progress
2
3 This is the beginning of Orca's new unit test and integration test support.
4
5 ## Status
6
7 * Basic test coverage for the D-Bus Remote Controller: DONE
8 * Advanced test coverage for the D-Bus Remote Controller: TODO
9 * Needed: A means to load document content, apps with UI for the navigators and presenters
10 * Unit test coverage of the AX* utilities: DONE
11 * Unit test coverage of the "Managers": DONE
12 * Unit test coverage of the "Presenters": DONE
13 * Unit test coverage of the "Navigators": DONE
14 * Unit test coverage of generators: TODO
15 * Unit test coverage of scripts: TODO
16 * Integration/advanced test coverage of all of the above: TODO
17 * Needed: Real AT-SPI2 objects
18 * Meson support: DONE
19 * Integration into Orca's Gitlab CI: TODO
20
21 ## Dependencies
22
23 * [pytest](https://pytest.org)
24 * [pytest-mock](https://pytest-mock.readthedocs.io/) - Mock plugin for pytest
25
26 ## Running Tests
27
28 ### Using Meson
29
30 ```bash
31 meson test -C _build # All tests
32 meson test -C _build --suite unit # Unit tests only
33 meson test -C _build --suite integration # Integration tests only
34 ```
35
36 ### Using Pytest
37
38 ```bash
39 pytest tests/unit_tests/ # All unit tests
40 coverage run -m pytest tests/unit_tests # Unit tests with coverage
41 python3 -m pytest tests/unit_tests/test_ax_text.py -v # Specific file
42 ```
43
44 ## Adding New Tests
45
46 ### 1. Create Test File
47
48 Follow naming convention: `test_[module_name].py`
49
50 ### 2. Test File Structure
51
52 ```python
53 from typing import TYPE_CHECKING
54 import pytest
55
56 if TYPE_CHECKING:
57 from .orca_test_context import OrcaTestContext
58 from unittest.mock import MagicMock
59
60 @pytest.mark.unit
61 class TestMyModule:
62 """Test MyModule class methods."""
63
64 def _setup_dependencies(self, test_context: OrcaTestContext) -> dict[str, MagicMock]:
65 """Set up mocks for my_module dependencies."""
66
67 # Use setup_shared_dependencies for common modules
68 additional_modules = ["orca.module_specific_to_my_module"]
69 essential_modules = test_context.setup_shared_dependencies(additional_modules)
70
71 # Configure module-specific behavior
72 my_mock = essential_modules["orca.module_specific_to_my_module"]
73 my_mock.some_method.return_value = "expected_value"
74
75 return essential_modules
76
77 def test_my_function(self, test_context: OrcaTestContext) -> None:
78 """Test MyModule.my_function behavior."""
79
80 # Set up mocks BEFORE importing the module under test.
81 # Python's import system caches modules - if MyModule imports its
82 # dependencies before we mock them, it gets the real modules.
83 self._setup_dependencies(test_context)
84
85 # Import AFTER mocks are set up so MyModule gets our mocked dependencies.
86 from orca.my_module import MyModule
87
88 result = MyModule.my_function()
89 assert result == "expected_value"
90 ```
91
92 ### 3. Mocking and Patching
93
94 The `test_context` fixture provides testing utilities using pytest-mock patterns:
95
96 #### `test_context.Mock()`
97
98 * Creates mock objects consistently across all tests
99 * Use `spec=` when the class itself hasn't been replaced (even if you're mocking instances of it)
100 * Omit `spec=` for method replacements, function replacements, class replacements, and ad-hoc test data
101
102 ```python
103 # Use spec when the class itself hasn't been replaced
104 mock_accessible = test_context.Mock(spec=Atspi.Accessible)
105 mock_accessible.get_name.return_value = "Test Button"
106
107 # Mock a function and use the spec mock as return value
108 mock_match_rule_new = test_context.Mock()
109 test_context.patch("gi.repository.Atspi.MatchRule.new", side_effect=mock_match_rule_new)
110 mock_rule = test_context.Mock(spec=Atspi.MatchRule)
111 mock_match_rule_new.return_value = mock_rule
112
113 # Don't use spec when the class itself is being mocked
114 mock_state_set_class = test_context.Mock()
115 test_context.patch("gi.repository.Atspi.StateSet", new=mock_state_set_class)
116 mock_state_set = test_context.Mock() # StateSet class was replaced, can't use spec
117 mock_state_set_class.return_value = mock_state_set
118
119 # Don't use spec for method/function replacements
120 debug_mock.print_message = test_context.Mock()
121 mock_function = test_context.Mock()
122 test_context.patch("module.function", side_effect=mock_function)
123
124 # Don't use spec for ad-hoc test data
125 test_config = test_context.Mock()
126 test_config.enabled = True
127 ```
128
129 #### `test_context.patch()` and `test_context.patch_object()`
130
131 * Returns mock objects for assertions
132 * Use `patch()` for string-based patching of deep module paths
133 * Use `patch_object()` for patching attributes on existing objects
134
135 ```python
136 mock_clear_cache = test_context.patch("gi.repository.Atspi.Accessible.clear_cache")
137 AXObject.clear_cache(mock_accessible, recursive=True)
138 mock_clear_cache.assert_called_once_with(mock_accessible)
139
140 mock_present_line = test_context.patch_object(presenter, "present_line")
141 presenter.go_previous_line(script_mock, event_mock)
142 mock_present_line.assert_called_once_with(script_mock, event_mock)
143 ```
144
145 #### `test_context.patch_module()` and `test_context.patch_modules()`
146
147 * Use instead of `patch()` or `patch_object()` when you need to replace entire modules in `sys.modules`
148 * Useful when the module under test imports dependencies at module level
149 * Ensures the mock module is available when the test module imports it
150
151 ```python
152 # Single module replacement
153 mock_module = test_context.Mock()
154 test_context.patch_module("orca.special_module", mock_module)
155
156 # Multiple modules at once
157 test_context.patch_modules({
158 "orca.module1": mock_module1,
159 "orca.module2": mock_module2
160 })
161 ```
162
163 #### `test_context.patch_env()`
164
165 * Patches environment variables for the test duration
166 * Can add new variables or remove existing ones
167
168 ```python
169 test_context.patch_env(
170 {"XDG_SESSION_TYPE": "wayland", "HOME": "/tmp/test"},
171 remove_vars=["DISPLAY"]
172 )
173 ```
174
175 #### Shared Dependencies
176
177 Most tests should use `test_context.setup_shared_dependencies()` which provides common modules like:
178
179 * `orca.debug` - Debugging and logging
180 * `orca.messages` - User messages
181 * `orca.input_event` - Event handling
182 * `orca.settings` - Configuration
183 * `orca.keybindings` - Keyboard shortcuts
184 * And many others with pre-configured behaviors
185
186 ### 4. Parameterized Tests
187
188 Use pytest's parameterize decorator for testing multiple inputs efficiently.
189
190 #### Simple Parameters
191
192 For straightforward test cases:
193
194 ```python
195 @pytest.mark.parametrize(
196 "focus, window, expected",
197 [
198 pytest.param(None, None, True, id="both_none"),
199 pytest.param(None, "window", False, id="focus_none_window_set"),
200 pytest.param("focus", None, False, id="focus_set_window_none"),
201 pytest.param("focus", "window", False, id="both_set"),
202 ],
203 )
204 def test_focus_and_window_are_unknown(self, test_context, focus, window, expected):
205 """Test FocusManager.focus_and_window_are_unknown."""
206
207 self._setup_dependencies(test_context)
208 from orca.focus_manager import FocusManager
209
210 manager = FocusManager()
211 focus_obj = test_context.Mock(spec=Atspi.Accessible) if focus else None
212 window_obj = test_context.Mock(spec=Atspi.Accessible) if window else None
213 test_context.patch_object(manager, "_focus", new=focus_obj)
214 test_context.patch_object(manager, "_window", new=window_obj)
215 result = manager.focus_and_window_are_unknown()
216 assert result == expected
217 ```
218
219 #### Dictionary with ID Lambda
220
221 For tests with complex configurations:
222
223 ```python
224 @pytest.mark.parametrize(
225 "case",
226 [
227 {
228 "id": "layout_only_role",
229 "mocks_config": {"ax_object.get_role": Atspi.Role.FILLER},
230 "expected": True,
231 },
232 {
233 "id": "group_with_explicit_name",
234 "mocks_config": {
235 "ax_utilities_role.is_group": True,
236 "has_explicit_name": True
237 },
238 "expected": False,
239 },
240 {
241 "id": "layered_pane_in_desktop",
242 "mocks_config": {
243 "ax_utilities_role.is_layered_pane": True,
244 "ax_utilities_role.is_desktop_frame": True,
245 "ax_object.find_ancestor": "desktop",
246 },
247 "expected": True,
248 },
249 ],
250 ids=lambda case: case["id"],
251 )
252 def test_is_layout_only_scenarios(self, test_context: OrcaTestContext, case: dict):
253 """Test AXUtilities.is_layout_only with various scenarios."""
254
255 mocks_config = case["mocks_config"]
256 expected = case["expected"]
257 essential_modules = self._setup_dependencies(test_context)
258
259 for mock_path, mock_value in mocks_config.items():
260 if mock_path == "has_explicit_name":
261 test_context.patch(
262 "orca.ax_utilities.AXUtilities.has_explicit_name",
263 return_value=mock_value,
264 )
265 elif mock_path.startswith("ax_object.get_role"):
266 essential_modules["orca.ax_object"].AXObject.get_role = test_context.Mock(
267 return_value=mock_value
268 )
269 elif mock_path.startswith("ax_utilities_role."):
270 method_name = mock_path.split(".", 1)[1]
271 setattr(
272 essential_modules["orca.ax_utilities_role"].AXUtilitiesRole,
273 method_name,
274 test_context.Mock(return_value=mock_value),
275 )
276
277 from orca.ax_utilities import AXUtilities
278 mock_obj = test_context.Mock(spec=Atspi.Accessible)
279 result = AXUtilities.is_layout_only(mock_obj)
280 assert result is expected
281 ```
282
283 Benefits of parameterized tests:
284
285 * Test multiple scenarios efficiently
286 * Clear test case identification
287 * Easy to add new test cases
288 * Better coverage with less code duplication
289 * Dictionary pattern keeps related test data together