Merge lp:~nuclearbob/autopilot/pep257-b into lp:autopilot

[Max Brustkern]

Additional pep257 changes.

Additional pep257 changes. I'm going to set this back to WIP and look at the diff.

[Max Brustkern (nuclearbob)]

This is smaller, but it should be ready to go.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:451
http://jenkins.qa.ubuntu.com/job/autopilot-ci/575/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-amd64-ci/301/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-armhf-ci/301/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-i386-ci/210/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-trusty-autopilot/27/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-trusty-amd64/3925/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/autopilot-ci/575/rebuild

review: Needs Fixing (continuous-integration)

[lp:~nuclearbob/autopilot/pep257-b]

452. By Max Brustkern on 2014-03-19

Fixed flake8 issue

[Christopher Lee (veebers)]

LGTM

review: Approve

[lp:~nuclearbob/autopilot/pep257-b]

453. By Max Brustkern on 2014-03-20

Merged trunk

454. By Max Brustkern on 2014-03-20

Resolved conflict with other branch

455. By Max Brustkern on 2014-03-20

Merged proposed release

=== modified file 'autopilot/__init__.py'
--- autopilot/__init__.py	2014-02-21 16:36:39 +0000
+++ autopilot/__init__.py	2014-03-20 12:37:25 +0000
@@ -181,6 +181,7 @@
 
 
 def get_version_string():
+    """Return the autopilot source and package versions."""
     version_string = "Autopilot Source Version: " + _get_source_version()
     pkg_version = _get_package_version()
     if pkg_version:

=== modified file 'autopilot/application/__init__.py'
--- autopilot/application/__init__.py	2013-12-13 00:45:13 +0000
+++ autopilot/application/__init__.py	2014-03-20 12:37:25 +0000
@@ -21,12 +21,14 @@
 
 from autopilot.application._launcher import (
     ClickApplicationLauncher,
+    get_application_launcher_wrapper,
     NormalApplicationLauncher,
-    get_application_launcher_wrapper,
+    UpstartApplicationLauncher,
 )
 
 __all__ = [
     'ClickApplicationLauncher',
+    'get_application_launcher_wrapper',
     'NormalApplicationLauncher',
-    'get_application_launcher_wrapper',
+    'UpstartApplicationLauncher',
 ]

=== modified file 'autopilot/application/_environment.py'
--- autopilot/application/_environment.py	2014-01-29 21:28:12 +0000
+++ autopilot/application/_environment.py	2014-03-20 12:37:25 +0000
@@ -21,7 +21,6 @@
 
 import fixtures
 import os
-import subprocess
 
 
 class ApplicationEnvironment(fixtures.Fixture):
@@ -43,6 +42,8 @@
         """Prepare the application, or environment to launch with
         autopilot-support.
 
+        :returns: unmodified app_path and arguments
+
         """
         modules = os.getenv('GTK_MODULES', '').split(':')
         if 'autopilot' not in modules:
@@ -58,6 +59,8 @@
         """Prepare the application, or environment to launch with
         autopilot-support.
 
+        :returns: unmodified app_path and arguments
+
         """
         if '-testability' not in arguments:
             insert_pos = 0
@@ -68,34 +71,3 @@
             arguments.insert(insert_pos, '-testability')
 
         return app_path, arguments
-
-
-class UpstartApplicationEnvironment(ApplicationEnvironment):
-
-    def prepare_environment(self, app_path, arguments):
-        """Prepare the application, or environment to launch with
-        autopilot-support.
-
-        """
-        _set_upstart_env("QT_LOAD_TESTABILITY", 1)
-        self.addCleanup(_unset_upstart_env, "QT_LOAD_TESTABILITY")
-
-        return app_path, arguments
-
-
-def _set_upstart_env(key, value):
-    _call_upstart_with_args(
-        "set-env",
-        "{key}={value}".format(key=key, value=value)
-    )
-
-
-def _unset_upstart_env(key):
-    _call_upstart_with_args("unset-env", key)
-
-
-def _call_upstart_with_args(*arguments):
-    return subprocess.check_output(
-        ["/sbin/initctl"] + list(arguments),
-        universal_newlines=True
-    )

=== modified file 'autopilot/application/_launcher.py'
--- autopilot/application/_launcher.py	2014-03-09 20:10:51 +0000
+++ autopilot/application/_launcher.py	2014-03-20 12:37:25 +0000
@@ -20,6 +20,7 @@
 """Base module for application launchers."""
 
 import fixtures
+from gi.repository import GLib, UpstartAppLaunch
 import json
 import logging
 import os
@@ -32,10 +33,8 @@
 from autopilot._timeout import Timeout
 from autopilot.utilities import _raise_on_unknown_kwargs
 from autopilot.application._environment import (
-    _call_upstart_with_args,
     GtkApplicationEnvironment,
     QtApplicationEnvironment,
-    UpstartApplicationEnvironment,
 )
 
 
@@ -43,10 +42,12 @@
 
 
 class ApplicationLauncher(fixtures.Fixture):
+
     """A class that knows how to launch an application with a certain type of
     introspection enabled.
 
     """
+
     def __init__(self, case_addDetail):
         self.case_addDetail = case_addDetail
         super(ApplicationLauncher, self).__init__()
@@ -55,9 +56,16 @@
         raise NotImplementedError("Sub-classes must implement this method.")
 
 
-class ClickApplicationLauncher(ApplicationLauncher):
+class UpstartApplicationLauncher(ApplicationLauncher):
+
+    """A launcher class that launched applicaitons with UpstartAppLaunch."""
+
+    Timeout = object()
+    Failed = object()
+    Started = object()
+
     def __init__(self, case_addDetail, **kwargs):
-        super(ClickApplicationLauncher, self).__init__(case_addDetail)
+        super(UpstartApplicationLauncher, self).__init__(case_addDetail)
 
         self.emulator_base = kwargs.pop('emulator_base', None)
         self.dbus_bus = kwargs.pop('dbus_bus', 'session')
@@ -65,35 +73,100 @@
 
         _raise_on_unknown_kwargs(kwargs)
 
+    def launch(self, app_id, app_uris=[]):
+        state = {}
+        state['loop'] = self._get_glib_loop()
+        state['expected_app_id'] = app_id
+        state['message'] = ''
+
+        UpstartAppLaunch.observer_add_app_failed(self._on_failed, state)
+        UpstartAppLaunch.observer_add_app_started(self._on_started, state)
+        GLib.timeout_add_seconds(10.0, self._on_timeout, state)
+
+        self._launch_app(app_id, app_uris)
+        state['loop'].run()
+        UpstartAppLaunch.observer_delete_app_failed(self._on_failed)
+        UpstartAppLaunch.observer_delete_app_started(self._on_started)
+        self._maybe_add_application_cleanups(state)
+        self._check_status_error(
+            state.get('status', None),
+            state.get('message', '')
+        )
+        return self._get_pid_for_launched_app(app_id)
+
+    @staticmethod
+    def _on_failed(launched_app_id, failure_type, state):
+        if launched_app_id == state['expected_app_id']:
+            if failure_type == UpstartAppLaunch.AppFailed.CRASH:
+                state['message'] = 'Application crashed.'
+            elif failure_type == UpstartAppLaunch.AppFailed.START_FAILURE:
+                state['message'] = 'Application failed to start.'
+            state['status'] = UpstartApplicationLauncher.Failed
+            state['loop'].quit()
+
+    @staticmethod
+    def _on_started(launched_app_id, state):
+        if launched_app_id == state['expected_app_id']:
+            state['status'] = UpstartApplicationLauncher.Started
+            state['loop'].quit()
+
+    @staticmethod
+    def _on_timeout(state):
+        state['status'] = UpstartApplicationLauncher.Timeout
+        state['loop'].quit()
+
+    def _maybe_add_application_cleanups(self, state):
+        if state.get('status', None) == UpstartApplicationLauncher.Started:
+            app_id = state['expected_app_id']
+            self.addCleanup(self._stop_application, app_id)
+            self.addCleanup(self._attach_application_log, app_id)
+
+    def _attach_application_log(self, app_id):
+        log_path = UpstartAppLaunch.application_log_path(app_id)
+        if log_path:
+            self.case_addDetail(
+                "Application Log",
+                content_from_file(log_path)
+            )
+
+    def _stop_application(self, app_id):
+        UpstartAppLaunch.stop_application(app_id)
+
+    @staticmethod
+    def _get_glib_loop():
+        return GLib.MainLoop()
+
+    @staticmethod
+    def _get_pid_for_launched_app(app_id):
+        return UpstartAppLaunch.get_primary_pid(app_id)
+
+    @staticmethod
+    def _launch_app(app_name, app_uris):
+        UpstartAppLaunch.start_application_test(app_name, app_uris)
+
+    @staticmethod
+    def _check_status_error(status, extra_message=''):
+        message_parts = []
+        if status == UpstartApplicationLauncher.Timeout:
+            message_parts.append(
+                "Timed out while waiting for application to launch"
+            )
+        elif status == UpstartApplicationLauncher.Failed:
+            message_parts.append("Application Launch Failed")
+        if message_parts and extra_message:
+            message_parts.append(extra_message)
+        if message_parts:
+            raise RuntimeError(': '.join(message_parts))
+
+
+class ClickApplicationLauncher(UpstartApplicationLauncher):
+
     def launch(self, package_id, app_name, app_uris):
         app_id = _get_click_app_id(package_id, app_name)
-
-        _app_env = self.useFixture(UpstartApplicationEnvironment())
-        _app_env.prepare_environment(app_id, app_name)
-
-        return self._launch_click_app(app_id, app_uris)
-
-    def _launch_click_app(self, app_id, app_uris):
-        pid = _launch_click_app(app_id, app_uris)
-        self._add_click_launch_cleanup(app_id, pid)
-
-        logger.info(
-            "Click package %s has been launched with PID %d",
-            app_id,
-            pid
-        )
-
-        return pid
-
-    def _add_click_launch_cleanup(self, app_id, pid):
-        self.addCleanup(_kill_pid, pid)
-        self.addCleanup(self._add_log_cleanup, app_id)
-
-    def _add_log_cleanup(self, app_id):
-        self.case_addDetail(
-            "Application Log",
-            _get_click_application_log_content_object(app_id)
-        )
+        return self._do_upstart_launch(app_id, app_uris)
+
+    def _do_upstart_launch(self, app_id, app_uris):
+        return super(ClickApplicationLauncher, self).launch(app_id, app_uris)
 
 
 class NormalApplicationLauncher(ApplicationLauncher):
@@ -173,45 +246,6 @@
     return process
 
 
-def _is_process_running(pid):
-    return psutil.pid_exists(pid)
-
-
-def _launch_click_app(app_id, app_uris):
-    subprocess.check_output([
-        "/sbin/start",
-        "application",
-        "APP_ID={}".format(app_id),
-        "APP_URIS='{}'".format(app_uris),
-    ])
-
-    return _get_click_app_pid(app_id)
-
-
-def _get_click_app_status(app_id):
-    return _call_upstart_with_args(
-        "status",
-        "application-click",
-        "APP_ID={}".format(app_id)
-    )
-
-
-def _get_click_application_log_content_object(app_id):
-    try:
-        return content_from_file(
-            _get_click_application_log_path(app_id),
-            buffer_now=True
-        )
-    except IOError as e:
-        return text_content(u'Unable to open application log: %s' % (e,))
-
-
-def _get_click_application_log_path(app_id):
-    log_dir = os.path.expanduser('~/.cache/upstart/')
-    log_name = 'application-click-{}.log'.format(app_id)
-    return os.path.join(log_dir, log_name)
-
-
 def _get_click_app_id(package_id, app_name=None):
     for pkg in _get_click_manifest():
         if pkg['name'] == package_id:
@@ -241,47 +275,6 @@
     return json.loads(click_manifest_str)
 
 
-def _get_click_app_pid(app_id):
-    for _ in Timeout.default():
-        try:
-            list_output = _get_click_app_status(app_id)
-        except subprocess.CalledProcessError:
-            # application not started yet.
-            pass
-        else:
-            for line in list_output.split('\n'):
-                if app_id in line and "start/running" in line:
-                    return int(line.split()[-1])
-    else:
-        raise RuntimeError(
-            "Could not find autopilot interface for click package"
-            " '{}' after 10 seconds.".format(app_id)
-        )
-
-
-def _kill_pid(pid):
-    """Kill the process with the specified pid."""
-    logger.info("waiting for process to exit.")
-    _attempt_kill_pid(pid)
-    for _ in Timeout.default():
-        if not _is_process_running(pid):
-            break
-    else:
-        logger.info(
-            "Killing process group, since it hasn't exited after the default"
-            "timeout."
-        )
-        _attempt_kill_pid(pid, signal.SIGKILL)
-
-
-def _attempt_kill_pid(pid, sig=signal.SIGTERM):
-    try:
-        logger.info("Killing process %d", pid)
-        os.killpg(pid, sig)
-    except OSError:
-        logger.info("Appears process has already exited.")
-
-
 def _get_application_environment(app_type=None, app_path=None):
     if app_type is None and app_path is None:
         raise ValueError("Must specify either app_type or app_path.")
@@ -368,3 +361,15 @@
         )
         _attempt_kill_pid(process.pid, signal.SIGKILL)
     return u''.join(stdout_parts), u''.join(stderr_parts), process.returncode
+
+
+def _attempt_kill_pid(pid, sig=signal.SIGTERM):
+    try:
+        logger.info("Killing process %d", pid)
+        os.killpg(pid, sig)
+    except OSError:
+        logger.info("Appears process has already exited.")
+
+
+def _is_process_running(pid):
+    return psutil.pid_exists(pid)

=== modified file 'autopilot/dbus_handler.py'
--- autopilot/dbus_handler.py	2013-07-22 04:36:50 +0000
+++ autopilot/dbus_handler.py	2014-03-20 12:37:25 +0000
@@ -42,7 +42,7 @@
 
 
 def get_session_bus():
-    """This function returns a session bus that has had the DBus GLib main loop
+    """Return a session bus that has had the DBus GLib main loop
     initialised.
 
     """
@@ -51,7 +51,7 @@
 
 
 def get_system_bus():
-    """This function returns a system bus that has had the DBus GLib main loop
+    """Return a system bus that has had the DBus GLib main loop
     initialised.
 
     """
@@ -60,7 +60,7 @@
 
 
 def get_custom_bus(bus_address):
-    """This function returns a custom bus that has had the DBus GLib main loop
+    """Return a custom bus that has had the DBus GLib main loop
     initialised.
 
     """

=== modified file 'autopilot/display/_X11.py'
--- autopilot/display/_X11.py	2013-07-19 07:03:40 +0000
+++ autopilot/display/_X11.py	2014-03-20 12:37:25 +0000
@@ -44,11 +44,15 @@
         self._blacklisted_drivers = ["NVIDIA"]
 
     def get_num_screens(self):
-        """Get the number of screens attached to the PC."""
+        """Get the number of screens attached to the PC.
+
+        :returns: int indicating number of screens attached.
+
+        """
         return self._default_screen.get_n_monitors()
 
     def get_primary_screen(self):
-        """Returns an integer of which screen is considered the primary"""
+        """Return an integer of which screen is considered the primary."""
         return self._default_screen.get_primary_monitor()
 
     def get_screen_width(self, screen_number=0):

=== modified file 'autopilot/display/__init__.py'
--- autopilot/display/__init__.py	2014-02-12 01:07:08 +0000
+++ autopilot/display/__init__.py	2014-03-20 12:37:25 +0000
@@ -26,7 +26,7 @@
 
 
 def is_rect_on_screen(screen_number, rect):
-    """Returns True if *rect* is **entirely** on the specified screen, with no
+    """Return True if *rect* is **entirely** on the specified screen, with no
     overlap."""
     (x, y, w, h) = rect
     (mx, my, mw, mh) = Display.create().get_screen_geometry(screen_number)
@@ -34,7 +34,7 @@
 
 
 def is_point_on_screen(screen_number, point):
-    """Returns True if *point* is on the specified screen.
+    """Return True if *point* is on the specified screen.
 
     *point* must be an iterable type with two elements: (x, y)
 
@@ -45,7 +45,7 @@
 
 
 def is_point_on_any_screen(point):
-    """Returns true if *point* is on any currently configured screen."""
+    """Return true if *point* is on any currently configured screen."""
     return any([is_point_on_screen(m, point) for m in
                 range(Display.create().get_num_screens())])
 
@@ -99,7 +99,8 @@
 
 
 class Display(object):
-    """The base class/inteface for the display devices"""
+
+    """The base class/inteface for the display devices."""
 
     @staticmethod
     def create(preferred_backend=''):
@@ -121,6 +122,7 @@
             one of the possible backends for this device class.
         :raises: :class:`~autopilot.BackendException` if the preferred_backend
             is set, but that backend could not be instantiated.
+        :returns: Instance of Display with appropriate backend.
 
         """
         def get_x11_display():

=== modified file 'autopilot/globals.py'
--- autopilot/globals.py	2014-01-14 01:50:17 +0000
+++ autopilot/globals.py	2014-03-20 12:37:25 +0000
@@ -39,11 +39,12 @@
 
 
 def get_log_verbose():
-    """Returns true if the user asked for verbose logging."""
+    """Return true if the user asked for verbose logging."""
     return _test_logger._log_verbose
 
 
 class _TestLogger(CleanupRegistered):
+
     """A class that handles adding test logs as test result content."""
 
     def __init__(self):
@@ -98,6 +99,7 @@
 
 
 class _VideoLogger(CleanupRegistered):
+
     """Video capture autopilot tests, saving the results if the test failed."""
 
     _recording_app = '/usr/bin/recordmydesktop'

=== modified file 'autopilot/introspection/dbus.py'
--- autopilot/introspection/dbus.py	2014-03-11 16:39:25 +0000
+++ autopilot/introspection/dbus.py	2014-03-20 12:37:25 +0000
@@ -413,7 +413,7 @@
             of the appropriate type (the latter case is for overridden emulator
             classes).
 
-        :raises: **TypeError** if neither *type_name* or keyword filters are
+        :raises TypeError: if neither *type_name* or keyword filters are
             provided.
 
         .. seealso::
@@ -466,7 +466,7 @@
         automatically retrieves new state every time this object's attributes
         are read.
 
-        :raises: **StateNotFound** if the object in the application under test
+        :raises StateNotFound: if the object in the application under test
             has been destroyed.
 
         """
@@ -530,7 +530,7 @@
 
         :param piece: an XPath-like query that specifies which bit of the tree
             you want to look at.
-        :raises: **TypeError** on invalid *piece* parameter.
+        :raises TypeError: on invalid *piece* parameter.
 
         """
         if not isinstance(piece, six.string_types):
@@ -598,25 +598,16 @@
         (path, state_dict).
 
         This only works for classes that derive from DBusIntrospectionObject.
+
+        :returns: A proxy object that derives from DBusIntrospectionObject
+        :raises ValueError: if more than one class is appropriate for this
+                 dbus_tuple
+
         """
         path, state = dbus_tuple
-        name = get_classname_from_path(path)
-        try:
-            class_type = _object_registry[self._id][name]
-        except KeyError:
-            get_debug_logger().warning(
-                "Generating introspection instance for type '%s' based on "
-                "generic class.", name)
-            # we want the object to inherit from the custom emulator base, not
-            # the object class that is doing the selecting
-            for base in type(self).__bases__:
-                if issubclass(base, CustomEmulatorBase):
-                    base_class = base
-                    break
-            else:
-                base_class = type(self)
-            class_type = type(str(name), (base_class,), {})
-        return class_type(state, path, self._backend)
+        class_object = _get_proxy_object_class(
+            _object_registry[self._id], type(self), path, state)
+        return class_object(state, path, self._backend)
 
     def print_tree(self, output=None, maxdepth=None, _curdepth=0):
         """Print properties of the object and its children to a stream.
@@ -678,6 +669,24 @@
         finally:
             self.__refresh_on_attribute = True
 
+    @classmethod
+    def validate_dbus_object(cls, 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.
+
+        :param path: The dbus path of the object to check
+        :param state: The dbus state dict of the object to check
+                      (ignored in default implementation)
+        :returns: Whether this class is appropriate for the dbus object
+
+        """
+        name = get_classname_from_path(path)
+        return cls.__name__ == name
+
 
 def _is_valid_server_side_filter_param(key, value):
     """Return True if the key and value parameters are valid for server-side
@@ -741,6 +750,72 @@
         raise ValueError("Unsupported value type: {}".format(type(value)))
 
 
+def _get_proxy_object_class(proxy_class_dict, default_class, path, state):
+    """Return a custom proxy class, either from the list or the default.
+
+    Use helper functions to check the class list or return the default.
+    :param proxy_class_dict: dict of proxy classes to try
+    :param default_class: default class to use if nothing in dict matches
+    :param path: dbus path
+    :param state: dbus state
+    :returns: appropriate custom proxy class
+    :raises ValueError: if more than one class in the dict matches
+
+    """
+    class_type = _try_custom_proxy_classes(proxy_class_dict, path, state)
+    if class_type:
+        return class_type
+    return _get_default_proxy_class(default_class,
+                                    get_classname_from_path(path))
+
+
+def _try_custom_proxy_classes(proxy_class_dict, path, state):
+    """Identify which custom proxy class matches the dbus path and state.
+
+    If more than one class in proxy_class_dict matches, raise an exception.
+    :param proxy_class_dict: dict of proxy classes to try
+    :param path: dbus path
+    :param state: dbus state dict
+    :returns: matching custom proxy class
+    :raises ValueError: if more than one class matches
+
+    """
+    possible_classes = [c for c in proxy_class_dict.values() if
+                        c.validate_dbus_object(path, state)]
+    if len(possible_classes) > 1:
+        raise ValueError(
+            'More than one custom proxy class matches this object: '
+            'Matching classes are: %s. State is %s.  Path is %s.'
+            ','.join([repr(c) for c in possible_classes]),
+            repr(state),
+            path)
+    if len(possible_classes) == 1:
+        return possible_classes[0]
+    return None
+
+
+def _get_default_proxy_class(default_class, name):
+    """Return a custom proxy object class of the default or a base class.
+
+    We want the object to inherit from CustomEmulatorBase, not the object
+    class that is doing the selecting.
+    :param default_class: default class to use if no bases match
+    :param name: name of new class
+    :returns: custom proxy object class
+
+    """
+    get_debug_logger().warning(
+        "Generating introspection instance for type '%s' based on generic "
+        "class.", name)
+    for base in default_class.__bases__:
+        if issubclass(base, CustomEmulatorBase):
+            base_class = base
+            break
+    else:
+        base_class = default_class
+    return type(str(name), (base_class,), {})
+
+
 class _CustomEmulatorMeta(IntrospectableObjectMetaclass):
 
     def __new__(cls, name, bases, d):

=== modified file 'autopilot/keybindings.py'
--- autopilot/keybindings.py	2013-10-13 21:49:49 +0000
+++ autopilot/keybindings.py	2014-03-20 12:37:25 +0000
@@ -137,8 +137,10 @@
     """Get a keybinding, given its well-known name.
 
     :param string binding_name:
-    :raises: **TypeError** if binding_name cannot be found in the bindings
-     dictionaries.
+    :raises TypeError: if binding_name is not a string
+    :raises ValueError: if binding_name cannot be found in the bindings
+                        dictionaries.
+    :returns: string for keybinding
 
     """
     if not isinstance(binding_name, six.string_types):
@@ -153,12 +155,12 @@
 
 
 def get_hold_part(binding_name):
-    """Returns the part of a keybinding that must be held permanently.
+    """Return 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 :meth:`get_tap_part` for the part that must be tapped.
 
-    :raises: **ValueError** if the binding specified does not have multiple
+    :raises ValueError: if the binding specified does not have multiple
      parts.
 
     """
@@ -172,13 +174,13 @@
 
 
 def get_tap_part(binding_name):
-    """Returns the part of a keybinding that must be tapped.
+    """Return 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 :meth:`get_hold_part` for the part that must be held
     down.
 
-    :Raises: **ValueError** if the binding specified does not have multiple
+    :raises ValueError: if the binding specified does not have multiple
      parts.
 
     """
@@ -195,9 +197,10 @@
     """Given a keybinding name, get the keybinding string from the compiz
     option.
 
-    :raises: **ValueError** if the compiz setting described does not hold a
+    :raises ValueError: if the compiz setting described does not hold a
      keybinding.
-    :raises: **RuntimeError** if the compiz keybinding has been disabled.
+    :raises RuntimeError: if the compiz keybinding has been disabled.
+    :returns: compiz keybinding
 
     """
     plugin_name, setting_name = compiz_tuple
@@ -249,6 +252,7 @@
 
 
 class KeybindingsHelper(object):
+
     """A helper class that makes it easier to use Unity keybindings."""
 
     @property
@@ -294,7 +298,12 @@
 
 
 def _get_global_compiz_context():
-    """Get the compizconfig global context object."""
+    """Get the compizconfig global context object.
+
+    :returns: global compiz context, either already defined or from compiz
+              config
+
+    """
     global _global_compiz_context
     if _global_compiz_context is None:
         with Silence():
@@ -306,7 +315,8 @@
 def _get_compiz_plugin(plugin_name):
     """Get a compizconfig plugin with the specified name.
 
-    Raises KeyError of the plugin named does not exist.
+    :raises KeyError: if the plugin named does not exist.
+    :returns: compizconfig plugin
 
     """
     ctx = _get_global_compiz_context()
@@ -321,7 +331,8 @@
 def _get_compiz_setting(plugin_name, setting_name):
     """Get a compizconfig setting object, given a plugin name and setting name.
 
-    Raises KeyError if the plugin or setting is not found.
+    :raises KeyError: if the plugin or setting is not found.
+    :returns: compiz setting object
 
     """
     plugin = _get_compiz_plugin(plugin_name)

=== modified file 'autopilot/platform.py'
--- autopilot/platform.py	2014-01-27 22:23:58 +0000
+++ autopilot/platform.py	2014-03-20 12:37:25 +0000
@@ -130,6 +130,8 @@
 
     ... True
 
+    :returns: boolean indicating whether this is a tablet
+
     """
     return _PlatformDetector.create().is_tablet
 

=== modified file 'autopilot/run.py'
--- autopilot/run.py	2014-03-09 23:01:45 +0000
+++ autopilot/run.py	2014-03-20 12:37:25 +0000
@@ -53,7 +53,7 @@
 
 
 def setup_logging(verbose):
-    """Configure the root logger and verbose logging to stderr"""
+    """Configure the root logger and verbose logging to stderr."""
     root_logger = get_root_logger()
     root_logger.setLevel(logging.DEBUG)
     if verbose == 0:
@@ -173,6 +173,7 @@
     """Get the on-disk location of a package from a test id name.
 
     :raises ImportError: if the name could not be found.
+    :returns: path as a string
     """
     top_level_pkg = import_name.split('.')[0]
     _, path, _ = find_module(top_level_pkg, [os.getcwd()] + sys.path)
@@ -201,9 +202,9 @@
 
 
 def _discover_test(test_name):
-    """Returns tuple of TestSuite of found test , top_level_dir of test
+    """Return tuple of (TestSuite of found test, top_level_dir of test).
 
-    raises ImportError if test_name isn't a valid module or test name
+    :raises ImportError: if test_name isn't a valid module or test name
 
     """
     loader = TestLoader()
@@ -223,7 +224,7 @@
 
 
 def _discover_requested_tests(test_names):
-    """Returns a collection of tests that are under test_names.
+    """Return a collection of tests that are under test_names.
 
     returns a tuple containig a TestSuite of tests found and a boolean
     depicting wherether any difficulties were encountered while searching
@@ -252,7 +253,7 @@
 
 
 def _filter_tests(all_tests, test_names):
-    """Filters a given TestSuite for tests starting with any name contained
+    """Filter a given TestSuite for tests starting with any name contained
     within test_names.
 
     """
@@ -278,7 +279,7 @@
 
 
 def load_test_suite_from_name(test_names):
-    """Returns a test suite object given a dotted test names.
+    """Return a test suite object given a dotted test names.
 
     Returns a tuple containing the TestSuite and a boolean indicating wherever
     any issues where encountered during the loading process.
@@ -383,7 +384,7 @@
 
 
 def _get_app_name_and_args(argument_list):
-    """Returns a tuple of (app_name, [app_args])."""
+    """Return a tuple of (app_name, [app_args])."""
     return argument_list[0], argument_list[1:]
 
 

=== modified file 'autopilot/testcase.py'
--- autopilot/testcase.py	2014-02-12 01:12:55 +0000
+++ autopilot/testcase.py	2014-03-20 12:37:25 +0000
@@ -50,6 +50,7 @@
 
 import logging
 import os
+import six
 
 from testscenarios import TestWithScenarios
 from testtools import TestCase
@@ -59,6 +60,7 @@
     ClickApplicationLauncher,
     get_application_launcher_wrapper,
     NormalApplicationLauncher,
+    UpstartApplicationLauncher,
 )
 from autopilot.display import Display
 from autopilot.globals import get_debug_profile_fixture
@@ -122,6 +124,7 @@
 
 
 class AutopilotTestCase(TestWithScenarios, TestCase, KeybindingsHelper):
+
     """Wrapper around testtools.TestCase that adds significant functionality.
 
     This class should be the base class for all autopilot test case classes.
@@ -241,18 +244,24 @@
         :keyword emulator_base: If set, specifies the base class to be used for
             all emulators for this loaded application.
 
-        :raises: **ValueError** if unknown keyword arguments are passed.
+        :raises ValueError: if unknown keyword arguments are passed.
         :return: A proxy object that represents the application. Introspection
          data is retrievable via this object.
 
         """
+        logger.info(
+            "Attempting to launch application '%s' with arguments '%s' as a "
+            "normal process",
+            application,
+            ' '.join(arguments)
+        )
         launcher = self.useFixture(
             NormalApplicationLauncher(self.addDetail, **kwargs)
         )
 
         return self._launch_test_application(launcher, application, *arguments)
 
-    def launch_click_package(self, package_id, app_name=None, app_uris="",
+    def launch_click_package(self, package_id, app_name=None, app_uris=[],
                              **kwargs):
         """Launch a click package application with introspection enabled.
 
@@ -283,13 +292,55 @@
         :raises RuntimeError: If the specified app_name cannot be found within
             the specified click package.
 
+        :returns: proxy object for the launched package application
+
         """
+        if isinstance(app_uris, (six.text_type, six.binary_type)):
+            app_uris = [app_uris]
+        logger.info(
+            "Attempting to launch click application '%s' from click package "
+            " '%s' and URIs '%s'",
+            app_name if app_name is not None else "(default)",
+            package_id,
+            ','.join(app_uris)
+        )
         launcher = self.useFixture(
             ClickApplicationLauncher(self.addDetail, **kwargs)
         )
         return self._launch_test_application(launcher, package_id, app_name,
                                              app_uris)
 
+    def launch_upstart_application(self, application_name, uris=[], **kwargs):
+        """Launch an application with upstart.
+
+        This method launched an application via the ``upstart-app-launch``
+        library, on platforms that support it.
+
+        Usage is similar to the
+        :py:meth:`AutopilotTestCase.launch_test_application`::
+
+            app_proxy = self.launch_upstart_application("gallery-app")
+
+        :param application_name: The name of the application to launch.
+        :keyword emulator_base: If set, specifies the base class to be used for
+            all emulators for this loaded application.
+
+        :raises RuntimeError: If the specified application cannot be launched.
+        :raises ValueError: If unknown keyword arguments are specified.
+        """
+        if isinstance(uris, (six.text_type, six.binary_type)):
+            uris = [uris]
+        logger.info(
+            "Attempting to launch application '%s' with URIs '%s' via "
+            "upstart-app-launch",
+            application_name,
+            ','.join(uris)
+        )
+        launcher = self.useFixture(
+            UpstartApplicationLauncher(self.addDetail, **kwargs)
+        )
+        return self._launch_test_application(launcher, application_name, uris)
+
     # Wrapper function tying the newer ApplicationLauncher behaviour with the
     # previous (to be depreciated) behaviour
     def _launch_test_application(self, launcher_instance, application, *args):
@@ -397,7 +448,7 @@
 
         :param stack_start: An iterable of
          :class:`~autopilot.process.Window` instances.
-        :raises: **AssertionError** if the top of the window stack does not
+        :raises AssertionError: if the top of the window stack does not
          match the contents of the stack_start parameter.
 
         """
@@ -427,9 +478,9 @@
         :param obj: The object to test.
         :param kwargs: One or more keyword arguments to match against the
          attributes of the *obj* parameter.
-        :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
+        :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.
 
         """
@@ -485,7 +536,7 @@
 
 
 def _compare_system_with_process_snapshot(snapshot_fn, old_snapshot):
-    """Compares an existing process snapshot with current running processes.
+    """Compare an existing process snapshot with current running processes.
 
     :param snapshot_fn: A callable that returns the current running process
         list.

=== modified file 'autopilot/testresult.py'
--- autopilot/testresult.py	2014-02-26 01:23:18 +0000
+++ autopilot/testresult.py	2014-03-20 12:37:25 +0000
@@ -37,15 +37,16 @@
 
 
 class LoggedTestResultDecorator(TestResultDecorator):
+
     """A decorator that logs messages to python's logging system."""
 
     def _log(self, level, message):
-        """Performs the actual message logging"""
+        """Perform the actual message logging."""
         if get_log_verbose():
             logging.getLogger().log(level, message)
 
     def _log_details(self, level, details):
-        """Logs the relavent test details"""
+        """Log the relavent test details."""
         for detail in details:
             # Skip the test-log as it was logged while the test executed
             if detail == "test-log":
@@ -64,7 +65,7 @@
         return super(type(self), self).addError(test, err, details)
 
     def addFailure(self, test, err=None, details=None):
-        """Called for a test which failed an assert"""
+        """Called for a test which failed an assert."""
         self._log(logging.ERROR, "FAIL: %s" % (test.id()))
         if hasattr(test, "getDetails"):
             self._log_details(logging.ERROR, test.getDetails())
@@ -72,7 +73,11 @@
 
 
 def get_output_formats():
-    """Get information regarding the different output formats supported."""
+    """Get information regarding the different output formats supported.
+
+    :returns: dict of supported formats and appropriate construct functions
+
+    """
     supported_formats = {}
 
     supported_formats['text'] = _construct_text

=== modified file 'autopilot/tests/functional/__init__.py'
--- autopilot/tests/functional/__init__.py	2014-03-10 06:02:13 +0000
+++ autopilot/tests/functional/__init__.py	2014-03-20 12:37:25 +0000
@@ -21,16 +21,14 @@
 from __future__ import absolute_import
 
 from codecs import open
-import fixtures
 import os
 import os.path
 import sys
 import logging
 from shutil import rmtree
 import subprocess
-from tempfile import mkdtemp, mkstemp
+from tempfile import mkdtemp
 from testtools.content import text_content
-from textwrap import dedent
 
 from autopilot.testcase import AutopilotTestCase
 
@@ -150,89 +148,6 @@
         return script_file
 
 
-class TempDesktopFile(fixtures.Fixture):
-    def setUp(self):
-        super(TempDesktopFile, self).setUp()
-        path_created = TempDesktopFile._ensure_desktop_dir_exists()
-        self._desktop_file_path = self._create_desktop_file()
-
-        self.addCleanup(
-            TempDesktopFile._remove_desktop_file_components,
-            path_created,
-            self._desktop_file_path,
-        )
-
-    def get_desktop_file_path(self):
-        return self._desktop_file_path
-
-    @staticmethod
-    def _ensure_desktop_dir_exists():
-        desktop_file_dir = TempDesktopFile._desktop_file_dir()
-        if not os.path.exists(desktop_file_dir):
-            return TempDesktopFile._create_desktop_file_dir(desktop_file_dir)
-        return ''
-
-    @staticmethod
-    def _desktop_file_dir():
-        return os.path.join(
-            os.getenv('HOME'),
-            '.local',
-            'share',
-            'applications'
-        )
-
-    @staticmethod
-    def _create_desktop_file_dir(desktop_file_dir):
-        """Create the directory specified.
-
-        Returns the component of the path that did not exist, or the empty
-        string if the entire path already existed.
-
-        """
-        # We might be creating more than just the leaf directory, so we need to
-        # keep track of what doesn't already exist and remove it when we're
-        # done. Defaults to removing the full path
-        path_to_delete = ""
-        if not os.path.exists(desktop_file_dir):
-            path_to_delete = desktop_file_dir
-        full_path, leaf = os.path.split(desktop_file_dir)
-        while leaf != "":
-            if not os.path.exists(full_path):
-                path_to_delete = full_path
-            full_path, leaf = os.path.split(full_path)
-
-        try:
-            os.makedirs(desktop_file_dir)
-        except OSError:
-            logger.warning("Directory already exists: %s" % desktop_file_dir)
-        return path_to_delete
-
-    @staticmethod
-    def _remove_desktop_file_components(created_path, created_file):
-        if created_path != "":
-            rmtree(created_path)
-        else:
-            os.remove(created_file)
-
-    @staticmethod
-    def _create_desktop_file():
-        _, tmp_file_path = mkstemp(
-            suffix='.desktop',
-            dir=TempDesktopFile._desktop_file_dir()
-        )
-        with open(tmp_file_path, 'w') as desktop_file:
-            desktop_file.write(
-                dedent("""\
-                [Desktop Entry]
-                Type=Application
-                Exec=Not important
-                Path=Not important
-                Name=Test app
-                Icon=Not important""")
-            )
-        return tmp_file_path
-
-
 def _get_environment_patch(pythonpath):
     environment_patch = dict(DISPLAY=':0')
 

=== added file 'autopilot/tests/functional/fixtures.py'
--- autopilot/tests/functional/fixtures.py	1970-01-01 00:00:00 +0000
+++ autopilot/tests/functional/fixtures.py	2014-03-20 12:37:25 +0000
@@ -0,0 +1,170 @@
+# -*- Mode: Python; coding: utf-8; indent-tabs-mode: nil; tab-width: 4 -*-
+#
+# Autopilot Functional Test Tool
+# Copyright (C) 2014 Canonical
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+"""Fixtures for the autopilot functional test suite."""
+
+from __future__ import absolute_import
+
+import logging
+import os
+import stat
+from shutil import rmtree
+import tempfile
+from textwrap import dedent
+
+from fixtures import Fixture
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExecutableScript(Fixture):
+    """Write some text to a file on disk and make it executable."""
+
+    def __init__(self, script, extension=".py"):
+        """Initialise the fixture.
+
+        :param script: The contents of the script file.
+        :param extension: The desired extension on the script file.
+
+        """
+        super(ExecutableScript, self).__init__()
+        self._script = script
+        self._extension = extension
+
+    def setUp(self):
+        super(ExecutableScript, self).setUp()
+        with tempfile.NamedTemporaryFile(
+            suffix=self._extension,
+            mode='w',
+            delete=False
+        ) as f:
+            f.write(self._script)
+            self.path = f.name
+        self.addCleanup(os.unlink, self.path)
+
+        os.chmod(self.path, os.stat(self.path).st_mode | stat.S_IXUSR)
+
+
+class TempDesktopFile(Fixture):
+
+    def __init__(self, type=None, exec_=None, name=None, icon=None):
+        """Create a TempDesktopFile instance.
+
+        Parameters control the contents of the created desktop file. Default
+        values will create a desktop file with bogus contents.
+
+        :param type: The type field in the created file. Defaults to
+            'Application'.
+        :param exec_: The path to the file to execute.
+        :param name: The name of the application being launched. Defaults to
+            "Test App".
+        """
+        super(TempDesktopFile, self).__init__()
+        type_line = type if type is not None else "Application"
+        exec_line = exec_ if exec_ is not None else "Not Important"
+        name_line = name if name is not None else "Test App"
+        icon_line = icon if icon is not None else "Not Important"
+        self._file_contents = dedent(
+            """\
+            [Desktop Entry]
+            Type={}
+            Exec={}
+            Name={}
+            Icon={}
+            """.format(type_line, exec_line, name_line, icon_line)
+        )
+
+    def setUp(self):
+        super(TempDesktopFile, self).setUp()
+        path_created = TempDesktopFile._ensure_desktop_dir_exists()
+        self._desktop_file_path = self._create_desktop_file(
+            self._file_contents,
+        )
+
+        self.addCleanup(
+            TempDesktopFile._remove_desktop_file_components,
+            path_created,
+            self._desktop_file_path,
+        )
+
+    def get_desktop_file_path(self):
+        return self._desktop_file_path
+
+    def get_desktop_file_id(self):
+        return os.path.splitext(os.path.basename(self._desktop_file_path))[0]
+
+    @staticmethod
+    def _ensure_desktop_dir_exists():
+        desktop_file_dir = TempDesktopFile._desktop_file_dir()
+        if not os.path.exists(desktop_file_dir):
+            return TempDesktopFile._create_desktop_file_dir(desktop_file_dir)
+        return ''
+
+    @staticmethod
+    def _desktop_file_dir():
+        return os.path.join(
+            os.getenv('HOME'),
+            '.local',
+            'share',
+            'applications'
+        )
+
+    @staticmethod
+    def _create_desktop_file_dir(desktop_file_dir):
+        """Create the directory specified.
+
+        Returns the component of the path that did not exist, or the empty
+        string if the entire path already existed.
+
+        """
+        # We might be creating more than just the leaf directory, so we need to
+        # keep track of what doesn't already exist and remove it when we're
+        # done. Defaults to removing the full path
+        path_to_delete = ""
+        if not os.path.exists(desktop_file_dir):
+            path_to_delete = desktop_file_dir
+        full_path, leaf = os.path.split(desktop_file_dir)
+        while leaf != "":
+            if not os.path.exists(full_path):
+                path_to_delete = full_path
+            full_path, leaf = os.path.split(full_path)
+
+        try:
+            os.makedirs(desktop_file_dir)
+        except OSError:
+            logger.warning("Directory already exists: %s" % desktop_file_dir)
+        return path_to_delete
+
+    @staticmethod
+    def _remove_desktop_file_components(created_path, created_file):
+        if created_path != "":
+            rmtree(created_path)
+        else:
+            os.remove(created_file)
+
+    @staticmethod
+    def _create_desktop_file(file_contents):
+        _, tmp_file_path = tempfile.mkstemp(
+            suffix='.desktop',
+            dir=TempDesktopFile._desktop_file_dir()
+        )
+        with open(tmp_file_path, 'w') as desktop_file:
+            desktop_file.write(file_contents)
+        return tmp_file_path

=== modified file 'autopilot/tests/functional/test_ap_apps.py'
--- autopilot/tests/functional/test_ap_apps.py	2014-03-10 01:54:54 +0000
+++ autopilot/tests/functional/test_ap_apps.py	2014-03-20 12:37:25 +0000
@@ -20,13 +20,11 @@
 
 import datetime
 import os
-import stat
 import subprocess
 import logging
 import sys
 import six
 from mock import patch
-from tempfile import mktemp
 from testtools import skipIf
 from testtools.matchers import (
     Equals,
@@ -40,7 +38,10 @@
 from autopilot.process import ProcessManager
 from autopilot.platform import model
 from autopilot.testcase import AutopilotTestCase
-from autopilot.tests.functional import TempDesktopFile
+from autopilot.tests.functional.fixtures import (
+    ExecutableScript,
+    TempDesktopFile,
+)
 from autopilot.introspection import (
     get_proxy_object_for_existing_process,
     ProcessSearchError,
@@ -86,15 +87,7 @@
         and return the path to the script file.
 
         """
-        path = mktemp(extension)
-        if six.PY3:
-            open(path, 'w', encoding='utf-8').write(content)
-        else:
-            open(path, 'w').write(content)
-        self.addCleanup(os.unlink, path)
-
-        os.chmod(path, os.stat(path).st_mode | stat.S_IXUSR)
-        return path
+        return self.useFixture(ExecutableScript(content, extension)).path
 
 
 class ApplicationLaunchTests(ApplicationTests):
@@ -238,7 +231,39 @@
         )
 
 
-class QtTests(ApplicationTests):
+class QmlTestMixin(object):
+
+    def get_qml_viewer_app_path(self):
+        try:
+            qtversions = subprocess.check_output(
+                ['qtchooser', '-list-versions'],
+                universal_newlines=True
+            ).split('\n')
+            check_func = self._find_qt_binary_chooser
+        except OSError:
+            # This means no qtchooser is installed, so let's check for
+            # qmlviewer and qmlscene manually, the old way
+            qtversions = ['qt4', 'qt5']
+            check_func = self._find_qt_binary_old
+
+        not_found = True
+        if 'qt4' in qtversions:
+            path = check_func('qt4', 'qmlviewer')
+            if path:
+                not_found = False
+                self.qml_viewer_app_path = path
+                self.patch_environment("QT_SELECT", "qt4")
+
+        if 'qt5' in qtversions:
+            path = check_func('qt5', 'qmlscene')
+            if path:
+                not_found = False
+                self.qml_viewer_app_path = path
+                self.patch_environment("QT_SELECT", "qt5")
+
+        if not_found:
+            self.skip("Neither qmlviewer nor qmlscene is installed")
+        return self.qml_viewer_app_path
 
     def _find_qt_binary_chooser(self, version, name):
         # Check for existence of the binary when qtchooser is installed
@@ -264,59 +289,21 @@
             path = None
         return path
 
-    def setUp(self):
-        super(QtTests, self).setUp()
-
-        try:
-            qtversions = subprocess.check_output(
-                ['qtchooser', '-list-versions'],
-                universal_newlines=True
-            ).split('\n')
-            check_func = self._find_qt_binary_chooser
-        except OSError:
-            # This means no qtchooser is installed, so let's check for
-            # qmlviewer and qmlscene manually, the old way
-            qtversions = ['qt4', 'qt5']
-            check_func = self._find_qt_binary_old
-
-        not_found = True
-        if 'qt4' in qtversions:
-            path = check_func('qt4', 'qmlviewer')
-            if path:
-                not_found = False
-                self.app_path = path
-                self.patch_environment("QT_SELECT", "qt4")
-
-        if 'qt5' in qtversions:
-            path = check_func('qt5', 'qmlscene')
-            if path:
-                not_found = False
-                self.app_path = path
-                self.patch_environment("QT_SELECT", "qt5")
-
-        if not_found:
-            self.skip("Neither qmlviewer nor qmlscene is installed")
-
-    def test_can_launch_qt_app(self):
-        extra_args = ''
-        if model() != "Desktop":
-            # We need to add the desktop-file-hint
-            desktop_file = self.useFixture(
-                TempDesktopFile()
-            ).get_desktop_file_path()
-            extra_args = '--desktop_file_hint={hint_file}'.format(
-                hint_file=desktop_file
-            )
-
-        app_proxy = self.launch_test_application(
-            self.app_path,
-            extra_args,
-            app_type='qt'
-        )
+
+class QtTests(ApplicationTests, QmlTestMixin):
+
+    def test_can_launch_normal_app(self):
+        path = self.get_qml_viewer_app_path()
+        app_proxy = self.launch_test_application(path, app_type='qt')
         self.assertTrue(app_proxy is not None)
 
+    def test_can_launch_upstart_app(self):
+        path = self.get_qml_viewer_app_path()
+        fixture = self.useFixture(TempDesktopFile(exec_=path,))
+        self.launch_upstart_application(fixture.get_desktop_file_id())
+
     @skipIf(model() != "Desktop", "Only suitable on Desktop (Qt4)")
-    def test_can_launch_qt_script(self):
+    def test_can_launch_normal_qt_script(self):
         path = self.write_script(dedent("""\
             #!%s
             from PyQt4.QtGui import QMainWindow, QApplication
@@ -330,6 +317,7 @@
         app_proxy = self.launch_test_application(path, app_type='qt')
         self.assertTrue(app_proxy is not None)
 
+    # TODO: move this into a test module that tests bamf.
     @skipIf(model() != 'Desktop', "Bamf only available on desktop (Qt4)")
     def test_bamf_geometry_gives_reliable_results(self):
         path = self.write_script(dedent("""\
@@ -413,17 +401,18 @@
 
 class GtkTests(ApplicationTests):
 
-    def setUp(self):
-        super(GtkTests, self).setUp()
-
+    def _get_mahjongg_path(self):
         try:
-            self.app_path = subprocess.check_output(
+            return subprocess.check_output(
                 ['which', 'gnome-mahjongg'], universal_newlines=True).strip()
-        except subprocess.CalledProcessError:
+        except:
+            return
+
+    def test_can_launch_gtk_app(self):
+        mahjongg_path = self._get_mahjongg_path()
+        if not mahjongg_path:
             self.skip("gnome-mahjongg not found.")
-
-    def test_can_launch_gtk_app(self):
-        app_proxy = self.launch_test_application(self.app_path)
+        app_proxy = self.launch_test_application(mahjongg_path)
         self.assertTrue(app_proxy is not None)
 
     def test_can_launch_gtk_script(self):

=== modified file 'autopilot/tests/functional/test_autopilot_functional.py'
--- autopilot/tests/functional/test_autopilot_functional.py	2014-03-10 04:06:08 +0000
+++ autopilot/tests/functional/test_autopilot_functional.py	2014-03-20 12:37:25 +0000
@@ -55,6 +55,9 @@
         This assertion is intelligent enough to know that tests are not always
         printed in alphabetical order.
 
+        'tests' can either be a list of test ids, or a list of tuples
+        containing (scenario_count, test_id), in the case of scenarios.
+
         """
 
         if type(tests) is not list:
@@ -63,8 +66,16 @@
             raise TypeError("output must be a string, not %r" % type(output))
 
         expected_heading = 'Loading tests from: %s\n\n' % self.base_path
-        expected_tests = ['    %s' % t for t in tests]
-        expected_footer = ' %d total %s.' % (len(tests), total_title)
+        expected_tests = []
+        expected_total = 0
+        for test in tests:
+            if type(test) == tuple:
+                expected_tests.append(' *%d %s' % test)
+                expected_total += test[0]
+            else:
+                expected_tests.append('    %s' % test)
+                expected_total += 1
+        expected_footer = ' %d total %s.' % (expected_total, total_title)
 
         parts = output.split('\n')
         observed_heading = '\n'.join(parts[:2]) + '\n'
@@ -232,20 +243,16 @@
             """)
         )
 
-        expected_output = '''\
-Loading tests from: %s
-
- *2 tests.test_simple.SimpleTest.test_simple
- *2 tests.test_simple.SimpleTest.test_simple_two
-
-
- 4 total tests.
-''' % self.base_path
-
         code, output, error = self.run_autopilot_list()
         self.assertThat(code, Equals(0))
         self.assertThat(error, Equals(''))
-        self.assertThat(output, Equals(expected_output))
+        self.assertTestsInOutput(
+            [
+                (2, 'tests.test_simple.SimpleTest.test_simple'),
+                (2, 'tests.test_simple.SimpleTest.test_simple_two'),
+            ],
+            output
+        )
 
     def test_can_list_invalid_scenarios(self):
         """Autopilot must ignore scenarios that are not lists."""

=== modified file 'autopilot/tests/functional/test_input_stack.py'
--- autopilot/tests/functional/test_input_stack.py	2014-02-26 01:08:27 +0000
+++ autopilot/tests/functional/test_input_stack.py	2014-03-20 12:37:25 +0000
@@ -34,7 +34,7 @@
 from autopilot.input._common import get_center_point
 from autopilot.matchers import Eventually
 from autopilot.testcase import AutopilotTestCase, multiply_scenarios
-from autopilot.tests.functional import TempDesktopFile
+from autopilot.tests.functional.fixtures import TempDesktopFile
 from autopilot.utilities import on_test_started
 
 

=== modified file 'autopilot/tests/functional/test_introspection_features.py'
--- autopilot/tests/functional/test_introspection_features.py	2014-02-26 01:08:27 +0000
+++ autopilot/tests/functional/test_introspection_features.py	2014-03-20 12:37:25 +0000
@@ -43,7 +43,7 @@
 from autopilot import platform
 from autopilot.matchers import Eventually
 from autopilot.testcase import AutopilotTestCase
-from autopilot.tests.functional import TempDesktopFile
+from autopilot.tests.functional.fixtures import TempDesktopFile
 from autopilot.introspection.dbus import CustomEmulatorBase
 from autopilot.introspection import _connection_matches_pid
 from autopilot.display import Display

=== modified file 'autopilot/tests/functional/test_process_emulator.py'
--- autopilot/tests/functional/test_process_emulator.py	2014-02-03 04:32:54 +0000
+++ autopilot/tests/functional/test_process_emulator.py	2014-03-20 12:37:25 +0000
@@ -16,20 +16,23 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
-
+import os
 from subprocess import Popen, call
+import sys
 from testtools import skipIf
 from testtools.matchers import Equals, NotEquals, LessThan
+from textwrap import dedent
 from threading import Thread
 from time import sleep, time
 
-from autopilot import platform
+from autopilot.platform import model
 from autopilot.exceptions import BackendException
 from autopilot.testcase import AutopilotTestCase
 from autopilot.process import ProcessManager
-
-
-@skipIf(platform.model() != "Desktop", "Not suitable for device (ProcManager)")
+from autopilot.tests.functional.fixtures import ExecutableScript
+
+
+@skipIf(model() != "Desktop", "Not suitable for device (ProcManager)")
 class ProcessEmulatorTests(AutopilotTestCase):
 
     def ensure_gedit_not_running(self):
@@ -89,6 +92,28 @@
         self.assertThat(app, NotEquals(None))
         self.assertThat(app.name, Equals('Calculator'))
 
+    @skipIf(model() != 'Desktop', "Bamf only available on desktop (Qt4)")
+    def test_bamf_geometry_gives_reliable_results(self):
+        script = dedent("""\
+            #!%s
+            from PyQt4.QtGui import QMainWindow, QApplication
+            from sys import argv
+
+            app = QApplication(argv)
+            win = QMainWindow()
+            win.show()
+            app.exec_()
+            """ % sys.executable)
+        path = self.useFixture(ExecutableScript(script)).path
+        app_proxy = self.launch_test_application(path, app_type='qt')
+        proxy_window = app_proxy.select_single('QMainWindow')
+        pm = ProcessManager.create()
+        window = [
+            w for w in pm.get_open_windows()
+            if w.name == os.path.basename(path)
+        ][0]
+        self.assertThat(list(window.geometry), Equals(proxy_window.geometry))
+
 
 class ProcessManagerApplicationNoCleanupTests(AutopilotTestCase):
     """Testing the process manager without the automated cleanup that running

=== modified file 'autopilot/tests/unit/test_application_environment.py'
--- autopilot/tests/unit/test_application_environment.py	2014-01-09 03:12:32 +0000
+++ autopilot/tests/unit/test_application_environment.py	2014-03-20 12:37:25 +0000
@@ -19,14 +19,12 @@
 
 from mock import patch
 from testtools import TestCase
-from testtools.matchers import raises, Equals
+from testtools.matchers import raises
 
 from autopilot.application._environment import (
-    _call_upstart_with_args,
     ApplicationEnvironment,
     GtkApplicationEnvironment,
     QtApplicationEnvironment,
-    UpstartApplicationEnvironment,
 )
 
 
@@ -40,11 +38,6 @@
             )
         )
 
-    @patch('autopilot.application._environment.subprocess')
-    def test_call_upstart_with_args_returns_output(self, patched_subprocess):
-        patched_subprocess.check_output.return_value = "Returned Value"
-        self.assertThat(_call_upstart_with_args(), Equals("Returned Value"))
-
 
 class GtkApplicationEnvironmentTests(TestCase):
 
@@ -105,52 +98,3 @@
             'app', ['-testability']
         )
         self.assertEqual(['-testability'], args)
-
-
-class UpstartApplicationEnvironmentTests(TestCase):
-
-    # These tests patch _unset_upstart_env as cleanUps() calls the unpatched
-    # _unset_upstart_env which in turn calls the real _call_upstart_with_args
-    # (making a system call)
-    @patch('autopilot.application._environment._call_upstart_with_args')
-    @patch('autopilot.application._environment._unset_upstart_env')
-    def test_does_not_alter_app(self, patched_unset, patched_call_upstart):
-        app_environment = self.useFixture(UpstartApplicationEnvironment())
-        fake_app = self.getUniqueString()
-        app, args = app_environment.prepare_environment(fake_app, [])
-
-        self.assertEqual(fake_app, app)
-
-    @patch('autopilot.application._environment._call_upstart_with_args')
-    @patch('autopilot.application._environment._unset_upstart_env')
-    def test_does_not_alter_args(self, patched_unset, patched_call_upstart):
-        app_environment = self.useFixture(UpstartApplicationEnvironment())
-        fake_app = self.getUniqueString()
-        app, args = app_environment.prepare_environment(fake_app, [])
-
-        self.assertEqual([], args)
-
-    @patch('autopilot.application._environment._call_upstart_with_args')
-    @patch('autopilot.application._environment._unset_upstart_env')
-    def test_patches_env(self, patched_unset, patched_call_upstart):
-        app_environment = self.useFixture(UpstartApplicationEnvironment())
-        fake_app = self.getUniqueString()
-        app, args = app_environment.prepare_environment(fake_app, [])
-
-        patched_call_upstart.called_with_args(
-            'set-env',
-            'QT_LOAD_TESTABILITY=1'
-        )
-
-    @patch('autopilot.application._environment._call_upstart_with_args')
-    def test_unpatches_env(self, patched_call_upstart):
-        app_environment = self.useFixture(UpstartApplicationEnvironment())
-        fake_app = self.getUniqueString()
-        app, args = app_environment.prepare_environment(fake_app, [])
-
-        app_environment.cleanUp()
-
-        patched_call_upstart.called_with_args(
-            'unset-env',
-            'QT_LOAD_TESTABILITY'
-        )

=== modified file 'autopilot/tests/unit/test_application_launcher.py'
--- autopilot/tests/unit/test_application_launcher.py	2014-03-09 20:10:51 +0000
+++ autopilot/tests/unit/test_application_launcher.py	2014-03-20 12:37:25 +0000
@@ -17,7 +17,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-import os
+from gi.repository import GLib
 import signal
 import subprocess
 from testtools import TestCase
@@ -25,6 +25,7 @@
     Contains,
     Equals,
     GreaterThan,
+    HasLength,
     IsInstance,
     MatchesListwise,
     Not,
@@ -32,16 +33,17 @@
     raises,
 )
 from testtools.content import text_content
+import tempfile
 from mock import Mock, patch
 
 from autopilot.application import (
     ClickApplicationLauncher,
     NormalApplicationLauncher,
+    UpstartApplicationLauncher,
 )
 from autopilot.application._environment import (
     GtkApplicationEnvironment,
     QtApplicationEnvironment,
-    UpstartApplicationEnvironment,
 )
 import autopilot.application._launcher as _l
 from autopilot.application._launcher import (
@@ -53,15 +55,9 @@
     _get_application_environment,
     _get_application_path,
     _get_click_app_id,
-    _get_click_app_pid,
-    _get_click_app_status,
-    _get_click_application_log_content_object,
-    _get_click_application_log_path,
     _get_click_manifest,
     _is_process_running,
-    _kill_pid,
     _kill_process,
-    _launch_click_app,
 )
 from autopilot.utilities import sleep
 
@@ -189,15 +185,38 @@
             launcher.dbus_application_name, Equals(app_name)
         )
 
-    @patch.object(UpstartApplicationEnvironment, 'prepare_environment')
-    def test_prepare_environment_called(self, prep_env):
-        with patch.object(_l, '_get_click_app_id', return_value="app_id"):
+    def test_click_launch_calls_upstart_launch(self):
+        launcher = ClickApplicationLauncher(self.addDetail)
+        token = self.getUniqueString()
+        with patch.object(launcher, '_do_upstart_launch') as p_dul:
+            with patch.object(_l, '_get_click_app_id') as p_gcai:
+                p_gcai.return_value = token
+                launcher.launch('some_app_id', 'some_app_name', [])
+                p_dul.assert_called_once_with(token, [])
+
+    def test_upcalls_to_upstart(self):
+        class FakeUpstartBase(_l.ApplicationLauncher):
+            launch_call_args = []
+
+            def launch(self, *args):
+                FakeUpstartBase.launch_call_args = list(args)
+
+        patcher = patch.object(
+            _l.ClickApplicationLauncher,
+            '__bases__',
+            (FakeUpstartBase,)
+        )
+        with patcher:
+            # Prevent mock from trying to delete __bases__
+            patcher.is_local = True
             launcher = ClickApplicationLauncher(self.addDetail)
-            launcher.setUp()
-            launcher._launch_click_app = Mock()
-
-            launcher.launch("package_id", "app_name", "")
-            prep_env.assert_called_with("app_id", "app_name")
+            launcher._do_upstart_launch('app_id', [])
+        self.assertEqual(
+            FakeUpstartBase.launch_call_args,
+            ['app_id', []])
+
+
+class ClickFunctionTests(TestCase):
 
     def test_get_click_app_id_raises_runtimeerror_on_empty_manifest(self):
         """_get_click_app_id must raise a RuntimeError if the requested
@@ -280,172 +299,285 @@
                 Equals("com.autopilot.testing_bar_1.0")
             )
 
-    def test_get_click_application_log_path_formats_correct_path(self):
-        path_token = self.getUniqueString()
-        expected = os.path.join(path_token, "application-click-foo.log")
-
-        with patch.object(_l.os.path, 'expanduser', return_value=path_token):
-            self.assertThat(
-                _get_click_application_log_path("foo"),
-                Equals(expected)
-            )
-
-    def test_get_click_application_log_content_object_returns_content_object(self):  # NOQA
-        with patch.object(_l, 'content_from_file') as from_file:
-            self.assertThat(
-                _get_click_application_log_content_object("foo"),
-                Equals(from_file())
-            )
-
-    def test_get_click_app_log_works_when_no_log_file_exists(self):
-        token = self.getUniqueString()
-        with patch.object(
-            _l,
-            '_get_click_application_log_path',
-            return_value=token
-        ):
-
-            self.assertThat(
-                lambda: _l._get_click_application_log_content_object("foo"),
-                Not(raises(IOError))
-            )
-
-    @patch.object(_l, '_launch_click_app', return_value=123)
-    def test_launch_click_app_returns_pid(self, patched_launch_click_app):
-        launcher = ClickApplicationLauncher(self.addDetail)
-        launcher._add_click_launch_cleanup = Mock()
-
-        with patch.object(_l, 'logger'):
-            self.assertThat(
-                launcher._launch_click_app("appid", ""),
-                Equals(123)
-            )
-
-    def test_add_click_launch_cleanup_queues_correct_cleanup_steps(self):
-        test_app_name = self.getUniqueString()
-        test_app_pid = self.getUniqueInteger()
-        launcher = ClickApplicationLauncher(self.addDetail)
-        launcher.setUp()
-        launcher._add_click_launch_cleanup(test_app_name, test_app_pid)
-
-        self.assertThat(
-            launcher._cleanups._cleanups,
-            MatchesListwise([
-                Equals((_kill_pid, (test_app_pid,), {})),
-                Equals((launcher._add_log_cleanup, (test_app_name,), {})),
-            ])
-        )
-
-    def test_add_click_launch_cleanup_provides_correct_details(self):
-        launcher = ClickApplicationLauncher(self.addDetail)
-        launcher.addCleanup = Mock()
-        test_app_id = self.getUniqueString()
-        test_app_pid = self.getUniqueInteger()
-
-        launcher._add_click_launch_cleanup(test_app_id, test_app_pid)
-        launcher.addCleanup.assert_any_call(_kill_pid, test_app_pid)
-        launcher.addCleanup.assert_any_call(
-            launcher._add_log_cleanup,
-            test_app_id
-        )
-
-    def test_add_log_cleanup_adds_details(self):
-        mock_addDetail = Mock()
-        launcher = ClickApplicationLauncher(mock_addDetail)
-        with patch.object(
-            _l, '_get_click_application_log_content_object'
-        ) as log_content:
-            launcher._add_log_cleanup("appid")
-
-            mock_addDetail.assert_called_with("Application Log", log_content())
+
+class UpstartApplicationLauncherTests(TestCase):
+
+    def test_can_construct_UpstartApplicationLauncher(self):
+        UpstartApplicationLauncher(self.addDetail)
+
+    def test_default_values_are_set(self):
+        launcher = UpstartApplicationLauncher(self.addDetail)
+        self.assertThat(launcher.emulator_base, Equals(None))
+        self.assertThat(launcher.dbus_bus, Equals('session'))
+
+    def test_can_set_emulator_base(self):
+        mock_emulator_base = Mock()
+        launcher = UpstartApplicationLauncher(
+            self.addDetail,
+            emulator_base=mock_emulator_base
+        )
+
+        self.assertThat(launcher.emulator_base, Equals(mock_emulator_base))
+
+    def test_can_set_dbus_bus(self):
+        launcher = UpstartApplicationLauncher(
+            self.addDetail,
+            dbus_bus='system'
+        )
+
+        self.assertThat(launcher.dbus_bus, Equals('system'))
+
+    def test_raises_exception_on_unknown_kwargs(self):
+        self.assertThat(
+            lambda: UpstartApplicationLauncher(self.addDetail, unknown=True),
+            raises(ValueError("Unknown keyword arguments: 'unknown'."))
+        )
+
+    def test_on_failed_only_sets_status_on_correct_app_id(self):
+        state = {
+            'expected_app_id': 'gedit',
+        }
+
+        UpstartApplicationLauncher._on_failed('some_game', None, state)
+
+        self.assertThat(state, Not(Contains('status')))
+
+    def assertFunctionSetsCorrectStateAndQuits(self, observer, expected_state):
+        """Assert that the observer observer sets the correct state id.
+
+        :param observer: The observer callable you want to test.
+        :param expected_state: The state id the observer callable must set.
+
+        """
+        expected_app_id = self.getUniqueString()
+        state = {
+            'expected_app_id': expected_app_id,
+            'loop': Mock()
+        }
+
+        if observer == UpstartApplicationLauncher._on_failed:
+            observer(expected_app_id, None, state)
+        elif observer == UpstartApplicationLauncher._on_started:
+            observer(expected_app_id, state)
+        else:
+            observer(state)
+
+        self.assertThat(
+            state['status'],
+            Equals(expected_state)
+        )
+        state['loop'].quit.assert_called_once_with()
+
+    def test_on_failed_sets_status_with_correct_app_id(self):
+        self.assertFunctionSetsCorrectStateAndQuits(
+            UpstartApplicationLauncher._on_failed,
+            UpstartApplicationLauncher.Failed
+        )
+
+    def test_on_started_sets_status_with_correct_app_id(self):
+        self.assertFunctionSetsCorrectStateAndQuits(
+            UpstartApplicationLauncher._on_started,
+            UpstartApplicationLauncher.Started
+        )
+
+    def test_on_timeout_sets_status_and_exits_loop(self):
+        self.assertFunctionSetsCorrectStateAndQuits(
+            UpstartApplicationLauncher._on_timeout,
+            UpstartApplicationLauncher.Timeout
+        )
+
+    def test_on_started_only_sets_status_on_correct_app_id(self):
+        state = {
+            'expected_app_id': 'gedit',
+        }
+
+        UpstartApplicationLauncher._on_started('some_game', state)
+
+        self.assertThat(state, Not(Contains('status')))
+
+    def test_get_pid_calls_upstart_module(self):
+        expected_return = self.getUniqueInteger()
+        with patch.object(_l, 'UpstartAppLaunch') as mock_ual:
+            mock_ual.get_primary_pid.return_value = expected_return
+            observed = UpstartApplicationLauncher._get_pid_for_launched_app(
+                'gedit'
+            )
+
+            mock_ual.get_primary_pid.assert_called_once_with('gedit')
+            self.assertThat(expected_return, Equals(observed))
+
+    def test_launch_app_calls_upstart_module(self):
+        with patch.object(_l, 'UpstartAppLaunch') as mock_ual:
+            UpstartApplicationLauncher._launch_app(
+                'gedit',
+                ['some', 'uris']
+            )
+
+            mock_ual.start_application_test.assert_called_once_with(
+                'gedit',
+                ['some', 'uris']
+            )
+
+    def test_check_error_raises_RuntimeError_on_timeout(self):
+        fn = lambda: UpstartApplicationLauncher._check_status_error(
+            UpstartApplicationLauncher.Timeout
+        )
+        self.assertThat(
+            fn,
+            raises(
+                RuntimeError(
+                    "Timed out while waiting for application to launch"
+                )
+            )
+        )
+
+    def test_check_error_raises_RuntimeError_on_failure(self):
+        fn = lambda: UpstartApplicationLauncher._check_status_error(
+            UpstartApplicationLauncher.Failed
+        )
+        self.assertThat(
+            fn,
+            raises(
+                RuntimeError(
+                    "Application Launch Failed"
+                )
+            )
+        )
+
+    def test_check_error_raises_RuntimeError_with_extra_message(self):
+        fn = lambda: UpstartApplicationLauncher._check_status_error(
+            UpstartApplicationLauncher.Failed,
+            "extra message"
+        )
+        self.assertThat(
+            fn,
+            raises(
+                RuntimeError(
+                    "Application Launch Failed: extra message"
+                )
+            )
+        )
+
+    def test_check_error_does_nothing_on_None(self):
+        UpstartApplicationLauncher._check_status_error(None)
+
+    def test_get_loop_returns_glib_mainloop_instance(self):
+        loop = UpstartApplicationLauncher._get_glib_loop()
+        self.assertThat(loop, IsInstance(GLib.MainLoop))
+
+    def test_launch(self):
+        launcher = UpstartApplicationLauncher(self.addDetail)
+        with patch.object(launcher, '_launch_app') as patched_launch:
+            with patch.object(launcher, '_get_glib_loop'):
+                launcher.launch('gedit')
+
+                patched_launch.assert_called_once_with('gedit', [])
+
+    def assertFailedObserverSetsExtraMessage(self, fail_type, expected_msg):
+        """Assert that the on_failed observer must set the expected message
+        for a particular failure_type."""
+        expected_app_id = self.getUniqueString()
+        state = {
+            'expected_app_id': expected_app_id,
+            'loop': Mock()
+        }
+        UpstartApplicationLauncher._on_failed(
+            expected_app_id,
+            fail_type,
+            state
+        )
+        self.assertEqual(expected_msg, state['message'])
+
+    def test_on_failed_sets_message_for_app_crash(self):
+        self.assertFailedObserverSetsExtraMessage(
+            _l.UpstartAppLaunch.AppFailed.CRASH,
+            'Application crashed.'
+        )
+
+    def test_on_failed_sets_message_for_app_start_failure(self):
+        self.assertFailedObserverSetsExtraMessage(
+            _l.UpstartAppLaunch.AppFailed.START_FAILURE,
+            'Application failed to start.'
+        )
+
+    def test_add_application_cleanups_adds_both_cleanup_actions(self):
+        token = self.getUniqueString()
+        state = {
+            'status': UpstartApplicationLauncher.Started,
+            'expected_app_id': token,
+        }
+        launcher = UpstartApplicationLauncher(Mock())
+        launcher.setUp()
+        launcher._maybe_add_application_cleanups(state)
+        self.assertThat(
+            launcher._cleanups._cleanups,
+            Contains(
+                (launcher._attach_application_log, (token,), {})
+            )
+        )
+        self.assertThat(
+            launcher._cleanups._cleanups,
+            Contains(
+                (launcher._stop_application, (token,), {})
+            )
+        )
+
+    def test_add_application_cleanups_does_nothing_when_app_timedout(self):
+        state = {
+            'status': UpstartApplicationLauncher.Timeout,
+        }
+        launcher = UpstartApplicationLauncher(Mock())
+        launcher.setUp()
+        launcher._maybe_add_application_cleanups(state)
+        self.assertThat(launcher._cleanups._cleanups, HasLength(0))
+
+    def test_add_application_cleanups_does_nothing_when_app_failed(self):
+        state = {
+            'status': UpstartApplicationLauncher.Failed,
+        }
+        launcher = UpstartApplicationLauncher(Mock())
+        launcher.setUp()
+        launcher._maybe_add_application_cleanups(state)
+        self.assertThat(launcher._cleanups._cleanups, HasLength(0))
+
+    def test_attach_application_log_does_nothing_wth_no_log_specified(self):
+        app_id = self.getUniqueString()
+        case_addDetail = Mock()
+        launcher = UpstartApplicationLauncher(case_addDetail)
+        with patch.object(_l.UpstartAppLaunch, 'application_log_path') as p:
+            p.return_value = None
+            launcher._attach_application_log(app_id)
+
+            p.assert_called_once_with(app_id)
+            self.assertEqual(0, case_addDetail.call_count)
+
+    def test_attach_application_log_attaches_log_file(self):
+        token = self.getUniqueString()
+        case_addDetail = Mock()
+        launcher = UpstartApplicationLauncher(case_addDetail)
+        app_id = self.getUniqueString()
+        with tempfile.NamedTemporaryFile(mode='w') as f:
+            f.write(token)
+            f.flush()
+            with patch.object(_l.UpstartAppLaunch, 'application_log_path',
+                              return_value=f.name):
+                launcher._attach_application_log(app_id)
+
+                self.assertEqual(1, case_addDetail.call_count)
+                content_name, content_obj = case_addDetail.call_args[0]
+                self.assertEqual("Application Log", content_name)
+                self.assertThat(content_obj.as_text(), Contains(token))
+
+    def test_stop_applications_calls_UAL_stop_application(self):
+        app_id = self.getUniqueString()
+        launcher = UpstartApplicationLauncher(Mock())
+        with patch.object(_l.UpstartAppLaunch, 'stop_application') as p_stop:
+            launcher._stop_application(app_id)
+            p_stop.assert_called_once_with(app_id)
 
 
 class ApplicationLauncherInternalTests(TestCase):
 
-    def test_get_click_app_status(self):
-        with patch.object(_l, '_call_upstart_with_args') as call_upstart:
-            _get_click_app_status("app_id")
-            call_upstart.assert_called_with(
-                "status",
-                "application-click",
-                "APP_ID=app_id"
-            )
-
-    def test_get_click_app_pid(self):
-        with patch.object(_l.subprocess, 'check_output') as check_output:
-            check_output.return_value = """
-            application-click (com.autopilot.testing.test_app_id)
-            dummy/data\napplication-click (blah) dummy/data\napplication-click
-            (com.autopilot.testing.test_app_id) start/running, process 1234
-            """
-            self.assertThat(
-                _get_click_app_pid("test_app_id"),
-                Equals(1234)
-            )
-
-    def test_get_click_app_pid_raises_runtimeerror_with_no_status(self):
-        test_app_id = self.getUniqueString()
-        expected_error = "Could not find autopilot interface for click "\
-                         "package '%s' after 10 seconds." % test_app_id
-        with sleep.mocked():
-            with patch.object(_l, '_get_click_app_status', return_value=""):
-                self.assertThat(
-                    lambda: _get_click_app_pid(test_app_id),
-                    raises(RuntimeError(expected_error))
-                )
-
-    def test_get_click_app_pid_tries_10_times_and_raises(self):
-        test_app_name = self.getUniqueString()
-        expected_error = "Could not find autopilot interface for click "\
-                         "package '%s' after 10 seconds." % test_app_name
-        with sleep.mocked():
-            with patch.object(
-                    _l, '_get_click_app_status',
-                    side_effect=subprocess.CalledProcessError(1, "")
-            ):
-                self.assertThat(
-                    lambda: _get_click_app_pid(test_app_name),
-                    raises(RuntimeError(expected_error))
-                )
-                self.assertThat(
-                    sleep.total_time_slept(),
-                    Equals(10)
-                )
-
-    @patch('autopilot.application._launcher.subprocess.check_output')
-    def test_launch_click_app_starts_application(self, check_output):
-        test_app_name = self.getUniqueString()
-        with patch.object(
-            _l, '_get_click_app_pid'
-        ) as patched_get_click_app_pid:
-            _launch_click_app(test_app_name, "")
-
-            check_output.assert_called_with([
-                "/sbin/start",
-                "application",
-                "APP_ID=%s" % test_app_name,
-                "APP_URIS=''",
-            ])
-            patched_get_click_app_pid.assert_called_with(test_app_name)
-
-    @patch('autopilot.application._launcher.subprocess.check_output')
-    def test_launch_click_app_starts_application_with_uri(self, check_output):
-        test_app_name = self.getUniqueString()
-        test_app_uris = "%s %s" % (self.getUniqueString(),
-                                   self.getUniqueString())
-        with patch.object(
-            _l, '_get_click_app_pid'
-        ) as patched_get_click_app_pid:
-            _launch_click_app(test_app_name, test_app_uris)
-
-            check_output.assert_called_with([
-                "/sbin/start",
-                "application",
-                "APP_ID=%s" % test_app_name,
-                "APP_URIS='%s'" % test_app_uris,
-            ])
-            patched_get_click_app_pid.assert_called_with(test_app_name)
-
     def test_get_app_env_from_string_hint_returns_qt_env(self):
         self.assertThat(
             _get_app_env_from_string_hint('QT'),
@@ -517,27 +649,6 @@
                 ))
             )
 
-    @patch.object(_l, '_attempt_kill_pid')
-    def test_kill_pid_succeeds(self, patched_killpg):
-        with patch.object(
-            _l, '_is_process_running', return_value=False
-        ) as proc_running:
-            _kill_pid(0)
-            proc_running.assert_called_once_with(0)
-            patched_killpg.assert_called_once_with(0)
-
-    @patch.object(_l, '_attempt_kill_pid')
-    def test_kill_pid_retried(self, patched_killpid):
-        with sleep.mocked():
-            with patch.object(
-                _l, '_is_process_running', return_value=True
-            ) as proc_running:
-                _kill_pid(0)
-                proc_running.assert_called_with(0)
-                self.assertThat(proc_running.call_count, GreaterThan(1))
-                self.assertThat(patched_killpid.call_count, Equals(2))
-                patched_killpid.assert_called_with(0, signal.SIGKILL)
-
     @patch.object(_l.os, 'killpg')
     def test_attempt_kill_pid_logs_if_process_already_exited(self, killpg):
         killpg.side_effect = OSError()

=== modified file 'autopilot/tests/unit/test_introspection_features.py'
--- autopilot/tests/unit/test_introspection_features.py	2014-03-11 17:36:53 +0000
+++ autopilot/tests/unit/test_introspection_features.py	2014-03-20 12:37:25 +0000
@@ -27,6 +27,7 @@
 from testtools import TestCase
 from testtools.matchers import (
     Equals,
+    IsInstance,
     Not,
     NotEquals,
     Raises,
@@ -46,13 +47,18 @@
     _get_application_name_from_dbus_address,
     _get_search_criteria_string_representation,
     _maybe_filter_connections_by_app_name,
+    get_classname_from_path,
     get_proxy_object_for_existing_process,
     ProcessSearchError,
 )
 from autopilot.introspection.dbus import (
     _get_filter_string_for_key_value_pair,
+    _get_default_proxy_class,
     _is_valid_server_side_filter_param,
+    _get_proxy_object_class,
     _object_passes_filters,
+    _object_registry,
+    _try_custom_proxy_classes,
     CustomEmulatorBase,
     DBusIntrospectionObject,
 )
@@ -639,3 +645,194 @@
                     )
                 )
             )
+
+
+class MakeIntrospectionObjectTests(TestCase):
+
+    """Test selection of custom proxy object class."""
+
+    class DefaultSelector(CustomEmulatorBase):
+        pass
+
+    class AlwaysSelected(CustomEmulatorBase):
+        @classmethod
+        def validate_dbus_object(cls, path, state):
+            """Validate always.
+
+            :returns: True
+
+            """
+            return True
+
+    class NeverSelected(CustomEmulatorBase):
+        @classmethod
+        def validate_dbus_object(cls, path, state):
+            """Validate never.
+
+            :returns: False
+
+            """
+            return False
+
+    def test_class_has_validation_method(self):
+        """Verify that a class has a validation method by default."""
+        self.assertTrue(callable(self.DefaultSelector.validate_dbus_object))
+
+    @patch('autopilot.introspection.dbus._get_proxy_object_class')
+    def test_make_introspection_object(self, gpoc):
+        """Verify that make_introspection_object makes the right call."""
+        gpoc.return_value = self.DefaultSelector
+        fake_object = self.DefaultSelector(
+            dict(id=[0, 123], path=[0, '/some/path']),
+            '/',
+            Mock()
+        )
+        new_fake = fake_object.make_introspection_object(('/Object', {}))
+        self.assertThat(new_fake, IsInstance(self.DefaultSelector))
+        gpoc.assert_called_once_with(
+            _object_registry[fake_object._id],
+            self.DefaultSelector,
+            '/Object',
+            {}
+        )
+
+    @patch('autopilot.introspection.dbus._try_custom_proxy_classes')
+    @patch('autopilot.introspection.dbus._get_default_proxy_class')
+    def test_get_proxy_object_class_return_from_list(self, gdpc, tcpc):
+        """_get_proxy_object_class should return the value of
+        _try_custom_proxy_classes if there is one."""
+        token = self.getUniqueString()
+        tcpc.return_value = token
+        gpoc_return = _get_proxy_object_class(None, None, None, None)
+
+        self.assertThat(gpoc_return, Equals(token))
+        self.assertFalse(gdpc.called)
+
+    @patch('autopilot.introspection.dbus._try_custom_proxy_classes')
+    def test_get_proxy_object_class_send_right_args(self, tcpc):
+        """_get_proxy_object_class should send the right arguments to
+        _try_custom_proxy_classes."""
+        class_dict = {'DefaultSelector': self.DefaultSelector}
+        path = '/path/to/DefaultSelector'
+        state = {}
+        _get_proxy_object_class(class_dict, None, path, state)
+        tcpc.assert_called_once_with(class_dict, path, state)
+
+    @patch('autopilot.introspection.dbus._try_custom_proxy_classes')
+    def test_get_proxy_object_class_not_handle_error(self, tcpc):
+        """_get_proxy_object_class should not handle an exception raised by
+        _try_custom_proxy_classes."""
+        tcpc.side_effect = ValueError
+        self.assertThat(
+            lambda: _get_proxy_object_class(
+                None,
+                None,
+                None,
+                None
+            ),
+            raises(ValueError))
+
+    @patch('autopilot.introspection.dbus._try_custom_proxy_classes')
+    @patch('autopilot.introspection.dbus._get_default_proxy_class')
+    @patch('autopilot.introspection.dbus.get_classname_from_path')
+    def test_get_proxy_object_class_call_default_call(self, gcfp, gdpc, tcpc):
+        """_get_proxy_object_class should call _get_default_proxy_class if
+        _try_custom_proxy_classes returns None."""
+        tcpc.return_value = None
+        _get_proxy_object_class(None, None, None, None)
+        self.assertTrue(gdpc.called)
+
+    @patch('autopilot.introspection.dbus._try_custom_proxy_classes')
+    @patch('autopilot.introspection.dbus._get_default_proxy_class')
+    def test_get_proxy_object_class_default_args(self, gdpc, tcpc):
+        """_get_proxy_object_class should pass the correct arguments to
+        _get_default_proxy_class"""
+        tcpc.return_value = None
+        default = self.DefaultSelector
+        path = '/path/to/DefaultSelector'
+        _get_proxy_object_class(None, default, path, None)
+        gdpc.assert_called_once_with(default, get_classname_from_path(path))
+
+    @patch('autopilot.introspection.dbus._try_custom_proxy_classes')
+    @patch('autopilot.introspection.dbus._get_default_proxy_class')
+    @patch('autopilot.introspection.dbus.get_classname_from_path')
+    def test_get_proxy_object_class_default(self, gcfp, gdpc, tcpc):
+        """_get_proxy_object_class should return the value of
+        _get_default_proxy_class if _try_custom_proxy_classes returns None."""
+        token = self.getUniqueString()
+        gdpc.return_value = token
+        tcpc.return_value = None
+        gpoc_return = _get_proxy_object_class(None, None, None, None)
+        self.assertThat(gpoc_return, Equals(token))
+
+    def test_try_custom_proxy_classes_zero_results(self):
+        """_try_custom_proxy_classes must return None if no classes match."""
+        proxy_class_dict = {'NeverSelected': self.NeverSelected}
+        path = '/path/to/NeverSelected'
+        state = {}
+        class_type = _try_custom_proxy_classes(proxy_class_dict, path, state)
+        self.assertThat(class_type, Equals(None))
+
+    def test_try_custom_proxy_classes_one_result(self):
+        """_try_custom_proxy_classes must return the matching class if there is
+        exacly 1."""
+        proxy_class_dict = {'DefaultSelector': self.DefaultSelector}
+        path = '/path/to/DefaultSelector'
+        state = {}
+        class_type = _try_custom_proxy_classes(proxy_class_dict, path, state)
+        self.assertThat(class_type, Equals(self.DefaultSelector))
+
+    def test_try_custom_proxy_classes_two_results(self):
+        """_try_custom_proxy_classes must raise ValueError if multiple classes
+        match."""
+        proxy_class_dict = {'DefaultSelector': self.DefaultSelector,
+                            'AlwaysSelected': self.AlwaysSelected}
+        path = '/path/to/DefaultSelector'
+        state = {}
+        self.assertThat(
+            lambda: _try_custom_proxy_classes(
+                proxy_class_dict,
+                path,
+                state
+            ),
+            raises(ValueError)
+        )
+
+    @patch('autopilot.introspection.dbus.get_debug_logger')
+    def test_get_default_proxy_class_logging(self, gdl):
+        """_get_default_proxy_class should log a message."""
+        _get_default_proxy_class(self.DefaultSelector, None)
+        gdl.assert_called_once_with()
+
+    def test_get_default_proxy_class_base(self):
+        """Subclass must return an emulator of base class."""
+        class SubclassedProxy(self.DefaultSelector):
+            pass
+
+        result = _get_default_proxy_class(SubclassedProxy, 'Object')
+        self.assertTrue(result, Equals(self.DefaultSelector))
+
+    def test_get_default_proxy_class_base_instead_of_self(self):
+        """Subclass must not use self if base class works."""
+        class SubclassedProxy(self.DefaultSelector):
+            pass
+
+        result = _get_default_proxy_class(SubclassedProxy, 'Object')
+        self.assertFalse(issubclass(result, SubclassedProxy))
+
+    def test_get_default_proxy_class(self):
+        """Must default to own class if no usable bases present."""
+        result = _get_default_proxy_class(self.DefaultSelector, 'Object')
+        self.assertTrue(result, Equals(self.DefaultSelector))
+
+    def test_get_default_proxy_name(self):
+        """Must default to own class if no usable bases present."""
+        token = self.getUniqueString()
+        result = _get_default_proxy_class(self.DefaultSelector, token)
+        self.assertThat(result.__name__, Equals(token))
+
+    def test_validate_dbus_object_matches_on_class_name(self):
+        """Validate_dbus_object must match class name."""
+        selected = self.DefaultSelector.validate_dbus_object(
+            '/DefaultSelector', {})
+        self.assertTrue(selected)

=== modified file 'autopilot/tests/unit/test_test_fixtures.py'
--- autopilot/tests/unit/test_test_fixtures.py	2014-02-27 00:20:32 +0000
+++ autopilot/tests/unit/test_test_fixtures.py	2014-03-20 12:37:25 +0000
@@ -17,15 +17,19 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-from autopilot.tests.functional import TempDesktopFile
+from autopilot.tests.functional.fixtures import (
+    ExecutableScript,
+    TempDesktopFile,
+)
 
+import os
 import os.path
+import stat
 from mock import patch
 from shutil import rmtree
 import tempfile
 from testtools import TestCase
-from testtools.matchers import Equals, FileContains
-from textwrap import dedent
+from testtools.matchers import Contains, EndsWith, Equals, FileContains
 
 
 class TempDesktopFileTests(TestCase):
@@ -121,7 +125,7 @@
 
     def test_remove_desktop_file_removes_created_file_when_path_exists(self):
         test_created_path = self.getUniqueString()
-        with patch('autopilot.tests.functional.rmtree') as p_rmtree:
+        with patch('autopilot.tests.functional.fixtures.rmtree') as p_rmtree:
             TempDesktopFile._remove_desktop_file_components(
                 test_created_path, ""
             )
@@ -142,28 +146,70 @@
         with patch.object(
             TempDesktopFile, '_desktop_file_dir', return_value=desktop_file_dir
         ):
-            desktop_file = TempDesktopFile._create_desktop_file()
+            desktop_file = TempDesktopFile._create_desktop_file("")
             path, head = os.path.split(desktop_file)
             self.assertThat(path, Equals(desktop_file_dir))
 
     def test_create_desktop_file_writes_correct_data(self):
         desktop_file_dir = tempfile.mkdtemp(dir="/tmp")
         self.addCleanup(rmtree, desktop_file_dir)
+        token = self.getUniqueString()
 
         with patch.object(
             TempDesktopFile, '_desktop_file_dir', return_value=desktop_file_dir
         ):
-            desktop_file = TempDesktopFile._create_desktop_file()
+            desktop_file = TempDesktopFile._create_desktop_file(token)
             self.assertTrue(desktop_file.endswith('.desktop'))
-            self.assertThat(
-                desktop_file,
-                FileContains(
-                    dedent("""\
-                    [Desktop Entry]
-                    Type=Application
-                    Exec=Not important
-                    Path=Not important
-                    Name=Test app
-                    Icon=Not important""")
-                )
-            )
+            self.assertThat(desktop_file, FileContains(token))
+
+    def do_parameter_contents_test(self, matcher, **kwargs):
+        fixture = self.useFixture(TempDesktopFile(**kwargs))
+        self.assertThat(
+            fixture.get_desktop_file_path(),
+            FileContains(matcher=matcher),
+        )
+
+    def test_can_specify_exec_path(self):
+        token = self.getUniqueString()
+        self.do_parameter_contents_test(
+            Contains("Exec="+token),
+            exec_=token
+        )
+
+    def test_can_specify_type(self):
+        token = self.getUniqueString()
+        self.do_parameter_contents_test(
+            Contains("Type="+token),
+            type=token
+        )
+
+    def test_can_specify_name(self):
+        token = self.getUniqueString()
+        self.do_parameter_contents_test(
+            Contains("Name="+token),
+            name=token
+        )
+
+    def test_can_specify_icon(self):
+        token = self.getUniqueString()
+        self.do_parameter_contents_test(
+            Contains("Icon="+token),
+            icon=token
+        )
+
+
+class ExecutableScriptTests(TestCase):
+
+    def test_creates_file_with_content(self):
+        token = self.getUniqueString()
+        fixture = self.useFixture(ExecutableScript(script=token))
+        self.assertThat(fixture.path, FileContains(token))
+
+    def test_creates_file_with_correct_extension(self):
+        token = self.getUniqueString()
+        fixture = self.useFixture(ExecutableScript(script="", extension=token))
+        self.assertThat(fixture.path, EndsWith(token))
+
+    def test_creates_file_with_execute_bit_set(self):
+        fixture = self.useFixture(ExecutableScript(script=""))
+        self.assertTrue(os.stat(fixture.path).st_mode & stat.S_IXUSR)

=== modified file 'autopilot/utilities.py'
--- autopilot/utilities.py	2014-02-25 22:25:32 +0000
+++ autopilot/utilities.py	2014-03-20 12:37:25 +0000
@@ -63,6 +63,7 @@
 # Taken from http://ur1.ca/eqapv
 # licensed under the MIT license.
 class Silence(object):
+
     """Context manager which uses low-level file descriptors to suppress
     output to stdout/stderr, optionally redirecting to the named file(s).
 
@@ -72,6 +73,7 @@
             # do something that prints to stdout or stderr
 
     """
+
     def __init__(self, stdout=os.devnull, stderr=os.devnull, mode='wb'):
         self.outfiles = stdout, stderr
         self.combine = (stdout == stderr)
@@ -138,6 +140,7 @@
 
 
 class Timer(object):
+
     """A context-manager that times a block of code, writing the results to
     the log."""
 
@@ -158,6 +161,7 @@
 
 
 class StagnantStateDetector(object):
+
     """Detect when the state of something doesn't change over many iterations.
 
 
@@ -185,7 +189,7 @@
         :param threshold: Amount of times the updated state can fail to
           differ consecutively before raising an exception.
 
-        :raises: **ValueError** if *threshold* isn't a positive integer.
+        :raises ValueError: if *threshold* isn't a positive integer.
 
         """
         if type(threshold) is not int or threshold <= 0:
@@ -195,13 +199,13 @@
         self._previous_state_hash = -1
 
     def check_state(self, *state):
-        """Checks if there is a difference between the previous state and
+        """Check if there is a difference between the previous state and
         state.
 
         :param state: Hashable state argument to compare against the previous
           iteration
 
-        :raises: **TypeError** when state is unhashable
+        :raises TypeError: when state is unhashable
 
         """
         state_hash = hash(state)
@@ -218,7 +222,11 @@
 
 
 def get_debug_logger():
-    """Get a logging object to be used as a debug logger only."""
+    """Get a logging object to be used as a debug logger only.
+
+    :returns: logger object from logging module
+
+    """
     logger = logging.getLogger("autopilot.debug")
     logger.addFilter(DebugLogFilter())
     return logger
@@ -258,6 +266,7 @@
 
 
 class _CleanupWrapper(object):
+
     """Support for calling 'addCleanup' outside the test case."""
 
     def __init__(self):
@@ -285,7 +294,9 @@
 
 
 class _TestCleanupMeta(type):
-    """Metaclass to inject the object into on test start/end functionality"""
+
+    """Metaclass to inject the object into on test start/end functionality."""
+
     def __new__(cls, classname, bases, classdict):
         class EmptyStaticMethod(object):
             """Class used to give us 'default classmethods' for those that
@@ -346,6 +357,7 @@
 
 
 class MockableSleep(object):
+
     """Delay execution for a certain number of seconds.
 
     Functionally identical to `time.sleep`, except we can replace it during
@@ -365,6 +377,7 @@
             self.assertEqual(mock_sleep.total_time_slept(), 10.0)
 
     """
+
     def __init__(self):
         self._mock_count = 0.0
         self._mocked = False

=== modified file 'debian/control'
--- debian/control	2014-02-19 21:41:26 +0000
+++ debian/control	2014-03-20 12:37:25 +0000
@@ -9,6 +9,7 @@
                gir1.2-gconf-2.0,
                gir1.2-gtk-3.0,
                gir1.2-ibus-1.0,
+               gir1.2-upstart-app-launch-2,
                graphviz,
                liblttng-ust-dev,
                python-all-dev (>= 2.6),
@@ -56,6 +57,7 @@
 Architecture: all
 Depends: ${misc:Depends},
          ${python:Depends},
+         gir1.2-upstart-app-launch-2,
          python-contextlib2,
          python-dbus,
          python-decorator,
@@ -84,6 +86,7 @@
 Architecture: all
 Depends: ${misc:Depends},
          ${python3:Depends},
+         gir1.2-upstart-app-launch-2,
          python3-dbus,
          python3-decorator,
          python3-fixtures,