Package for introspection object support and search.
This package contains the methods and classes that are of use for accessing dbus proxy objects and creating Custom Proxy Object classes.
For retrieving proxy objects for already existing processes use get_proxy_object_for_existing_process This takes search criteria and return a proxy object that can be queried and introspected.
For creating your own Custom Proxy Classes use autopilot.introspection.CustomEmulatorBase
See also
The tutorial section Writing Custom Proxy Classes for further details on using ‘CustomEmulatorBase’ to write custom proxy classes.
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
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. |
---|
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 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
Returns the parent of this object.
If this object has no parent (i.e.- it is the root of the introspection tree). Then it returns itself.
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 the object at the root of this tree.
This will return an object that represents the root of the introspection tree.
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 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: |
|
---|
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. |
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 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 ValueError: | |
if neither type_name or keyword filters are provided. |
See also
Tutorial Section Writing Custom Proxy Classes
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: |
|
See also
Tutorial Section Writing Custom Proxy Classes
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: |
|
---|---|
Returns: | Whether this class is appropriate for the dbus object |
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 10 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). |
---|---|
Raises: |
|
See also
Tutorial Section Writing Custom Proxy Classes
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. |
Given an object path, return the class name component.
Object introspection error occured.
Return a single proxy object for an application that is already running (i.e. launched outside of Autopilot).
Searches the given bus (supplied by the kwarg dbus_bus) for an application matching the search criteria (also supplied in kwargs, see further down for explaination on what these can be.) Returns a proxy object created using the supplied custom emulator emulator_base (which defaults to None).
This function take kwargs arguments containing search parameter values to use when searching for the target application.
Possible search criteria: (unless specified otherwise these parameters default to None)
Parameters: |
|
---|
Non-search parameters:
Parameters: |
|
---|
Exceptions possibly thrown by this function:
Raises: |
|
---|
Examples:
Retrieving 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'
)