Wrapper around testtools.TestCase that adds significant functionality.
This class should be the base class for all autopilot test case classes. Not using this class as the base class disables several important convenience methods, and also prevents the use of the failed-test recording tools.
Some of the more notable features of this class include:
Application Launch Support
This class contains the methods start_app and start_app_window which will launch one of the well-known applications and return a BamfApplication or BamfWindow instance to the launched process respectively. All applications launched in this way will be closed when the test ends.
Set Unity & Compiz Options
The set_unity_option and set_compiz_option methods set a unity or compiz setting to a particular value for the duration of the current test only. This is useful if you want the window manager to behave in a particular fashion for a particular test, while being assured that any chances are non-destructive.
Patch Process Environment
The patch_environment method patches the process environment, for the duration of the current test only. This allows you to set an environment variable for the duration of the current test only.
Set a desktop wide gsettings option
Using the gsettings command because there is a bug with importing from gobject introspection and pygtk2 simultaneously, and the Xlib keyboard layout bits are very unwieldy. This seems like the best solution, even a little bit brutish.
Set an option in the unity compiz plugin options.
Note
The value will be set for the current test only, and automatically undone when the test ends.
Parameters: |
|
---|---|
Raises : | KeyError if the option named does not exist. |
Set a compiz option for the duration of this test only.
Note
The value will be set for the current test only, and automatically undone when the test ends.
Parameters: |
|
---|---|
Raises : | KeyError if the option named does not exist. |
Register an application with autopilot.
After calling this method, you may call start_app or start_app_window with the name parameter to start this application. You need only call this once within a test run - the application will remain registerred until the test run ends.
Parameters: |
|
---|---|
Raises : | KeyError if application has been registered already |
Unregister an application with the known_apps dictionary.
Parameters: | name – The name to be used when launching the application. |
---|---|
Raises : | KeyError if the application has not been registered. |
Start one of the known applications, and kill it on tear down.
Warning
This method will clear all instances of this application on tearDown, not just the one opened by this method! We recommend that you use the start_app_window method instead, as it is generally safer.
Parameters: |
|
---|---|
Returns: | A BamfApplication instance. |
Open a single window for one of the known applications, and close it at the end of the test.
Parameters: |
|
---|---|
Raises : | AssertionError if no window was opened, or more than one window was opened. |
Returns: | A BamfWindow instance. |
Get a list of BamfWindow instances for the given application name.
Parameters: | app_name – The name of one of the well-known applications. |
---|---|
Returns: | A list of BamfWindow instances. |
Patch the process environment, setting key with value value.
This patches os.environ for the duration of the test only. After calling this method, the following should be True:
os.environ[key] == value
After the test, the patch will be undone (including deleting the key if if didn’t exist before this method was called).
Note
Be aware that patching the environment in this way only affects the current autopilot process, and any processes spawned by autopilot. If you are planing on starting an application from within autopilot and you want this new application to read the patched environment variable, you must patch the environment before launching the new process.
Parameters: |
|
---|
Check that the visible window stack starts with the windows passed in.
Note
Minimised windows are skipped.
Parameters: | stack_start – An iterable of BamfWindow instances. |
---|---|
Raises : | AssertionError if the top of the window stack does not match the contents of the stack_start parameter. |
Assert that obj has properties equal to the key/value pairs in kwargs.
This method is intended to be used on objects whose attributes do not have the wait_for method (i.e.- objects that do not come from the autopilot DBus interface).
For example, from within a test, to assert certain properties on a BamfWindow instance:
self.assertProperty(my_window, is_maximized=True)
Note
assertProperties is a synonym for this method.
Parameters: |
|
---|---|
Raises : | ValueError if no keyword arguments were given. |
Raises : | ValueError if a named attribute is a callable object. |
Raises : | AssertionError if any of the attribute/value pairs in kwargs do not match the attributes on the object passed in. |
Assert that obj has properties equal to the key/value pairs in kwargs.
This method is intended to be used on objects whose attributes do not have the wait_for method (i.e.- objects that do not come from the autopilot DBus interface).
For example, from within a test, to assert certain properties on a BamfWindow instance:
self.assertProperty(my_window, is_maximized=True)
Note
assertProperties is a synonym for this method.
Parameters: |
|
---|---|
Raises : | ValueError if no keyword arguments were given. |
Raises : | ValueError if a named attribute is a callable object. |
Raises : | AssertionError if any of the attribute/value pairs in kwargs do not match the attributes on the object passed in. |
Utility functions to get shortcut keybindings for various parts of Unity.
Inside Autopilot we deal with keybindings by naming them with unique names. For example, instead of hard-coding the fact that ‘Alt+F2’ opens the command lens, we might call:
>>> keybindings.get('lens_reveal/command')
'Alt+F2'
Get a keybinding, given its well-known name.
Parameters: | binding_name (string) – |
---|---|
Raises : | TypeError if binding_name cannot be found in the bindings dictionaries. |
Returns the part of a keybinding that must be held permanently.
Use this function to split bindings like “Alt+Tab” into the part that must be held down. See get_tap_part for the part that must be tapped.
Raises : | ValueError if the binding specified does not have multiple parts. |
---|
Returns the part of a keybinding that must be tapped.
Use this function to split bindings like “Alt+Tab” into the part that must be held tapped. See get_hold_part for the part that must be held down.
Raises : | ValueError if the binding specified does not have multiple parts. |
---|
Bases: object
A helper class that makes it easier to use Unity keybindings.
Get an instance of the Keyboard class.
If variant is specified, it should be a string that specifies a backend to use. However, this hint can be ignored - autopilot will prefer to return a keyboard variant other than the one requested, rather than fail to return anything at all.
If autopilot cannot instantate any of the possible backends, a RuntimeError will be raised.
Get an instance of the Mouse class.
If variant is specified, it should be a string that specifies a backend to use. However, this hint can be ignored - autopilot will prefer to return a mouse variant other than the one requested, rather than fail to return anything at all.
If autopilot cannot instantate any of the possible backends, a RuntimeError will be raised.
Bases: object
A base class for all keyboard-type devices.
Send key press events only.
Parameters: | keys (string) – Keys you want pressed. |
---|
Example:
>>> press('Alt+F2')
presses the ‘Alt’ and ‘F2’ keys.
Send key release events only.
Parameters: | keys (string) – Keys you want released. |
---|
Example:
>>> release('Alt+F2')
releases the ‘Alt’ and ‘F2’ keys.
Press and release all items in ‘keys’.
This is the same as calling ‘press(keys);release(keys)’.
Parameters: | keys (string) – Keys you want pressed and released. |
---|
Example:
>>> press_and_release('Alt+F2')
presses both the ‘Alt’ and ‘F2’ keys, and then releases both keys.
Bases: object
A base class for all mouse-type classes.
Moves mouse to location (x, y).
Callers should avoid specifying the rate or time_between_events parameters unless they need a specific rate of movement.
Attempts to move the mouse to ‘object_proxy’s centre point.
It does this by looking for several attributes, in order. The first attribute found will be used. The attributes used are (in order):
- globalRect (x,y,w,h)
- center_x, center_y
- x, y, w, h
Raises : | ValueError if none of these attributes are found, or if an attribute is of an incorrect type. |
---|
Various classes for interacting with BAMF.
Bases: object
High-level class for interacting with Bamf from within a test.
Use this class to inspect the state of running applications and open windows.
Get a list of the currently running applications.
If user_visible_only is True (the default), only applications visible to the user in the switcher will be returned.
Return a list of applications that have the desktop file desktop_file.
This method may return an empty list, if no applications are found with the specified desktop file.
Return the application that has a child with the requested xid or None.
Get a list of currently open windows.
If user_visible_only is True (the default), only applications visible to the user in the switcher will be returned.
The result is sorted to be in stacking order.
Wait until a given application is running.
Parameters: |
|
---|---|
Returns: | true once the application is found, or false if the application was not found until the timeout was reached. |
Launch an application by specifying a desktop file.
Parameters: | files (List of strings) – List of files to pass to the application. Not all apps support this. |
---|
Note
If wait is True, this method will wait up to 10 seconds for the application to appear in the BAMF model.
Raises : | TypeError on invalid files parameter. |
---|---|
Returns: | The Gobject process object. |
Bases: object
Represents an application, with information as returned by Bamf.
Important
Don’t instantiate this class yourself. instead, use the methods as provided by the Bamf class.
Raises : | dbus.DBusException in the case of a DBus error. |
---|
Get the application desktop file.
This just returns the filename, not the full path. If the application no longer exists, this returns an empty string.
Get the application name.
Note
This may change according to the current locale. If you want a unique string to match applications against, use the desktop_file instead.
Bases: object
Represents an application window, as returned by Bamf.
Important
Don’t instantiate this class yourself. Instead, use the appropriate methods in BamfApplication.
Get the window name.
Note
This may change according to the current locale. If you want a unique string to match windows against, use the x_id instead.
Get the window title.
This may be different from the application name.
Note
This may change depending on the current locale.
Is the window maximized?
Maximized in this case means both maximized vertically and horizontally. If a window is only maximized in one direction it is not considered maximized.
Get the application that owns this window.
This method may return None if the window does not have an associated application. The ‘desktop’ window is one such example.
Is this window hidden?
Windows are hidden when the ‘Show Desktop’ mode is activated.
Functions to deal with ibus service.
Get the ibus bus object, possibly starting the ibus daemon if it’s not already running.
Raises : | RuntimeError in the case of ibus-daemon being unavailable. |
---|
Get a list of available input engines.
Get the list of input engines that have been activated.
Installs the engines in engine_list into the list of active iBus engines.
The specified engines must appear in the return list from get_available_input_engines().
Note
This function removes all other engines.
This function returns the list of engines installed before this function was called. The caller should pass this list to set_active_engines to restore ibus to it’s old state once the test has finished.
Parameters: | engine_list (List of strings) – List of engine names |
---|---|
Raises : | TypeError on invalid engine_list parameter. |
Raises : | ValueError when engine_list contains invalid engine name. |
Provide ability to register text files with the file lens.
Package for introspection support.
Bases: object
A mix-in class to make launching applications for introsection easier.
Important
You should not instantiate this class directly. Instead, use one of the derived classes.
Launch application and retrieve a proxy object for the application.
Use this method to launch a supported application and start testing it. The application can be specified as:
- A Desktop file, either with or without a path component.
- An executable file, either with a path, or one that is in the $PATH.
This method supports the following keyword arguments:
- launch_dir. If set to a directory that exists the process will be launched from that directory.
- capture_output. If set to True (the default), the process output will be captured and attached to the test as test detail.
Raises : | ValueError if unknown keyword arguments are passed. |
---|---|
Returns: | A proxy object that represents the application. Introspection data is retrievable via this object. |
Launch an autopilot-enabled process and return the proxy object.
Get a list of all child process Ids, for the given parent.
Return the autopilot proxy object for the given process.
Raises : | RuntimeError if no autopilot interface was found. |
---|
Returns a root proxy object given a DBus service name.
Return tuple of the base classes to use when creating a proxy object for the given service name & path.
Raises : | RuntimeError if the autopilot interface cannot be found. |
---|
Return the class name and root state dictionary.
Bases: autopilot.introspection.dbus.DBusIntrospectionObject
A class that better supports query data from an application.
Get a single node from the introspection tree, with type equal to type_name and (optionally) matching the keyword filters present in kwargs.
For example:
>>> 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.
Raises : | ValueError if the query returns more than one item. If you want more than one item, use select_many instead. |
---|
Get a list of nodes from the introspection tree, with type equal to type_name and (optionally) matching the keyword filters present in kwargs.
For example:
>>> app.select_many('QPushButton', enabled=True)
... returns a list of QPushButtons that are enabled.
If you only want to get one item, use select_single instead.
This module contains the code to retrieve state via DBus calls.
Under normal circumstances, the only thing you should need to use from this module is the DBusIntrospectableObject class.
Bases: exceptions.RuntimeError
Raised when a piece of state information from unity is not found.
Bases: type
Metaclass to insert appropriate classes into the object registry.
Clear the object registry.
Important
DO NOT CALL THIS UNLESS YOU REALLY KNOW WHAT YOU ARE DOING! ... and even then, are you sure?
Get the autopilot introspection interface for the specified service name and object path.
Parameters: |
|
---|---|
Raises : | TypeError on invalid parameter type |
Translates the state_dict passed in so the keys are usable as python attributes.
Return true if instance satisifies all the filters present in kwargs.
Bases: object
A class that can be created using a dictionary of state from DBus.
To use this class properly you must set the DBUS_SERVICE and DBUS_OBJECT class attributes. They should be set to the Service name and object path where the autopilot interface is being exposed.
Creates and set attributes of self based on contents of state_dict.
Note
Translates ‘-‘ to ‘_’, so a key of ‘icon-type’ for example becomes ‘icon_type’.
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 LauncherInstances 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 (subclass of DBusIntrospectionObject, or a string.) – |
---|
Important
desired_type must be a subclass of DBusIntrospectionObject.
Refreshes the object’s state from unity.
Raises : | StateNotFound if the object in unity has been destroyed. |
---|
Get all instances of this class that exist within the Unity state tree.
For example, to get all the BamfLauncherIcons:
>>> icons = BamfLauncherIcons.get_all_instances()
Returns: | List (possibly empty) of class instances. |
---|
WARNING: Using this method is slow - it requires a complete scan of the introspection tree. Instead, get the root tree object with get_root_instance, and then navigate to the desired node.
Get state for a particular piece of the state tree.
piece is an XPath-like query that specifies which bit of the tree you want to look at.
Parameters: | piece (string) – |
---|---|
Raises : | TypeError on invalid piece parameter. |
Retrieve a new state dictionary for this class instance.
Note
The state keys in the returned dictionary are not translated.
Get the XPath query string required to refresh this class’s state.
Make an introspection object given a DBus tuple of (name, state_dict).
The optional ‘path_info’ parameter can be set to a string that contains the full, absolute path in the introspection tree to this object.
This only works for classes that derive from DBusIntrospectionObject.
Classes and tools to support Qt introspection.
Bases: autopilot.introspection.ApplicationIntrospectionTestMixin
A mix-in class to make Qt application introspection easier.
Inherit from this class if you want to launch and test Qt application with autopilot.
Bases: autopilot.introspection.ApplicationIntrospectionTestMixin
A mix-in class to make Gtk application introspection easier.
Autopilot-specific testtools matchers.
Bases: testtools.matchers._impl.Matcher
Asserts that a value will eventually equal a given Matcher object.
This works on objects that either have a wait_for(expected) function, or objects that are callable and return the most current value (i.e.- they refresh the objects value).