ElementQuery

Use ElementQuery to form a query into the tree of UI elements and then locate one or multiple matching elements.

ElementQuery uses the builder pattern to concatenate criteria, such as searching for descendants, or matching elements only with a certain id.

Construct an instance of this by calling query_descendants or query_descendants. Apply additional criterial on the returned ElementQuery and fetch results by calling find_first to collect just the first match, find_one to collect the only match, or find_all to collect all matches for the query.

The elements returned by these functions refer to the element instances that matched when the query ran. If the UI replaces such an instance, for example when an if condition toggles or a live preview reloads, the returned element is no longer valid. Call tracking before running the query to obtain an element that runs the query again each time it is used, and therefore follows these replacements:

ok_button = (
    window.query_descendants()
    .match_accessible_role(slint_testing.AccessibleRole.Button)
    .match_accessible_label("OK")
    .tracking()
    .find_one()
)
ok_button.invoke_accessible_default_action()  # acts on the OK button that exists right now

Methods

match_descendants

match_descendants() -> ElementQuery

Applies any subsequent matches to all descendants of the results of the query up to this point.

match_id

match_id(id: str) -> ElementQuery

Include only elements in the results where id is equal to the provided id.

match_type_name

match_type_name(type_name: str) -> ElementQuery

Include only elements in the results where type_name is equal to the provided type_name.

match_inherits

match_inherits(type_name: str) -> ElementQuery

Include only elements in the results where type_name or bases is contains to the provided type_name.

match_accessible_role

match_accessible_role(role: AccessibleRole) -> ElementQuery

Include only elements in the results where accessible_role is equal to the provided role.

match_accessible_label

match_accessible_label(label: str) -> ElementQuery Slint ≥ 1.19

Include only elements in the results where accessible_label is equal to the provided label.

Requires Slint 1.19 or newer. With older versions, running the query raises RequestError.

tracking

tracking(timeout: float = 5.0) -> ElementQuery

Makes find_first and find_one return an element that runs this query again every time a property is read or a function is called on it. Use this when the UI may replace the element’s instance while the test holds on to it, for example when an if condition toggles, a popup is shown again, or a live preview reloads.

For example, in the following UI, unchecking and checking the checkbox replaces the Text element with a new instance:

export component App inherits Window {
    VerticalLayout {
        show-details := CheckBox { text: "Show details"; checked: true; }
        if show-details.checked: details := Text { text: "Some details"; }
    }
}

An element from a tracking query keeps working with the new instance:

query = window.query_descendants()
checkbox = query.match_id("App::show-details").find_one()
details = query.match_id("App::details").tracking().find_one()

checkbox.invoke_accessible_default_action()  # hides the details
assert not details.is_valid
checkbox.invoke_accessible_default_action()  # shows new details
assert details.accessible_label == "Some details"

Without tracking(), details would refer to the first instance, and reading details.accessible_label would raise RequestError.

When the query doesn’t match at the time the element is used, the element waits up to timeout seconds for a match to appear and then raises ElementLookupError. is_valid doesn’t wait and tells whether the query matches right now.

find_all can’t be combined with tracking and raises ValueError.

find_first

find_first() -> Element | None

Runs the query and returns the first result; returns None if no element matches the selected criteria.

On a tracking query, the query runs once right away to decide whether to return None, without waiting. The returned element runs the query again on every use and refers to its first match.

find_one

find_one() -> Element

Runs the query and returns the only result. Raises ElementLookupError if no element or more than one element matches the selected criteria.

On a tracking query, this waits up to the tracking timeout for exactly one element to match. The returned element runs the query again on every use, and requires exactly one match each time.

find_all

find_all() -> list[Element]

Runs the query and returns a list of all matching elements.