autopilot.process - Process Control

class autopilot.process.ProcessManager[source]

A simple process manager class.

The process manager is used to handle processes, windows and applications. This class should not be instantiated directly however. To get an instance of the keyboard class, call create instead.

KNOWN_APPS = {'Remmina': {'process-name': 'remmina', 'desktop-file': 'remmina.desktop'}, 'Calculator': {'process-name': 'gnome-calculator', 'desktop-file': 'gnome-calculator.desktop'}, 'Terminal': {'process-name': 'gnome-terminal', 'desktop-file': 'gnome-terminal.desktop'}, 'Text Editor': {'process-name': 'gedit', 'desktop-file': 'gedit.desktop'}, 'System Settings': {'process-name': 'gnome-control-center', 'desktop-file': 'gnome-control-center.desktop'}, 'Mahjongg': {'process-name': 'gnome-mahjongg', 'desktop-file': 'gnome-mahjongg.desktop'}, 'Character Map': {'process-name': 'gucharmap', 'desktop-file': 'gucharmap.desktop'}}
static create(preferred_backend='')[source]

Get an instance of the ProcessManager class.

For more infomration on picking specific backends, see Advanced Backend Picking

Parameters:preferred_backend

A string containing a hint as to which backend you would like. Possible backends are:

  • BAMF - Get process information using the BAMF Application
    Matching Framework.
Raises:RuntimeError if autopilot cannot instantate any of the possible backends.
Raises:RuntimeError if the preferred_backend is specified and is not one of the possible backends for this device class.
Raises:BackendException if the preferred_backend is set, but that backend could not be instantiated.
classmethod register_known_application(name, desktop_file, process_name)[source]

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:
  • name – The name to be used when launching the application.
  • desktop_file – The filename (without path component) of the desktop file used to launch the application.
  • process_name – The name of the executable process that gets run.
Raises:

KeyError if application has been registered already

classmethod unregister_known_application(name)[source]

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_app(app_name, files=[], locale=None)[source]

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:
  • app_name – The application name. This name must either already be registered as one of the built-in applications that are supported by autopilot, or must have been registered using register_known_application beforehand.
  • files – (Optional) A list of paths to open with the given application. Not all applications support opening files in this way.
  • locale – (Optional) The locale will to set when the application is launched. If you want to launch an application without any localisation being applied, set this parameter to ‘C’.
Returns:

A Application instance.

start_app_window(app_name, files=[], locale=None)[source]

Open a single window for one of the known applications, and close it at the end of the test.

Parameters:
  • app_name – The application name. This name must either already be registered as one of the built-in applications that are supported by autopilot, or must have been registered with register_known_application beforehand.
  • files – (Optional) Should be a list of paths to open with the given application. Not all applications support opening files in this way.
  • locale – (Optional) The locale will to set when the application is launched. If you want to launch an application without any localisation being applied, set this parameter to ‘C’.
Raises:

AssertionError if no window was opened, or more than one window was opened.

Returns:

A Window instance.

get_open_windows_by_application(app_name)[source]

Get a list of ~autopilot.process.Window` instances for the given application name.

Parameters:app_name – The name of one of the well-known applications.
Returns:A list of Window instances.
close_all_app(app_name)[source]
get_app_instances(app_name)[source]
app_is_running(app_name)[source]
get_running_applications(user_visible_only=True)[source]

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.

get_running_applications_by_desktop_file(desktop_file)[source]

Return a list of applications with the desktop file desktop_file.

This method will return an empty list if no applications are found with the specified desktop file.

get_open_windows(user_visible_only=True)[source]

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_application_is_running(desktop_file, timeout)[source]

Wait until a given application is running.

Parameters:
  • desktop_file (string) – The name of the application desktop file.
  • timeout (integer) – The maximum time to wait, in seconds. If set to something less than 0, this method will wait forever.
Returns:

true once the application is found, or false if the application was not found until the timeout was reached.

launch_application(desktop_file, files=[], wait=True)[source]

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.

Raises:TypeError on invalid files parameter.
Returns:The Gobject process object.
class autopilot.process.Application[source]
desktop_file

Get the application desktop file.

This returns just the filename, not the full path. If the application no longer exists, this returns an empty string.

name

Get the application name.

Note

This may change according to the current locale. If you want a unique string to match applications against, use desktop_file instead.

icon

Get the application icon.

Returns:The name of the icon.
is_active

Is the application active (i.e. has keyboard focus)?

is_urgent

Is the application currently signalling urgency?

user_visible

Is this application visible to the user?

Note

Some applications (such as the panel) are hidden to the user but may still be returned.

get_windows()[source]

Get a list of the application windows.

class autopilot.process.Window[source]
x_id

Get the X11 Window Id.

x_win

Get the X11 window object of the underlying window.

get_wm_state

Get the state of the underlying window.

name

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.

title

Get the window title.

This may be different from the application name.

Note

This may change depending on the current locale.

geometry

Get the geometry for this window.

Returns:Tuple containing (x, y, width, height).
is_maximized

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.

application

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.

user_visible

Is this window visible to the user in the switcher?

is_hidden

Is this window hidden?

Windows are hidden when the ‘Show Desktop’ mode is activated.

is_focused

Is this window focused?

is_valid

Is this window object valid?

Invalid windows are caused by windows closing during the construction of this object instance.

monitor

Returns the monitor to which the windows belongs to

closed

Returns True if the window has been closed

close()[source]

Close the window.

set_focus()[source]