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