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(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}