Skip to content

squape.object_tree

children 

children(object_or_name, selector)

Finds direct children of the given object.

Parameters:

Name Type Description Default
object_or_name any

symbolic name, real name, or object reference.

 required
selector dict

The selector is a dictionary of key-value pairs, The selector is a dictionary consisting of key-value pairs. In this dictionary:
- Each key represents a property of an object.
- Each value can either be an expected value for that property or a function that takes exactly one argument.

Additionally, the dictionary can have a key 'type' where the value should be the expected object type. An object will pass verification if the object's property value matches the selector value.

 required

Returns:

Type Description
tuple

Children objects that met the selector criteria.

Examples:

children(object_or_name, {'type' : QToolButton, 'height': 50})
children(object_or_name, {'type' : 'Button', 'visible' : True})
children(object_or_name, {'type' : 'QToolButton', 'height' : lambda x: x > 25})

def height_filter_function(height: int) -> bool:
    return height > 30 and height < 120
children(
    object_or_name,
    {'type' : 'QToolButton', 'height' : height_filter_function}
)
Source code in squape/object_tree.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def children(object_or_name: any, selector: dict) -> tuple:
    """
    Finds direct children of the given object.

    Args:
        object_or_name (any): symbolic name, real name, or object reference.

        selector (dict): The selector is a dictionary of key-value pairs,
            The selector is a dictionary consisting of key-value pairs.
            In this dictionary:  
            - Each key represents a property of an object.  
            - Each value can either be an expected value for that property
            or a function that takes exactly one argument.

            Additionally, the dictionary can have a key 'type'
            where the value should be the expected object type.
            An object will pass verification
            if the object's property value matches the selector value.

    Returns:
        Children objects that met the selector criteria.

    Examples:
        ```python
        children(object_or_name, {'type' : QToolButton, 'height': 50})
        children(object_or_name, {'type' : 'Button', 'visible' : True})
        children(object_or_name, {'type' : 'QToolButton', 'height' : lambda x: x > 25})

        def height_filter_function(height: int) -> bool:
            return height > 30 and height < 120
        children(
            object_or_name,
            {'type' : 'QToolButton', 'height' : height_filter_function}
        )
        ```
    """
    object_reference = _get_object_reference(object_or_name)
    children = object.children(object_reference)
    return tuple(filter(lambda x: _is_matching(x, selector), children))

find 

find(object_or_name, selector=None, max_depth=None)

Finds descendants of the given object.

Parameters:

Name Type Description Default
object_or_name any

symbolic name, real name, or object reference.

 required
selector dict

The selector is a dictionary of key-value pairs, where a key is a property of an object and value is expected value or function. The passed functions must accept exactly one argument. Accepted key is also 'type' and then value should by object type. An object will pass verification if the object's property value matches the selector value. Defaults to {}, which means all objects pass the verification.

 None
max_depth int

defines maximum depth in the object structure that should be while looking for children. Defaults to None, which mean there is no depth limit.

 None

Returns:

Type Description
tuple

Descendants of the given object that met the selector criteria.

Examples:

find(object_or_name)
find(object_or_name, {'type' : 'ToolBar'})
find(object_or_name, max_depth=5)
find(object_or_name, {'visible' : True}, max_depth=3)
find(
    object_or_name,
    {'type' : 'QToolButton', 'height' : lambda x: x > 25},
    max_depth=5
)

def height_filter_function(height: int) -> bool:
    return height > 30 and height < 120
find(
    object_or_name,
    {'type' : 'QToolButton', 'height' : height_filter_function}
)
Source code in squape/object_tree.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def find(object_or_name: any, selector: dict = None, max_depth: int = None) -> tuple:
    """
    Finds descendants of the given object.

    Args:
        object_or_name (any): symbolic name, real name, or object reference.

        selector (dict, optional): The selector is a dictionary of key-value pairs,
            where a key is a property of an object  and value is expected value
            or function. The passed functions must accept exactly one argument.
            Accepted key is also 'type' and then value should by object type.
            An object will pass verification
            if the object's property value matches the selector value.
            Defaults to {}, which means all objects pass the verification.

        max_depth (int): defines maximum depth in the object structure that should be
            while looking for children.
            Defaults to None, which mean there is no depth limit.

    Returns:
        Descendants of the given object that met the selector criteria.

    Examples:
        ```python
        find(object_or_name)
        find(object_or_name, {'type' : 'ToolBar'})
        find(object_or_name, max_depth=5)
        find(object_or_name, {'visible' : True}, max_depth=3)
        find(
            object_or_name,
            {'type' : 'QToolButton', 'height' : lambda x: x > 25},
            max_depth=5
        )

        def height_filter_function(height: int) -> bool:
            return height > 30 and height < 120
        find(
            object_or_name,
            {'type' : 'QToolButton', 'height' : height_filter_function}
        )
        ```
    """
    if max_depth is None:
        max_depth = math.inf
    if max_depth <= 0:
        return ()
    if selector is None:
        selector = {}

    object_reference = _get_object_reference(object_or_name)
    children = ()

    for child in object.children(object_reference):
        if _is_matching(child, selector):
            children += (child,)
        children += find(child, selector, max_depth - 1)

    return children

find_ancestor 

find_ancestor(object_or_name, selector)

Find the first object's ancestor that matches the selector.

Parameters:

Name Type Description Default
object_or_name any

symbolic name, real name, or object reference.

 required
selector dict

The selector is a dictionary of key-value pairs, where a key is a property of an object and value is expected value or function. The passed functions must accept exactly one argument. Accepted key is also 'type' and then value should by object type. An object will pass verification if the object's property value matches the selector value.

 required

Returns:

Type Description
Squish object / None

The ancestor object that matches the selector.

Examples:

find_ancestor(object_or_name)
find_ancestor(object_or_name, {'type' : 'MyContainerType'})
find_ancestor(
    object_or_name,
    {'type' : 'QToolButton', 'height' : lambda x: x > 25}
)

def height_filter_function(height: int) -> bool:
    return height > 30 and height < 120
find_ancestor(
    object_or_name,
    {'type' : 'QToolButton', 'height' : height_filter_function}
)
Source code in squape/object_tree.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def find_ancestor(object_or_name: any, selector: dict):
    """
    Find the first object's ancestor that matches the selector.

    Args:
        object_or_name (any): symbolic name, real name, or object reference.

        selector (dict): The selector is a dictionary of key-value pairs,
            where a key is a property of an object  and value is expected value
            or function. The passed functions must accept exactly one argument.
            Accepted key is also 'type' and then value should by object type.
            An object will pass verification
            if the object's property value matches the selector value.

    Returns:
        (Squish object / None): The ancestor object that matches the selector.

    Examples:
        ```python
        find_ancestor(object_or_name)
        find_ancestor(object_or_name, {'type' : 'MyContainerType'})
        find_ancestor(
            object_or_name,
            {'type' : 'QToolButton', 'height' : lambda x: x > 25}
        )

        def height_filter_function(height: int) -> bool:
            return height > 30 and height < 120
        find_ancestor(
            object_or_name,
            {'type' : 'QToolButton', 'height' : height_filter_function}
        )
        ```
    """
    object_reference = _get_object_reference(object_or_name)
    parent = object.parent(object_reference)

    if parent is None:
        return None

    if _is_matching(object.parent(object_reference), selector):
        return parent

    return find_ancestor(parent, selector)

siblings 

siblings(object_or_name, selector=None)

Find the object's siblings.

Parameters:

Name Type Description Default
object_or_name any

symbolic name, real name, or object reference.

 required
selector dict

The selector is a dictionary of key-value pairs, where a key is a property of an object and value is expected value or function. The passed functions must accept exactly one argument. Accepted key is also 'type' and then value should by object type. An object will pass verification if the object's property value matches the selector value. Defaults to {}, which means all objects pass the verification.

 None

Returns:

Type Description
tuple

Siblings of the given object that met the selector criteria.

Examples:

siblings(object)
siblings(object, {'enabled' : True})
siblings(object_or_name, {'type' : 'QToolButton', 'height' : lambda x: x > 25})

def height_filter_function(height: int) -> bool:
    return height > 30 and height < 120
siblings(
    object_or_name,
    {'type' : 'QToolButton', 'height' : height_filter_function}
)
Source code in squape/object_tree.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def siblings(object_or_name: any, selector: dict = None) -> tuple:
    """
    Find the object's siblings.

    Args:
        object_or_name (any): symbolic name, real name, or object reference.

        selector (dict, optional): The selector is a dictionary of key-value pairs,
            where a key is a property of an object  and value is expected value
            or function. The passed functions must accept exactly one argument.
            Accepted key is also 'type' and then value should by object type.
            An object will pass verification
            if the object's property value matches the selector value.
            Defaults to {}, which means all objects pass the verification.

    Returns:
        Siblings of the given object that met the selector criteria.

    Examples:
        ```python
        siblings(object)
        siblings(object, {'enabled' : True})
        siblings(object_or_name, {'type' : 'QToolButton', 'height' : lambda x: x > 25})

        def height_filter_function(height: int) -> bool:
            return height > 30 and height < 120
        siblings(
            object_or_name,
            {'type' : 'QToolButton', 'height' : height_filter_function}
        )
        ```
    """
    if selector is None:
        selector = {}
    object_reference = _get_object_reference(object_or_name)
    parent = object.parent(object_reference)

    if parent is None:
        return None
    else:
        siblings = list(object.children(parent))
        siblings.remove(object_reference)
        return tuple(filter(lambda x: _is_matching(x, selector), siblings))

wait_for_any_object 

wait_for_any_object(object_names, timeout=squish.testSettings.waitForObjectTimeout / 1000, retry_delay=0.5)

Wait for any accessible object from the provided object names list to become available (exists, visible, enabled) within a specified timeout.

Parameters:

Name Type Description Default
object_names list

A list of names of the objects to wait for.

 required
timeout int

The maximum time in seconds to wait for any object to become available. Defaults to squish.testSettings.waitForObjectTimeout/1000.

 waitForObjectTimeout / 1000
retry_delay float

The time in seconds to wait before

 0.5

Returns:

Name Type Description
object

The first object that becomes available within the specified timeout.

Raises:

Type Description
LookupError

If none of the objects become available within the specified timeout.
ValueError

If object_names list is empty
Source code in squape/object_tree.py 
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
def wait_for_any_object(
    object_names: list,
    timeout=squish.testSettings.waitForObjectTimeout / 1000,
    retry_delay: float = 0.5,
):
    """
    Wait for any accessible object from the provided object names list to become
    available (exists, visible, enabled) within a specified timeout.

    Args:
        object_names (list): A list of names of the objects to wait for.
        timeout (int, optional): The maximum time in seconds to wait for
            any object to become available.
            Defaults to squish.testSettings.waitForObjectTimeout/1000.
        retry_delay (float, optional): The time in seconds to wait before
        retrying the Squish lookup function. Defaults to 0.5.

    Returns:
        object: The first object that becomes available within the specified timeout.

    Raises:
        LookupError: If none of the objects become available within
            the specified timeout.
        ValueError: If object_names list is empty
    """
    return _wait_for_any_object(
        squish.waitForObject, object_names, timeout, retry_delay=retry_delay
    )

wait_for_any_object_exists 

wait_for_any_object_exists(object_names, timeout=squish.testSettings.waitForObjectTimeout / 1000, retry_delay=0.5)

Wait for object from the provided object names list to become available (exists) within a specified timeout.

Parameters:

Name Type Description Default
object_names list

A list of names of the objects to wait for.

 required
timeout int

The maximum time in seconds to wait for any object to become available. Defaults to squish.testSettings.waitForObjectTimeout/1000.

 waitForObjectTimeout / 1000
retry_delay float

The time in seconds to wait before retrying the Squish lookup function. Defaults to 0.5.

 0.5

Returns:

Name Type Description
object

The first object that becomes available within the specified timeout.

Raises:

Type Description
LookupError

If none of the objects become available within the specified timeout.
ValueError

If object_names list is empty
Source code in squape/object_tree.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
def wait_for_any_object_exists(
    object_names: list,
    timeout=squish.testSettings.waitForObjectTimeout / 1000,
    retry_delay: float = 0.5,
):
    """
    Wait for object from the provided object names list to become
    available (exists) within a specified timeout.

    Args:
        object_names (list): A list of names of the objects to wait for.
        timeout (int, optional): The maximum time in seconds to wait for
            any object to become available.
            Defaults to squish.testSettings.waitForObjectTimeout/1000.
        retry_delay (float, optional): The time in seconds to wait before
            retrying the Squish lookup function. Defaults to 0.5.

    Returns:
        object: The first object that becomes available within the specified timeout.

    Raises:
        LookupError: If none of the objects become available within
            the specified timeout.
        ValueError: If object_names list is empty
    """
    return _wait_for_any_object(
        squish.waitForObjectExists, object_names, timeout, retry_delay=retry_delay
    )