1use std::{cell::RefCell, rc::Rc};
2
3use sui_core::{
4 Error, Event, ImeEvent, KeyState, KeyboardEvent, Point, PointerButton, PointerButtons,
5 PointerEvent, PointerEventKind, PointerKind, Rect, Result, ScrollDelta, SemanticsNode, Vector,
6 WidgetId, WindowId,
7};
8use sui_platform::AccessibilitySnapshot;
9
10use crate::{
11 diagnostics::format_failure, expect::Expectation, harness::Harness, screenshot::Screenshot,
12 selector::Selector,
13};
14
15#[derive(Clone)]
16pub struct Locator {
17 harness: Rc<RefCell<Harness>>,
18 window_id: WindowId,
19 scopes: Vec<Selector>,
20 selector: Selector,
21}
22
23impl Locator {
24 pub(crate) fn new(
25 harness: Rc<RefCell<Harness>>,
26 window_id: WindowId,
27 selector: Selector,
28 ) -> Self {
29 Self {
30 harness,
31 window_id,
32 scopes: Vec::new(),
33 selector,
34 }
35 }
36
37 pub fn locator(&self, selector: Selector) -> Self {
38 let mut scopes = self.scopes.clone();
39 scopes.push(self.selector.clone());
40
41 Self {
42 harness: Rc::clone(&self.harness),
43 window_id: self.window_id,
44 scopes,
45 selector,
46 }
47 }
48
49 pub fn focused(&self) -> Self {
50 self.locator(Selector::focused())
51 }
52
53 pub fn get_by_role(&self, role: sui_core::SemanticsRole) -> Self {
54 self.locator(Selector::by_role(role))
55 }
56
57 pub fn get_by_text(&self, text: impl Into<String>) -> Self {
58 self.locator(Selector::by_text(text))
59 }
60
61 pub fn get_by_description(&self, text: impl Into<String>) -> Self {
62 self.locator(Selector::by_description(text))
63 }
64
65 pub fn with_name(mut self, name: impl Into<String>) -> Self {
66 self.selector = self.selector.with_name(name);
67 self
68 }
69
70 pub fn with_description(mut self, description: impl Into<String>) -> Self {
71 self.selector = self.selector.with_description(description);
72 self
73 }
74
75 pub fn expect(&self) -> Expectation {
76 Expectation::new(self.clone())
77 }
78
79 pub fn count(&self) -> Result<usize> {
80 let mut harness = self.harness.borrow_mut();
81 harness.run_until_idle()?;
82 Ok(self.resolve_all(&harness)?.len())
83 }
84
85 pub fn hover(&self) -> Result<()> {
86 let point = self.action_point("hover")?;
87 self.dispatch_event(Event::Pointer(PointerEvent::new(
88 PointerEventKind::Move,
89 point,
90 )))
91 }
92
93 pub fn click(&self) -> Result<()> {
94 let point = self.action_point("click")?;
95 self.dispatch_event(Event::Pointer(PointerEvent::new(
96 PointerEventKind::Move,
97 point,
98 )))?;
99
100 let mut down = PointerEvent::new(PointerEventKind::Down, point);
101 down.button = Some(PointerButton::Primary);
102 down.buttons = PointerButtons::new(1);
103 self.dispatch_event(Event::Pointer(down))?;
104
105 let mut up = PointerEvent::new(PointerEventKind::Up, point);
106 up.button = Some(PointerButton::Primary);
107 self.dispatch_event(Event::Pointer(up))
108 }
109
110 pub fn touch_tap(&self) -> Result<()> {
111 self.touch_tap_with_id(1)
112 }
113
114 pub fn touch_tap_with_id(&self, pointer_id: u64) -> Result<()> {
115 let point = self.action_point("touch tap")?;
116
117 let mut down = PointerEvent::new(PointerEventKind::Down, point);
118 down.pointer_id = pointer_id;
119 down.pointer_kind = PointerKind::Touch;
120 down.button = Some(PointerButton::Primary);
121 down.buttons = PointerButtons::new(1);
122 self.dispatch_event(Event::Pointer(down))?;
123
124 let mut up = PointerEvent::new(PointerEventKind::Up, point);
125 up.pointer_id = pointer_id;
126 up.pointer_kind = PointerKind::Touch;
127 up.button = Some(PointerButton::Primary);
128 self.dispatch_event(Event::Pointer(up))
129 }
130
131 pub fn scroll_pixels(&self, delta: Vector) -> Result<()> {
132 self.scroll_with_delta(ScrollDelta::Pixels(delta))
133 }
134
135 pub fn scroll_lines(&self, delta: Vector) -> Result<()> {
136 self.scroll_with_delta(ScrollDelta::Lines(delta))
137 }
138
139 pub fn focus(&self) -> Result<()> {
140 if self.is_focused()? {
141 return Ok(());
142 }
143
144 self.click()?;
145
146 let mut harness = self.harness.borrow_mut();
147 let timeout = harness.default_timeout();
148 let result = harness
149 .run_until(timeout, |harness| {
150 Ok(self
151 .resolve_unique(harness)
152 .ok()
153 .filter(|node| node.state.focused))
154 })
155 .map(|_| ());
156 drop(harness);
157 result.map_err(|_| self.failure("focus", "locator did not become focused"))
158 }
159
160 pub fn press(&self, key: impl Into<String>) -> Result<()> {
161 self.focus()?;
162 let key = key.into();
163 self.dispatch_event(Event::Keyboard(KeyboardEvent::new(
164 key.clone(),
165 KeyState::Pressed,
166 )))?;
167 self.dispatch_event(Event::Keyboard(KeyboardEvent::new(key, KeyState::Released)))
168 }
169
170 pub fn fill(&self, text: impl Into<String>) -> Result<()> {
171 self.focus()?;
172 let text = text.into();
173 self.dispatch_event(Event::Ime(ImeEvent::CompositionStart))?;
174 self.dispatch_event(Event::Ime(ImeEvent::CompositionUpdate {
175 text: text.clone(),
176 cursor_range: None,
177 }))?;
178 self.dispatch_event(Event::Ime(ImeEvent::CompositionCommit { text }))?;
179 self.dispatch_event(Event::Ime(ImeEvent::CompositionEnd))
180 }
181
182 pub fn dispatch_event(&self, event: Event) -> Result<()> {
183 self.harness
184 .borrow_mut()
185 .dispatch_event(self.window_id, event)
186 }
187
188 pub fn dispatch_event_now(&self, event: Event) -> Result<()> {
189 self.harness
190 .borrow_mut()
191 .dispatch_event_now(self.window_id, event)
192 }
193
194 pub fn capture_screenshot(&self) -> Result<Screenshot> {
195 let mut harness = self.harness.borrow_mut();
196 harness.run_until_idle()?;
197 self.capture_screenshot_from(&harness)
198 }
199
200 pub fn describe(&self) -> String {
201 if self.scopes.is_empty() {
202 return self.selector.describe();
203 }
204
205 self.scopes
206 .iter()
207 .chain(std::iter::once(&self.selector))
208 .map(Selector::describe)
209 .collect::<Vec<_>>()
210 .join(" >> ")
211 }
212
213 pub(crate) fn harness(&self) -> &Rc<RefCell<Harness>> {
214 &self.harness
215 }
216
217 pub(crate) fn selector(&self) -> &Selector {
218 &self.selector
219 }
220
221 pub(crate) fn window_id(&self) -> WindowId {
222 self.window_id
223 }
224
225 pub(crate) fn default_timeout(&self) -> f64 {
226 self.harness.borrow().default_timeout()
227 }
228
229 pub(crate) fn resolve_all(&self, harness: &Harness) -> Result<Vec<SemanticsNode>> {
230 let snapshot = harness.snapshot(self.window_id)?;
231 let scope_ids = self.resolve_scope_ids(&snapshot.accessibility);
232 Ok(snapshot
233 .accessibility
234 .nodes
235 .iter()
236 .filter(|node| {
237 self.selector.matches(&snapshot.accessibility, node)
238 && self.matches_scope(&snapshot.accessibility, node.id, &scope_ids)
239 })
240 .cloned()
241 .collect())
242 }
243
244 pub(crate) fn resolve_unique(&self, harness: &Harness) -> Result<SemanticsNode> {
245 let nodes = self.resolve_all(harness)?;
246 match nodes.as_slice() {
247 [node] => Ok(node.clone()),
248 [] => Err(Error::new("locator did not match any nodes")),
249 _ => Err(Error::new(format!(
250 "locator matched {} nodes instead of exactly one",
251 nodes.len()
252 ))),
253 }
254 }
255
256 fn action_point(&self, action: &str) -> Result<Point> {
257 let mut harness = self.harness.borrow_mut();
258 let timeout = harness.default_timeout();
259 let result = harness.run_until(timeout, |harness| {
260 let Ok(node) = self.resolve_unique(harness) else {
261 return Ok(None);
262 };
263 if !self.selector.is_visible(&node) || node.state.disabled {
264 return Ok(None);
265 }
266
267 Ok(Some(center(node.bounds)))
268 });
269 drop(harness);
270 result.map_err(|_| self.failure(action, "locator never became uniquely actionable"))
271 }
272
273 fn scroll_with_delta(&self, scroll_delta: ScrollDelta) -> Result<()> {
274 let point = self.action_point("scroll")?;
275 self.dispatch_event(Event::Pointer(PointerEvent::new(
276 PointerEventKind::Move,
277 point,
278 )))?;
279
280 let mut scroll = PointerEvent::new(PointerEventKind::Scroll, point);
281 scroll.scroll_delta = Some(scroll_delta);
282 self.dispatch_event(Event::Pointer(scroll))
283 }
284
285 fn is_focused(&self) -> Result<bool> {
286 let mut harness = self.harness.borrow_mut();
287 harness.run_until_idle()?;
288 Ok(self
289 .resolve_unique(&harness)
290 .is_ok_and(|node| node.state.focused))
291 }
292
293 fn failure(&self, action: &str, detail: &str) -> Error {
294 let harness = self.harness.borrow();
295 let snapshot = harness
296 .snapshot(self.window_id)
297 .unwrap_or_else(|_| harness.fallback_snapshot(self.window_id));
298 Error::new(format_failure(action, &self.describe(), &snapshot, detail))
299 }
300
301 pub(crate) fn capture_screenshot_from(&self, harness: &Harness) -> Result<Screenshot> {
302 let snapshot = harness.snapshot(self.window_id)?;
303 let scope_ids = self.resolve_scope_ids(&snapshot.accessibility);
304 let nodes = snapshot
305 .accessibility
306 .nodes
307 .iter()
308 .filter(|node| {
309 self.selector.matches(&snapshot.accessibility, node)
310 && self.matches_scope(&snapshot.accessibility, node.id, &scope_ids)
311 })
312 .cloned()
313 .collect::<Vec<_>>();
314 let node = match nodes.as_slice() {
315 [node] => node.clone(),
316 [] => return Err(Error::new("locator did not match any nodes")),
317 _ => {
318 return Err(Error::new(format!(
319 "locator matched {} nodes instead of exactly one",
320 nodes.len()
321 )));
322 }
323 };
324 let screenshot = harness.capture_screenshot(self.window_id)?;
325 screenshot.crop(scale_bounds_for_screenshot(
326 node.bounds,
327 &snapshot,
328 screenshot.width(),
329 screenshot.height(),
330 ))
331 }
332
333 fn resolve_scope_ids(&self, snapshot: &AccessibilitySnapshot) -> Vec<WidgetId> {
334 let mut current_scope_ids = Vec::new();
335
336 for scope in &self.scopes {
337 let parent_scope_ids = current_scope_ids.clone();
338 current_scope_ids = snapshot
339 .nodes
340 .iter()
341 .filter(|node| {
342 scope.matches(snapshot, node)
343 && (parent_scope_ids.is_empty()
344 || parent_scope_ids
345 .iter()
346 .any(|scope_id| is_descendant(snapshot, node.id, *scope_id)))
347 })
348 .map(|node| node.id)
349 .collect();
350
351 if current_scope_ids.is_empty() {
352 break;
353 }
354 }
355
356 current_scope_ids
357 }
358
359 fn matches_scope(
360 &self,
361 snapshot: &AccessibilitySnapshot,
362 node_id: WidgetId,
363 scope_ids: &[WidgetId],
364 ) -> bool {
365 self.scopes.is_empty()
366 || scope_ids
367 .iter()
368 .any(|scope_id| is_descendant(snapshot, node_id, *scope_id))
369 }
370}
371
372fn center(bounds: sui_core::Rect) -> Point {
373 Point::new(
374 bounds.x() + (bounds.width() / 2.0),
375 bounds.y() + (bounds.height() / 2.0),
376 )
377}
378
379fn scale_bounds_for_screenshot(
380 bounds: Rect,
381 snapshot: &crate::snapshot::WindowSnapshot,
382 screenshot_width: u32,
383 screenshot_height: u32,
384) -> Rect {
385 let Some(scene) = &snapshot.scene_summary else {
386 return bounds;
387 };
388
389 let viewport = scene.viewport;
390 if viewport.width <= 0.0 || viewport.height <= 0.0 {
391 return bounds;
392 }
393
394 let scale_x = screenshot_width as f32 / viewport.width;
395 let scale_y = screenshot_height as f32 / viewport.height;
396 Rect::new(
397 bounds.x() * scale_x,
398 bounds.y() * scale_y,
399 bounds.width() * scale_x,
400 bounds.height() * scale_y,
401 )
402}
403
404fn is_descendant(
405 snapshot: &AccessibilitySnapshot,
406 node_id: WidgetId,
407 ancestor_id: WidgetId,
408) -> bool {
409 let mut current = parent_id(snapshot, node_id);
410
411 while let Some(parent) = current {
412 if parent == ancestor_id {
413 return true;
414 }
415
416 current = parent_id(snapshot, parent);
417 }
418
419 false
420}
421
422fn parent_id(snapshot: &AccessibilitySnapshot, node_id: WidgetId) -> Option<WidgetId> {
423 snapshot
424 .nodes
425 .iter()
426 .find(|node| node.id == node_id)
427 .and_then(|node| node.parent)
428}