autopilot.introspection - Autopilot introspection internals

Package for introspection support.

This package contains the internal implementation of the autopilot introspection mechanism, and probably isn’t useful to most test authors.

autopilot.introspection.get_proxy_object_for_existing_process(pid=None, dbus_bus='session', connection_name=None, process=None, object_path='/com/canonical/Autopilot/Introspection', application_name=None, emulator_base=None)[source]

Return a single proxy object for an application that is already running (i.e. launched outside of Autopilot).

Searches on the given bus (supplied by dbus_bus) for an application matching the search criteria, creating the proxy object using the supplied custom emulator emulator_base (defaults to None).

For example for an application on the system bus where the applications PID is known:

app_proxy = get_proxy_object_for_existing_process(pid=app_pid)

Multiple criteria are allowed, for instance you could search on pid and connection_name:

app_proxy = get_proxy_object_for_existing_process(
    pid=app_pid, connection_name='org.gnome.gedit')

If the application from the previous example was on the system bus:

app_proxy = get_proxy_object_for_existing_process(
    dbus_bus='system', pid=app_pid, connection_name='org.gnome.gedit')

It is possible to search for the application given just the applications name. An example for an application running on a custom bus searching using the applications name:

app_proxy = get_proxy_object_for_existing_process(
    application_name='qmlscene',
    dbus_bus='unix:abstract=/tmp/dbus-IgothuMHNk')
Parameters:
  • pid – The PID of the application to search for.
  • dbus_bus – A string containing either ‘session’, ‘system’ or the custom buses name (i.e. ‘unix:abstract=/tmp/dbus-IgothuMHNk’).
  • connection_name – A string containing the DBus connection name to use with the search criteria.
  • object_path – A string containing the object path to use as the search criteria. Defaults to autopilot.introspection.constants.AUTOPILOT_PATH.
  • application_name – A string containing the applications name to search for.
  • emulator_base – The custom emulator to create the resulting proxy object with.
Raises:
  • ProcessSearchError – if no search criteria match.
  • RuntimeError – if the search criteria results in many matches.
  • RuntimeError – if both process and pid are supplied, but process.pid != pid.
class autopilot.introspection.CustomEmulatorBase(state_dict, path, backend)

This class must be used as a base class for any custom emulators defined within a test case.

See also

Tutorial Section Writing Custom Emulators Information on how to write custom emulators.

class autopilot.introspection.DBusIntrospectionObject(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.

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 Emulators

get_class_query_string()

Get the XPath query string required to refresh this class’s state.

get_new_state()

Retrieve a new state dictionary for this class instance.

You should probably never need to call this directly.

Note

The state keys in the returned dictionary are not translated.

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.

get_state_by_path(piece)

Get state for a particular piece of the state tree.

You should probably never need to call this directly.

Parameters:piece – an XPath-like query that specifies which bit of the tree you want to look at.
Raises :TypeError on invalid piece parameter.
make_introspection_object(dbus_tuple)

Make an introspection object given a DBus tuple of (path, state_dict).

This only works for classes that derive from DBusIntrospectionObject.

no_automatic_refreshing(*args, **kwds)

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.

refresh_state()

Refreshes the object’s state from unity.

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 unity has been destroyed.
select_many(type_name='*', **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 recurseivly::
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.

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).
Raises :TypeError if neither type_name or keyword filters are provided.

See also

Tutorial Section Writing Custom Emulators

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 returns None.

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.
  • TypeError – if neither type_name or keyword filters are provided.

See also

Tutorial Section Writing Custom Emulators

This Page