autopilot.introspection.ProxyBase

class autopilot.introspection.ProxyBase(state_dict, path, backend)

A class that supports transparent data retrieval from the application under test.

This class is the base class for all objects retrieved from the application under test. It handles transparently refreshing attribute values when needed, and contains many methods to select child objects in the introspection tree.

This class must be used as a base class for any custom proxy classes.

See also

Tutorial Section Writing Custom Proxy Classes

Information on how to write custom proxy classes.

get_all_instances()

Get all instances of this class that exist within the Application state tree.

For example, to get all the LauncherIcon instances:

icons = LauncherIcon.get_all_instances()

Warning

Using this method is slow - it requires a complete scan of the introspection tree. You should only use this when you’re not sure where the objects you are looking for are located. Depending on the application you are testing, you may get duplicate results using this method.

Returns:	List (possibly empty) of class instances.

get_children()

Returns a list of all child objects.

This returns a list of all children. To return only children of a specific type, use get_children_by_type. To get objects further down the introspection tree (i.e.- nodes that may not necessarily be immeadiate children), use select_single and select_many.

get_children_by_type(desired_type, **kwargs)

Get a list of children of the specified type.

Keyword arguments can be used to restrict returned instances. For example:

get_children_by_type('Launcher', monitor=1)

will return only Launcher instances that have an attribute ‘monitor’ that is equal to 1. The type can also be specified as a string, which is useful if there is no emulator class specified:

get_children_by_type('Launcher', monitor=1)

Note however that if you pass a string, and there is an emulator class defined, autopilot will not use it.

Parameters:	desired_type – Either a string naming the type you want, or a class of the type you want (the latter is used when defining custom emulators)

See also

Tutorial Section Writing Custom Proxy Classes

get_parent(type_name='', **kwargs)

Returns the parent of this object.

One may also use this method to get a specific parent node from the introspection tree, with type equal to type_name or matching the keyword filters present in kwargs. Note: The priority order is closest parent.

If no filters are provided and this object has no parent (i.e.- it is the root of the introspection tree). Then it returns itself.

Parameters:	type_name – Either a string naming the type you want, or a class of the appropriate type (the latter case is for overridden emulator classes).
Raises StateNotFoundError:
	if the requested object was not found.

get_path()

Return the absolute path of the dbus node

get_properties()

Returns a dictionary of all the properties on this class.

This can be useful when you want to log all the properties exported from your application for a particular object. Every property in the returned dictionary can be accessed as attributes of the object as well.

get_root_instance()

Get the object at the root of this tree.

This will return an object that represents the root of the introspection tree.

classmethod get_type_query_name()

Return the Type node name to use within the search query.

This allows for a Custom Proxy Object to be named differently to the underlying node type name.

For instance if you have a QML type defined in the file RedRect.qml:

import QtQuick 2.0
Rectangle {
color: red;
}

You can then define a Custom Proxy Object for this type like so:

class RedRect(DBusIntrospectionObject):

@classmethod def get_type_query_name(cls):

This is due to the qml engine storing ‘RedRect’ as a QQuickRectangle in the UI tree and the xpathquery query needs a node type to query for. By default the query will use the class name (in this case RedRect) but this will not match any node type in the tree.

is_moving(gap_interval=0.1)

Check if the element is moving.

Parameters:	gap_interval – Time in seconds to wait before re-inquiring the object co-ordinates to be able to evaluate if, the element is moving.
Returns:	True, if the element is moving, otherwise False.

no_automatic_refreshing()

Context manager function to disable automatic DBus refreshing when retrieving attributes.

Example usage:

with instance.no_automatic_refreshing():

# access lots of attributes.

This can be useful if you need to check lots of attributes in a tight loop, or if you want to atomicaly check several attributes at once.

print_tree(output=None, maxdepth=None, _curdepth=0)

Print properties of the object and its children to a stream.

When writing new tests, this can be called when it is too difficult to find the widget or property that you are interested in in “vis”.

Warning

Do not use this in production tests, this is expensive and not at all appropriate for actual testing. Only call this temporarily and replace with proper select_single/select_many calls.

Parameters:	output – A file object or path name where the output will be written to. If not given, write to stdout. maxdepth – If given, limit the maximum recursion level to that number, i. e. only print children which have at most maxdepth-1 intermediate parents.

refresh_state()

Refreshes the object’s state.

You should probably never have to call this directly. Autopilot automatically retrieves new state every time this object’s attributes are read.

Raises StateNotFound:
	if the object in the application under test has been destroyed.

select_many(type_name='*', ap_result_sort_keys=None, **kwargs)

Get a list of nodes from the introspection tree, with type equal to type_name and (optionally) matching the keyword filters present in kwargs.

You must specify either type_name, keyword filters or both.

This method searches recursively from the instance this method is called on. Calling select_many on the application (root) proxy object will search the entire tree. Calling select_many on an object in the tree will only search it’s descendants.

Example Usage:

app.select_many('QPushButton', enabled=True)
# returns a list of QPushButtons that are enabled.

As mentioned above, this method searches the object tree recursively:

file_menu = app.select_one('QMenu', title='File')
file_menu.select_many('QAction')
# returns a list of QAction objects who appear below file_menu in
# the object tree.

Warning

The order in which objects are returned is not guaranteed. It is bad practise to write tests that depend on the order in which this method returns objects. (see Do Not Depend on Object Ordering for more information).

If you want to ensure a certain count of results retrieved from this method, use wait_select_many or if you only want to get one item, use select_single instead.

Parameters:	type_name – Either a string naming the type you want, or a class of the appropriate type (the latter case is for overridden emulator classes). ap_result_sort_keys – list of object properties to sort the query result with (sort key priority starts with element 0 as highest priority and then descends down the list).
Raises ValueError:
	if neither type_name or keyword filters are provided.

See also

Tutorial Section Writing Custom Proxy Classes

select_single(type_name='*', **kwargs)

Get a single node from the introspection tree, with type equal to type_name and (optionally) matching the keyword filters present in kwargs.

You must specify either type_name, keyword filters or both.

This method searches recursively from the instance this method is called on. Calling select_single on the application (root) proxy object will search the entire tree. Calling select_single on an object in the tree will only search it’s descendants.

Example usage:

app.select_single('QPushButton', objectName='clickme')
# returns a QPushButton whose 'objectName' property is 'clickme'.

If nothing is returned from the query, this method raises StateNotFoundError.

Parameters:	type_name – Either a string naming the type you want, or a class of the appropriate type (the latter case is for overridden emulator classes).
Raises:	ValueError – if the query returns more than one item. If you want more than one item, use select_many instead. ValueError – if neither type_name or keyword filters are provided. StateNotFoundError – if the requested object was not found.

See also

Tutorial Section Writing Custom Proxy Classes

classmethod validate_dbus_object(path, _state)

Return whether this class is the appropriate proxy object class for a given dbus path and state.

The default version matches the name of the dbus object and the class. Subclasses of CustomProxyObject can override it to define a different validation method.

Parameters:	path – The dbus path of the object to check state – The dbus state dict of the object to check (ignored in default implementation)
Returns:	Whether this class is appropriate for the dbus object

wait_select_many(type_name='*', ap_query_timeout=10, ap_result_count=1, ap_result_sort_keys=None, **kwargs)

Get a list of nodes from the introspection tree, with type equal to type_name and (optionally) matching the keyword filters present in kwargs.

This method is identical to the select_many method, except that this method will poll the application under test for ap_query_timeout seconds in the event that the search result count is not greater than or equal to ap_result_count.

You must specify either type_name, keyword filters or both.

This method searches recursively from the instance this method is called on. Calling wait_select_many on the application (root) proxy object will search the entire tree. Calling wait_select_many on an object in the tree will only search it’s descendants.

Example Usage:

app.wait_select_many(
'QPushButton',
ap_query_timeout=5,
ap_result_count=2,
enabled=True
)
# returns at least 2 QPushButtons that are enabled, within
# 5 seconds.

Warning

The order in which objects are returned is not guaranteed. It is bad practise to write tests that depend on the order in which this method returns objects. (see Do Not Depend on Object Ordering for more information).

Parameters:	type_name – Either a string naming the type you want, or a class of the appropriate type (the latter case is for overridden emulator classes). ap_query_timeout – Time in seconds to wait for search criteria to match. ap_result_count – Minimum number of results to return. ap_result_sort_keys – list of object properties to sort the query result with (sort key priority starts with element 0 as highest priority and then descends down the list).
Raises ValueError:
	if neither type_name or keyword filters are provided. Also raises, if search result count does not match the number specified by ap_result_count within ap_query_timeout seconds.

See also

Tutorial Section Writing Custom Proxy Classes

wait_select_single(type_name='*', ap_query_timeout=10, **kwargs)

Get a proxy object matching some search criteria, retrying if no object is found until a timeout is reached.

This method is identical to the select_single method, except that this method will poll the application under test for 10 seconds in the event that the search criteria does not match anything.

This method will return single proxy object from the introspection tree, with type equal to type_name and (optionally) matching the keyword filters present in kwargs.

You must specify either type_name, keyword filters or both.

This method searches recursively from the proxy object this method is called on. Calling select_single on the application (root) proxy object will search the entire tree. Calling select_single on an object in the tree will only search it’s descendants.

Example usage:

app.wait_select_single('QPushButton', objectName='clickme')
# returns a QPushButton whose 'objectName' property is 'clickme'.
# will poll the application until such an object exists, or will
# raise StateNotFoundError after 10 seconds.

If nothing is returned from the query, this method raises StateNotFoundError after ap_query_timeout seconds.

Parameters:	type_name – Either a string naming the type you want, or a class of the appropriate type (the latter case is for overridden emulator classes). ap_query_timeout – Time in seconds to wait for search criteria to match.
Raises:	ValueError – if the query returns more than one item. If you want more than one item, use select_many instead. ValueError – if neither type_name or keyword filters are provided. StateNotFoundError – if the requested object was not found.

See also

Tutorial Section Writing Custom Proxy Classes

wait_until_destroyed(timeout=10)

Block until this object is destroyed in the application.

Block until the object this instance is a proxy for has been destroyed in the applicaiton under test. This is commonly used to wait until a UI component has been destroyed.

Parameters:	timeout – The number of seconds to wait for the object to be destroyed. If not specified, defaults to 10 seconds.
Raises RuntimeError:
	if the method timed out.

wait_until_not_moving(retry_attempts_count=20, retry_interval=0.5)

Block until this object is not moving.

Block until both x and y of the object stop changing. This is normally useful for cases, where there is a need to ensure an object is static before interacting with it.

Parameters:	retry_attempts_count – number of attempts to check if the object is moving. retry_interval – time in fractional seconds to be slept, between each attempt to check if the object moving.
Raises RuntimeError:
	if DBus node is still moving after number of retries specified in retry_attempts_count.

autopilot.introspection.CustomEmulatorBase

alias of ProxyBase

autopilot.introspection.is_element(ap_query_func, args, kwargs)

Call the ap_query_func with the args and indicate if it raises StateNotFoundError.

Param:	ap_query_func: The dbus query call to be evaluated.
Param:	args: The *ap_query_func positional parameters.
Param:	kwargs: The ap_query_func optional parameters.
Returns:	False if the ap_query_func raises StateNotFoundError, True otherwise.