use actl_core::target::Target;
use actl_core::{CtlError, ErrorCode};
use uiautomation::{UIAutomation, UIElement, UITreeWalker};
use crate::window::{ensure_window_responsive, find_window, top_level_of_focused};
use crate::{internal, timing};
pub struct Located {
pub window_title: String,
pub role: String,
pub name: Option<String>,
pub automation_id: Option<String>,
pub resolved_by: &'static str,
pub(crate) element: UIElement,
}
pub struct ResolvedInfo {
pub window_title: String,
pub role: String,
pub name: Option<String>,
pub automation_id: Option<String>,
pub resolved_by: &'static str,
}
impl Located {
pub(crate) fn into_info(self) -> ResolvedInfo {
let Located {
window_title,
role,
name,
automation_id,
resolved_by,
element,
} = self;
drop(element);
ResolvedInfo {
window_title,
role,
name,
automation_id,
resolved_by,
}
}
}
struct CachedResolve {
key: String,
element: UIElement,
runtime_id: serde_json::Value,
}
thread_local! {
static RESOLVE_CACHE: std::cell::RefCell<Option<CachedResolve>> =
const { std::cell::RefCell::new(None) };
}
fn cache_key(app: Option<&str>, target: &Target) -> String {
format!("{}\u{1f}{}", app.unwrap_or(""), target.describe())
}
fn root_element(walker: &UITreeWalker, element: &UIElement) -> UIElement {
let mut current = element.clone();
for _ in 0..32 {
match walker.get_parent(¤t) {
Ok(parent) => current = parent,
_ => break,
}
}
current
}
fn cache_lookup(app: Option<&str>, key: &str) -> Option<Located> {
let app = app?;
let (element, cached_rid) = RESOLVE_CACHE.with(|cache| {
let guard = cache.borrow();
let cached = guard.as_ref()?;
if cached.key != key {
return None;
}
Some((cached.element.clone(), cached.runtime_id.clone()))
})?;
let rid = element.get_runtime_id().ok()?;
if rid.is_empty() || serde_json::json!(rid) != cached_rid {
return None;
}
let auto = UIAutomation::new().ok()?;
let walker = auto.create_tree_walker().ok()?;
let window = find_window(&auto, &walker, app).ok()?;
let root = root_element(&walker, &element);
let window_rid = window.get_runtime_id().ok()?;
let root_rid = root.get_runtime_id().ok()?;
if window_rid.is_empty()
|| root_rid.is_empty()
|| serde_json::json!(window_rid) != serde_json::json!(root_rid)
{
return None;
}
let title = window.get_name().ok()?;
located_from(element, title, "cache").ok()
}
fn cache_store(key: &str, located: &Located) {
let rid = match located.element.get_runtime_id() {
Ok(rid) if !rid.is_empty() => serde_json::json!(rid),
_ => return,
};
RESOLVE_CACHE.with(|cache| {
*cache.borrow_mut() = Some(CachedResolve {
key: key.to_string(),
element: located.element.clone(),
runtime_id: rid,
});
});
}
pub fn locate(app: Option<&str>, target: &Target, near: Option<&str>) -> Result<Located, CtlError> {
let cacheable = near.is_none()
&& app.is_some()
&& matches!(target, Target::Name(_) | Target::Id(_) | Target::Role(..));
if !cacheable {
return locate_full(app, target, near);
}
let key = cache_key(app, target);
if let Some(hit) = cache_lookup(app, &key) {
return Ok(hit);
}
let located = locate_full(app, target, near)?;
{
let _guard = crate::watchdog::enter();
cache_store(&key, &located);
}
Ok(located)
}
fn locate_full(
app: Option<&str>,
target: &Target,
near: Option<&str>,
) -> Result<Located, CtlError> {
let _watchdog = crate::watchdog::enter();
if matches!(target, Target::Uia(_)) && near.is_some() {
return Err(CtlError::protocol(
"uia selectors do not support --near; use within and unique conditions",
));
}
if let Target::Coord(..) = target {
return Err(CtlError::protocol(format!(
"{} cannot be resolved to an element; coordinate targets are physical-only (click xy:x,y --app <win> --physical)",
target.describe()
)));
}
let auto = {
let _t = actl_core::trace::scope("locate.initialize");
UIAutomation::new().map_err(internal)?
};
if let Target::Uia(selector) = target {
let root = {
let _t = actl_core::trace::scope("locate.uia.window");
crate::scoped_locate::window(&auto, app)?
};
let _t = actl_core::trace::scope("locate.uia.selector");
return crate::scoped_locate::locate(&auto, &root, selector);
}
let walker = auto.create_tree_walker().map_err(internal)?;
let root = {
let _t = actl_core::trace::scope("locate.window");
match app {
Some(pattern) => find_window(&auto, &walker, pattern)?,
None => {
if matches!(target, Target::Ref(_)) {
return Err(CtlError::protocol(format!(
"{} requires --app: refs are scoped to the window the snapshot came from; \
pass --app <title-substr> or re-snapshot",
target.describe()
)));
}
top_level_of_focused(&auto, &walker)?
}
}
};
let window_title = root
.get_name()
.map_err(|e| crate::read_channel::failure("window.name", e))?;
let _wake_ms = {
let _t = actl_core::trace::scope("locate.wake");
ensure_window_responsive(&root)
};
if let Target::Ref(n) = target {
if let Some(hit) = crate::identity::scoped_ref(&auto, &root, *n)? {
crate::identity::check_ref(&root, &hit, *n)?;
return located_from(hit, window_title, "scoped-ref-replay");
}
let mut counter = 0u32;
let _t = actl_core::trace::scope("locate.ref-replay");
return match collect_until_ref(&walker, &root, 0, *n, &mut counter)? {
Some(hit) => {
crate::identity::check_ref(&root, &hit, *n)?;
located_from(hit, window_title, "ref-replay")
}
None => Err(CtlError::new(
ErrorCode::StaleRef,
format!(
"{} does not resolve — the tree changed since the snapshot",
target.describe()
),
)),
};
}
if let Target::Focused(role) = target {
let _t = actl_core::trace::scope("locate.focused");
let (focused_hwnd, focused_title) = crate::kbd::focused_root_window().ok_or_else(|| {
CtlError::new(
ErrorCode::NotFound,
"focused: no keyboard focus or focus root resolvable",
)
})?;
if app.is_some() {
let root_hwnd = crate::window::native_hwnd(&root)
.ok_or_else(|| internal("app window has no native hwnd"))?;
if root_hwnd.0 as isize != focused_hwnd {
return Err(CtlError::with_evidence(
ErrorCode::NotFound,
"focused: keyboard focus belongs to another window",
serde_json::json!({
"focused_window": focused_title,
"app_window": window_title,
}),
));
}
}
let focused = auto
.get_focused_element()
.map_err(|e| crate::read_channel::failure("focused_element", e))?;
if let Some(expected) = role {
let actual = strict_role(&focused)?;
if !actual.eq_ignore_ascii_case(expected) {
return Err(CtlError::with_evidence(
ErrorCode::NotFound,
"focused: focused element role does not match",
serde_json::json!({
"expected": expected,
"actual": actual,
}),
));
}
}
return located_from(focused, focused_title, "focused");
}
let mut counter = 0u32;
let mut matches = Vec::new();
if let Target::Id(_) = target {
let hits = {
let _t = actl_core::trace::scope("locate.fastpath");
fast_exact_ids(&auto, &root, target)?
};
match hits {
Some(hits) if hits.len() == 1 => {
return located_from(hits[0].clone(), window_title, "primary");
}
Some(hits) if hits.is_empty() => {
let _t = actl_core::trace::scope("locate.l4");
if let Some(hit) = locate_virtualized(&walker, &root, target)? {
return located_from(hit, window_title, "item-container");
}
return Err(CtlError::new(
ErrorCode::NotFound,
format!(
"no element matches {} (exact and virtualized-container levels)",
target.describe()
),
));
}
_ => {} }
}
{
let _t = actl_core::trace::scope("locate.dfs");
collect_matches(&walker, &root, 0, target, false, &mut counter, &mut matches)?;
}
if matches.is_empty() {
if let Target::Name(_) = target {
let mut fuzzy = Vec::new();
collect_matches(&walker, &root, 0, target, true, &mut counter, &mut fuzzy)?;
if !fuzzy.is_empty() {
fuzzy.sort_by_key(|c: &Candidate| c.ref_no);
return select(
fuzzy,
target,
near,
&walker,
&root,
window_title,
"fuzzy-name",
);
}
}
let l4 = {
let _t = actl_core::trace::scope("locate.l4");
locate_virtualized(&walker, &root, target)?
};
if let Some(hit) = l4 {
return located_from(hit, window_title, "item-container");
}
return Err(CtlError::new(
ErrorCode::NotFound,
format!(
"no element matches {} (exact, fuzzy and virtualized-container levels)",
target.describe()
),
));
}
matches.sort_by_key(|c: &Candidate| c.ref_no);
select(
matches,
target,
near,
&walker,
&root,
window_title,
"primary",
)
}
fn select(
matches: Vec<Candidate>,
target: &Target,
near: Option<&str>,
walker: &UITreeWalker,
root: &UIElement,
window_title: String,
level: &'static str,
) -> Result<Located, CtlError> {
if let Target::RoleAt(_, n) | Target::IdAt(_, n) = target {
return match matches.get((*n as usize).saturating_sub(1)) {
Some(c) => located_from(
c.element.clone(),
window_title,
if matches!(target, Target::IdAt(..)) {
"id-ordinal"
} else {
"role-ordinal"
},
),
None => Err(CtlError::new(
ErrorCode::NotFound,
format!(
"{}: only {} match(es) in the window",
target.describe(),
matches.len()
),
)),
};
}
if matches.len() == 1 {
return located_from(matches[0].element.clone(), window_title, level);
}
if let Some(anchor_pat) = near {
let mut counter = 0u32;
let mut anchors = Vec::new();
let anchor_target =
actl_core::parse_target(anchor_pat).unwrap_or(Target::Name(anchor_pat.to_string()));
collect_matches(
walker,
root,
0,
&anchor_target,
false,
&mut counter,
&mut anchors,
)?;
if anchors.len() != 1 {
return Err(CtlError::new(
ErrorCode::NotFound,
format!(
"--near anchor {anchor_pat:?} must match exactly one element, got {}",
anchors.len()
),
));
}
{
let ar = anchors[0]
.element
.get_bounding_rectangle()
.map_err(|e| crate::read_channel::failure("anchor.bounds", e))?;
let (ax, ay) = center(&ar);
let mut best: Option<(f64, usize)> = None;
for (i, c) in matches.iter().enumerate() {
{
let r = c
.element
.get_bounding_rectangle()
.map_err(|e| crate::read_channel::failure("candidate.bounds", e))?;
let (cx, cy) = center(&r);
let dx = (cx - ax) as f64;
let dy = (cy - ay) as f64;
let d = dx * dx + dy * dy;
if best.map(|(bd, _)| d < bd).unwrap_or(true) {
best = Some((d, i));
}
}
}
if let Some((_, i)) = best {
return located_from(matches[i].element.clone(), window_title, "anchor");
}
}
}
let shown: Vec<CandidateMeta> = matches.iter().take(8).map(Candidate::meta).collect();
Err(ambiguous_error(&target.describe(), matches.len(), &shown))
}
fn center(r: &uiautomation::types::Rect) -> (i32, i32) {
(
(r.get_left() + r.get_right()) / 2,
(r.get_top() + r.get_bottom()) / 2,
)
}
fn located_from(
elem: UIElement,
window_title: String,
resolved_by: &'static str,
) -> Result<Located, CtlError> {
Ok(Located {
window_title,
role: strict_role(&elem)?,
name: Some(
elem.get_name()
.map_err(|e| crate::read_channel::failure("name", e))?,
),
automation_id: Some(
elem.get_automation_id()
.map_err(|e| crate::read_channel::failure("automation_id", e))?,
),
resolved_by,
element: elem,
})
}
struct Candidate {
element: UIElement,
ref_no: u32,
role: String,
name: Option<String>,
automation_id: Option<String>,
context: Option<String>,
}
#[derive(Debug, Clone)]
struct CandidateMeta {
ref_no: u32,
role: String,
name: Option<String>,
automation_id: Option<String>,
context: Option<String>,
}
impl Candidate {
fn meta(&self) -> CandidateMeta {
CandidateMeta {
ref_no: self.ref_no,
role: self.role.clone(),
name: self.name.clone(),
automation_id: self.automation_id.clone(),
context: self.context.clone(),
}
}
}
fn ambiguous_error(target: &str, total: usize, cands: &[CandidateMeta]) -> CtlError {
let duplicated: std::collections::HashSet<String> = {
let mut seen = std::collections::HashSet::new();
let mut dups = std::collections::HashSet::new();
for c in cands {
let key = c.name.as_deref().unwrap_or("").trim().to_string();
if !seen.insert(key.clone()) {
dups.insert(key);
}
}
dups
};
let evidence: Vec<serde_json::Value> = cands
.iter()
.map(|c| {
let mut obj = serde_json::json!({
"ref": format!("@e{}", c.ref_no),
"role": c.role,
"name": c.name,
"automation_id": c.automation_id,
});
if duplicated.contains(c.name.as_deref().unwrap_or("").trim()) {
obj["context"] = serde_json::json!(c.context);
}
obj
})
.collect();
CtlError::with_evidence(
ErrorCode::Ambiguous,
format!(
"{} matches {} elements in the window; pick one by @eN or role ordinal (--near anchor also applies)",
target, total
),
serde_json::json!({ "candidates": evidence }),
)
}
fn collect_until_ref(
_walker: &UITreeWalker,
elem: &UIElement,
_depth: u32,
want: u32,
counter: &mut u32,
) -> Result<Option<UIElement>, CtlError> {
for entry in crate::observation::tree_live(elem)?.require_complete()? {
let role = strict_role(&entry.element)?;
if actl_core::is_interactive_role(&role) {
*counter += 1;
if *counter == want {
return Ok(Some(entry.element));
}
}
}
Ok(None)
}
fn strict_role(elem: &UIElement) -> Result<String, CtlError> {
crate::observation::role_of(elem).map(|v| format!("{v:?}"))
}
fn collect_matches(
_walker: &UITreeWalker,
elem: &UIElement,
_depth: u32,
target: &Target,
fuzzy: bool,
counter: &mut u32,
out: &mut Vec<Candidate>,
) -> Result<(), CtlError> {
*counter = 0;
let entries = crate::observation::tree_live(elem)?.require_complete()?;
for (index, entry) in entries.iter().enumerate() {
let element = &entry.element;
let role = strict_role(element)?;
let ref_no = if actl_core::is_interactive_role(&role) {
*counter += 1;
*counter
} else {
0
};
let name = crate::observation::name_of(element)?;
let id = crate::observation::automation_id_of(element)?;
let hit = match target {
Target::Name(s) if fuzzy => actl_core::target::fuzzy_contains(&name, s),
Target::Name(s) => name.contains(s.as_str()),
Target::Id(s) | Target::IdAt(s, _) => id == *s,
Target::Role(s) | Target::RoleAt(s, _) => role == *s,
_ => false,
};
if hit {
let context = crate::observation::nearest_named_ancestor(&entries, index, |e| {
crate::observation::name_of(e)
})?;
out.push(Candidate {
element: element.clone(),
ref_no,
role,
name: Some(name),
automation_id: Some(id),
context,
});
}
}
Ok(())
}
fn fast_exact_ids(
auto: &UIAutomation,
root: &UIElement,
target: &Target,
) -> Result<Option<Vec<UIElement>>, CtlError> {
use uiautomation::types::{TreeScope, UIProperty};
use uiautomation::variants::Variant;
let Target::Id(s) = target else {
return Ok(None);
};
let cond = auto
.create_property_condition(UIProperty::AutomationId, Variant::from(s.clone()), None)
.map_err(|e| crate::read_channel::failure("id.condition", e))?;
let cache = auto.create_cache_request().map_err(internal)?;
cache
.set_tree_filter(auto.create_true_condition().map_err(internal)?)
.map_err(internal)?;
cache.set_tree_scope(TreeScope::Element).map_err(internal)?;
root.find_all_build_cache(TreeScope::Subtree, &cond, &cache)
.map(Some)
.map_err(|e| crate::read_channel::failure("id.query", e))
}
pub fn find_by_id_provider(app: Option<&str>, id: &str) -> Result<Vec<ResolvedInfo>, CtlError> {
let auto = UIAutomation::new().map_err(crate::internal)?;
let walker = auto.create_tree_walker().map_err(crate::internal)?;
let root = match app {
Some(pattern) => crate::window::find_window(&auto, &walker, pattern)?,
None => crate::window::top_level_of_focused(&auto, &walker)?,
};
let window_title = root.get_name().unwrap_or_default();
let hits = fast_exact_ids(&auto, &root, &Target::Id(id.to_string()))?.unwrap_or_default();
let _watchdog = crate::watchdog::enter();
let mut out = Vec::with_capacity(hits.len());
for element in hits {
let role = format!(
"{:?}",
element
.get_control_type()
.map_err(|e| crate::read_channel::failure("role", e))?
);
let name = element
.get_name()
.map_err(|e| crate::read_channel::failure("name", e))?;
let automation_id = element
.get_automation_id()
.map_err(|e| crate::read_channel::failure("automation_id", e))?;
out.push(ResolvedInfo {
window_title: window_title.clone(),
role,
name: Some(name),
automation_id: Some(automation_id),
resolved_by: "provider-exact",
});
}
Ok(out)
}
fn container_query_for(
target: &Target,
) -> Option<(windows::Win32::UI::Accessibility::UIA_PROPERTY_ID, String)> {
use windows::Win32::UI::Accessibility::{UIA_AutomationIdPropertyId, UIA_NamePropertyId};
match target {
Target::Name(s) => Some((UIA_NamePropertyId, s.clone())),
Target::Id(s) => Some((UIA_AutomationIdPropertyId, s.clone())),
_ => None,
}
}
fn locate_virtualized(
_walker: &UITreeWalker,
root: &UIElement,
target: &Target,
) -> Result<Option<UIElement>, CtlError> {
use uiautomation::{types::UIProperty, variants::Variant};
use windows::{
Win32::UI::Accessibility::{
IUIAutomationElement, IUIAutomationItemContainerPattern, UIA_ItemContainerPatternId,
},
core::Interface,
};
let Some((prop, value)) = container_query_for(target) else {
return Ok(None);
};
let value = Variant::from(value);
let entries = crate::observation::tree_live(root)?.require_complete()?;
let mut hit = None;
for entry in entries {
let c = entry.element;
if !crate::read_channel::available(
&c,
UIProperty::IsItemContainerPatternAvailable,
"item-container",
)? {
continue;
}
unsafe {
let pattern: IUIAutomationItemContainerPattern = c
.as_ref()
.GetCurrentPattern(UIA_ItemContainerPatternId)
.and_then(|p| p.cast())
.map_err(|e| crate::read_channel::failure("item-container.pattern", e.into()))?;
let mut raw = std::ptr::null_mut();
(pattern.vtable().FindItemByProperty)(
pattern.as_raw(),
std::ptr::null_mut(),
prop,
std::mem::transmute_copy(value.as_ref()),
&mut raw,
)
.ok()
.map_err(|e| crate::read_channel::failure("item-container.query", e.into()))?;
if !raw.is_null() {
let element = UIElement::from(IUIAutomationElement::from_raw(raw));
let mut second = std::ptr::null_mut();
(pattern.vtable().FindItemByProperty)(
pattern.as_raw(),
element.as_ref().as_raw(),
prop,
std::mem::transmute_copy(value.as_ref()),
&mut second,
)
.ok()
.map_err(|e| crate::read_channel::failure("item-container.next", e.into()))?;
if !second.is_null() {
let _second = IUIAutomationElement::from_raw(second);
return Err(CtlError::new(
ErrorCode::Ambiguous,
"multiple virtualized items matched",
));
}
if hit.is_some() {
return Err(CtlError::new(
ErrorCode::Ambiguous,
"multiple virtualized containers matched",
));
}
hit = Some(element);
}
}
}
Ok(hit)
}
fn poll(app: Option<&str>, target: &Target) -> Result<Option<Located>, CtlError> {
actl_core::wait_control::check()?;
crate::scoped_locate::observed(locate(app, target, None))
}
pub fn wait_element(app: Option<&str>, target: &Target, timeout_ms: u64) -> Result<(), CtlError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
let mut last_transient: Option<CtlError> = None;
loop {
actl_core::watchdog::reset();
match poll(app, target) {
Ok(Some(_)) => return Ok(()),
Ok(None) => {}
Err(error)
if matches!(error.code, ErrorCode::StaleRef | ErrorCode::Internal)
&& std::time::Instant::now() < deadline =>
{
last_transient = Some(error);
}
Err(error) => return Err(error),
}
if std::time::Instant::now() >= deadline {
if let Some(transient) = last_transient {
return Err(transient);
}
return Err(CtlError::new(
ErrorCode::Timeout,
format!(
"element {} did not resolve within {timeout_ms}ms",
target.describe()
),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().poll_ms));
}
}
pub fn wait_gone(app: Option<&str>, target: &Target, timeout_ms: u64) -> Result<(), CtlError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
loop {
actl_core::watchdog::reset();
match poll(app, target) {
Ok(None) => return Ok(()),
Ok(Some(_)) => {}
Err(_) if std::time::Instant::now() < deadline => {}
Err(error) => return Err(error),
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::new(
ErrorCode::Timeout,
format!(
"{} still resolves after {timeout_ms}ms (expected it to disappear)",
target.describe()
),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().poll_ms));
}
}
#[cfg(test)]
mod tests {
use super::{CandidateMeta, ambiguous_error, container_query_for};
use actl_core::target::Target;
use windows::Win32::UI::Accessibility::{UIA_AutomationIdPropertyId, UIA_NamePropertyId};
fn meta(
ref_no: u32,
role: &str,
name: Option<&str>,
automation_id: &str,
context: Option<&str>,
) -> CandidateMeta {
CandidateMeta {
ref_no,
role: role.to_string(),
name: name.map(str::to_string),
automation_id: Some(automation_id.to_string()),
context: context.map(str::to_string),
}
}
#[test]
fn ambiguous_evidence_attaches_context_only_for_duplicate_labels() {
let cands = vec![
meta(1, "Button", Some("Play"), "b1", Some("Hello · Adele")),
meta(2, "Button", Some("Play"), "b2", Some("Skyfall · Adele")),
meta(5, "Button", Some("Stop"), "b3", Some("irrelevant")),
];
let error = ambiguous_error("name:Play", 3, &cands);
assert_eq!(error.code, actl_core::ErrorCode::Ambiguous);
let evidence = error.evidence.unwrap();
let cands = evidence["candidates"].as_array().unwrap();
assert_eq!(cands[0]["context"], "Hello · Adele");
assert_eq!(cands[1]["context"], "Skyfall · Adele");
assert!(
cands[2].get("context").is_none(),
"unique label carries no context (volume control)"
);
assert_eq!(cands[0]["ref"], "@e1");
}
#[test]
fn ambiguous_evidence_empty_name_duplicates_carry_null_when_no_ancestor() {
let cands = vec![
meta(3, "Edit", Some(""), "e1", None),
meta(4, "Edit", Some(""), "e2", None),
];
let error = ambiguous_error("role:Edit", 2, &cands);
let evidence = error.evidence.unwrap();
let cands = evidence["candidates"].as_array().unwrap();
assert_eq!(cands[0]["context"], serde_json::Value::Null);
assert_eq!(cands[1]["context"], serde_json::Value::Null);
}
#[test]
fn ambiguous_envelope_matches_golden() {
let cands = vec![
meta(1, "Button", Some("Play"), "b1", Some("Hello · Adele")),
meta(2, "Button", Some("Play"), "b2", Some("Skyfall · Adele")),
meta(5, "Button", Some("Stop"), "b3", None),
];
let error = ambiguous_error("name:Play", 3, &cands);
let envelope = actl_core::ErrorEnvelope::new("find", &error, 0);
let expected: serde_json::Value =
serde_json::from_str(include_str!("../tests/golden/ambiguous_candidates.json"))
.unwrap();
assert_eq!(serde_json::to_value(envelope).unwrap(), expected);
}
#[test]
fn l4_maps_name_and_id_to_exact_property_queries() {
let (prop, v) = container_query_for(&Target::Name("report.xlsx".into())).expect("name");
assert_eq!(prop, UIA_NamePropertyId);
assert_eq!(v, "report.xlsx");
let (prop, v) = container_query_for(&Target::Id("SystemListItem".into())).expect("id");
assert_eq!(prop, UIA_AutomationIdPropertyId);
assert_eq!(v, "SystemListItem");
}
#[test]
fn l4_excludes_role_and_ref_targets() {
assert!(container_query_for(&Target::Role("ListItem".into())).is_none());
assert!(container_query_for(&Target::RoleAt("ListItem".into(), 2)).is_none());
assert!(container_query_for(&Target::Ref(7)).is_none());
}
}
pub fn wait_property(
app: Option<&str>,
target: &Target,
predicate: &WaitPredicate,
timeout_ms: u64,
) -> Result<String, CtlError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
let mut last: Option<String> = None;
loop {
actl_core::watchdog::reset();
if let Some(loc) = poll(app, target)? {
let actual = predicate.read(&loc.element)?;
if predicate.satisfied(actual.as_deref()) {
return Ok(actual.unwrap_or_default());
}
last = actual;
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::with_evidence(
ErrorCode::Timeout,
format!(
"{} did not satisfy {} within {timeout_ms}ms",
target.describe(),
predicate.describe()
),
serde_json::json!({ "last_actual": last, "actual":last, "target":target.describe(), "expected":predicate.expected, "property":predicate.describe().split('=').next(), "channel":match predicate.prop { WaitProp::Value => "value-or-text-pattern", WaitProp::Name => "name", WaitProp::Text => "text-pattern", WaitProp::Checked => "toggle-pattern" }, "comparison":if predicate.contains {"contains"} else {"exact"} }),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().poll_ms));
}
}
pub struct StableOutcome {
pub samples: usize,
pub changes: usize,
pub last_len: usize,
}
pub fn wait_stable(
app: Option<&str>,
target: &Target,
timeout_ms: u64,
) -> Result<StableOutcome, CtlError> {
const STABLE_SAMPLES: usize = 2;
let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
let mut last: Option<String> = None;
let mut stable = 0usize;
let mut samples = 0usize;
let mut changes = 0usize;
loop {
actl_core::watchdog::reset();
if let Some(loc) = poll(app, target)? {
let sample = stability_sample(&loc.element)?;
samples += 1;
stable = match &last {
Some(prev) if prev == &sample => stable + 1,
Some(_) => {
changes += 1;
1
}
None => 1,
};
last = Some(sample);
if stable >= STABLE_SAMPLES {
return Ok(StableOutcome {
samples,
changes,
last_len: last.as_deref().map(str::len).unwrap_or(0),
});
}
} else {
stable = 0;
}
if std::time::Instant::now() >= deadline {
return Err(CtlError::with_evidence(
ErrorCode::Timeout,
format!(
"{} did not settle within {timeout_ms}ms (content still changing or element absent)",
target.describe()
),
serde_json::json!({
"samples": samples,
"changes": changes,
"last_len": last.as_deref().map(str::len),
}),
));
}
std::thread::sleep(std::time::Duration::from_millis(timing().settle_ms));
}
}
fn stability_sample(elem: &UIElement) -> Result<String, CtlError> {
if let Some(text) = crate::read::read_text(elem)? {
return Ok(text);
}
if let Some(value) = crate::read::read_value(elem)? {
return Ok(value);
}
elem.get_name()
.map_err(|e| crate::read_channel::failure("name", e))
}
pub struct WaitPredicate {
pub prop: WaitProp,
pub expected: String,
pub contains: bool,
}
pub enum WaitProp {
Text,
Value,
Name,
Checked,
}
impl WaitPredicate {
pub fn parse(raw: &str) -> Result<Self, CtlError> {
let Some((prop, expected)) = raw.split_once('=') else {
return Err(CtlError::protocol(format!(
"invalid predicate {raw:?}: expected <prop>=<expected> with prop in value|name|text|checked"
)));
};
let prop = match prop.trim() {
"value" => WaitProp::Value,
"name" => WaitProp::Name,
"text" => WaitProp::Text,
"checked" => WaitProp::Checked,
other => {
return Err(CtlError::protocol(format!(
"unknown predicate property {other:?}: expected value|name|text|checked"
)));
}
};
let expected = expected.trim().to_string();
if expected.is_empty() {
return Err(CtlError::protocol(format!(
"predicate {raw:?} has an empty expectation"
)));
}
if matches!(prop, WaitProp::Checked) && !matches!(expected.as_str(), "on" | "off") {
return Err(CtlError::protocol(
"checked predicate expects on|off (e.g. checked=on)",
));
}
Ok(Self {
prop,
expected,
contains: false,
})
}
pub fn describe(&self) -> String {
let p = match self.prop {
WaitProp::Value => "value",
WaitProp::Name => "name",
WaitProp::Text => "text",
WaitProp::Checked => "checked",
};
format!("{p}={}", self.expected)
}
pub fn read(&self, elem: &uiautomation::UIElement) -> Result<Option<String>, CtlError> {
let (value, channel) = match self.prop {
WaitProp::Value => (crate::read::read_value(elem)?, "value-or-text-pattern"),
WaitProp::Text => (crate::read::read_text(elem)?, "text-pattern"),
WaitProp::Name => (
Some(
elem.get_name()
.map_err(|e| crate::read_channel::failure("name", e))?,
),
"name",
),
WaitProp::Checked => (
crate::read_channel::toggle(elem)?.map(|v| v.to_lowercase()),
"toggle-pattern",
),
};
Ok(Some(crate::read_channel::require(value, channel)?))
}
pub fn satisfied(&self, actual: Option<&str>) -> bool {
let Some(a) = actual else { return false };
match (&self.prop, self.contains) {
(WaitProp::Checked, _)
| (WaitProp::Value, false)
| (WaitProp::Name | WaitProp::Text, false) => a == self.expected,
(WaitProp::Value, true) | (WaitProp::Name | WaitProp::Text, true) => {
a.contains(&self.expected)
}
}
}
}
#[cfg(test)]
mod wait_tests {
use super::*;
use actl_core::CtlError;
#[test]
fn predicate_parses_and_rejects() {
let p = WaitPredicate::parse("value=OK").unwrap();
assert!(p.satisfied(Some("OK")));
assert!(!p.satisfied(Some("ok"))); let p = WaitPredicate::parse("checked=on").unwrap();
assert!(p.satisfied(Some("on")));
assert!(WaitPredicate::parse("checked=maybe").is_err());
assert!(WaitPredicate::parse("bogus=1").is_err());
assert!(WaitPredicate::parse("noequalsign").is_err());
assert!(WaitPredicate::parse("value=").is_err());
}
#[test]
fn contains_semantics_apply_to_value_and_name_only() {
let mut p = WaitPredicate::parse("value=56,877").unwrap();
p.contains = true;
assert!(p.satisfied(Some("显示为 56,877")));
let mut p = WaitPredicate::parse("name=保存").unwrap();
p.contains = true;
assert!(p.satisfied(Some("另存为 - 保存")));
}
#[test]
fn missing_actual_is_unsatisfied() {
let p = WaitPredicate::parse("name=x").unwrap();
assert!(!p.satisfied(None));
let _ = CtlError::protocol(""); }
}