Skip to main content

sui_testing/
locator.rs

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}