Merge lp:~canonical-platform-qa/autopilot/updating-docs-and-argument-usage into lp:autopilot

[Christopher Lee]

Documentation (including porting and narrative) update for the new 1.6 CPO behaviour.

Documentation (including porting and narrative) update for the new 1.6 CPO behaviour.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:587
http://jenkins.qa.ubuntu.com/job/autopilot-ci/1090/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/21/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/20/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/21/console

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

review: Needs Fixing (continuous-integration)

[lp:~canonical-platform-qa/autopilot/updating-docs-and-argument-usage]

588. By Christopher Lee on 2015-06-23

Merge pre-req fixes

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:588
http://jenkins.qa.ubuntu.com/job/autopilot-ci/1094/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/25/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/24/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/25/console

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

review: Needs Fixing (continuous-integration)

[lp:~canonical-platform-qa/autopilot/updating-docs-and-argument-usage]

589. By Christopher Lee on 2015-06-23

Pyflakes fix.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:587
http://jenkins.qa.ubuntu.com/job/autopilot-ci/1097/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/28/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/27/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/28/console

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

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:589
http://jenkins.qa.ubuntu.com/job/autopilot-ci/1098/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/29
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/29/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/28
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/28/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/29
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/29/artifact/work/output/*zip*/output.zip
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-vivid-touch/3283
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-runner-vivid-mako/2740
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/3281
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/3281/artifact/work/output/*zip*/output.zip
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/21383

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

review: Approve (continuous-integration)

[lp:~canonical-platform-qa/autopilot/updating-docs-and-argument-usage]

590. By Christopher Lee on 2015-06-26

Merge pre-req. changes.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:590
http://jenkins.qa.ubuntu.com/job/autopilot-ci/1101/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/32
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/32/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/31
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/31/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/32
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/32/artifact/work/output/*zip*/output.zip
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-vivid-touch/3319
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-runner-vivid-mako/2775
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/3317
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/3317/artifact/work/output/*zip*/output.zip
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/21500

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

review: Approve (continuous-integration)

[Max Brustkern (nuclearbob)]

I have a few comments, but most of it looks good.

[lp:~canonical-platform-qa/autopilot/updating-docs-and-argument-usage]

591. By Christopher Lee on 2015-07-19

Merge pre-req. updates.

592. By Christopher Lee on 2015-07-21

Documentation improvement as per MP comments.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:592
http://jenkins.qa.ubuntu.com/job/autopilot-ci/1122/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/52
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-amd64-ci/52/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/51
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-armhf-ci/51/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/52
        deb: http://jenkins.qa.ubuntu.com/job/autopilot-wily-i386-ci/52/artifact/work/output/*zip*/output.zip
    FAILURE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-vivid-touch/3456/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-runner-vivid-mako/2880/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/3453
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-vivid-armhf/3453/artifact/work/output/*zip*/output.zip
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/22003

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

review: Approve (continuous-integration)

[platform-qa-bot (platform-qa-bot)]

PASSED: Continuous integration, rev:592
https://platform-qa-jenkins.ubuntu.com/job/autopilot-ci/4/
Executed test runs:
    None: https://platform-qa-jenkins.ubuntu.com/job/generic-update-mp/4/console

Click here to trigger a rebuild:
https://platform-qa-jenkins.ubuntu.com/job/autopilot-ci/4/rebuild

review: Approve (continuous-integration)

Unmerged revisions

592. By Christopher Lee on 2015-07-21

Documentation improvement as per MP comments.

591. By Christopher Lee on 2015-07-19

Merge pre-req. updates.

590. By Christopher Lee on 2015-06-26

Merge pre-req. changes.

589. By Christopher Lee on 2015-06-23

Pyflakes fix.

588. By Christopher Lee on 2015-06-23

Merge pre-req fixes

587. By Christopher Lee on 2015-06-23

Merge pre-req changes

586. By Christopher Lee on 2015-06-23

Cleanup of the porting doc.

585. By Christopher Lee on 2015-06-22

Cleanup use of sphinx generator use in code and tweak porting/tut details.

584. By Christopher Lee on 2015-06-22

Remove use of emulator_base incl. methods no longer relevant due to the removal of emulator_base

583. By Christopher Lee on 2015-06-22

Update usage (removal) of emulator_base

=== modified file 'autopilot/application/_launcher.py'
--- autopilot/application/_launcher.py	2014-07-22 02:30:19 +0000
+++ autopilot/application/_launcher.py	2015-07-21 03:40:37 +0000
@@ -53,16 +53,17 @@
     introspection enabled.
 
     :keyword case_addDetail: addDetail method to use.
-    :keyword proxy_base: custom proxy base class to use, defaults to None
+    :keyword proxy_class: custom proxy class to use when creating the proxy
+        object, defaults to None (and thus a generated default proxy).
     :keyword dbus_bus: dbus bus to use, if set to something other than the
-        default ('session') the environment will be patched
+        default ('session') the environment will be patched.
 
     """
 
-    def __init__(self, case_addDetail=None, emulator_base=None,
+    def __init__(self, case_addDetail=None, proxy_class=None,
                  dbus_bus='session'):
         super().__init__(case_addDetail)
-        self.proxy_base = emulator_base
+        self.proxy_class = proxy_class
         self.dbus_bus = dbus_bus
 
     def setUp(self):
@@ -142,7 +143,7 @@
         pid = self._get_pid_for_launched_app(app_id)
         proxy_object = get_proxy_object_for_existing_process(
             dbus_bus=self.dbus_bus,
-            emulator_base=self.proxy_base,
+            cpo_class=self.proxy_class,
             pid=pid
         )
         return proxy_object
@@ -379,7 +380,7 @@
             app_path, capture_output, launch_dir, arguments)
         proxy_object = get_proxy_object_for_existing_process(
             dbus_bus=self.dbus_bus,
-            emulator_base=self.proxy_base,
+            cpo_class=self.proxy_class,
             process=process,
             pid=process.pid
         )

=== modified file 'autopilot/introspection/_search.py'
--- autopilot/introspection/_search.py	2015-07-21 03:40:37 +0000
+++ autopilot/introspection/_search.py	2015-07-21 03:40:37 +0000
@@ -32,7 +32,6 @@
 from autopilot.exceptions import ProcessSearchError
 from autopilot.introspection import backends
 from autopilot.introspection import constants
-from autopilot.introspection import dbus as ap_dbus
 from autopilot.introspection import _proxy_objects as _po
 from autopilot.introspection._xpathselect import get_classname_from_path
 from autopilot.introspection.backends import WireProtocolVersionMismatch
@@ -52,21 +51,7 @@
     emulator_base,
     dbus_bus='session'
 ):
-    """Return the autopilot proxy object for the given *process*.
-
-    :raises RuntimeError: if no autopilot interface was found.
-
-    """
-    pid = process.pid
-    proxy_obj = get_proxy_object_for_existing_process(
-        pid,
-        process=process,
-        emulator_base=emulator_base,
-        dbus_bus=dbus_bus,
-    )
-    proxy_obj.set_process(process)
-
-    return proxy_obj
+    raise NotImplementedError('This method is no longer available.')
 
 
 def get_proxy_object_for_existing_process(**kwargs):
@@ -77,11 +62,12 @@
     application matching the search criteria (also supplied in kwargs, see
     further down for explaination on what these can be.)
     Returns a proxy object created using the supplied custom proxy object class
-    **cpo_class** (which defaults to None).
+    **cpo_class** (which defaults to None and thus returns a generated default
+      proxy).
 
-    Note: for backwards compatibility this method will continue to accept
-      emulator_base instead of cpo_class. Currently will issue a warning, in
-      the future this will potentially be an error.
+    .. note:: Prior to 1.6 emulator_base used to be a valid argument. Due to
+      the changes in how CPOs are used and created (i.e. no more object
+      registry) this argument is no longer supported.
 
     This function take kwargs arguments containing search parameter values to
     use when searching for the target application.
@@ -111,7 +97,7 @@
         Defaults to 'session'
     :param cpo_class: The custom proxy object class to use when creating the
         resulting proxy object.
-        Defaults to None resulting in a generated default object.
+        Defaults to None resulting in a generated default proxy object.
 
     **Exceptions possibly thrown by this function:**
 
@@ -159,15 +145,12 @@
     dbus_bus = _get_dbus_bus_from_string(kwargs.pop('dbus_bus', 'session'))
     process = kwargs.pop('process', None)
     cpo_class = kwargs.pop('cpo_class', None)
-    emulator_base = kwargs.pop('emulator_base', None)
-    if emulator_base is not None:
-        logger.warning(
-            'The use of emulator_base is deprecated. Please use '
-            'cpo_class instead.'
+    if kwargs.pop('emulator_base', None) is not None:
+        logger.error(
+            'The use of emulator_base is deprecated as of version 1.6. '
+            'Perhaps cpo_class is what you want instead.'
         )
 
-    cpo_class = cpo_class if cpo_class else emulator_base
-
     # Force default object_path
     kwargs['object_path'] = kwargs.get('object_path', constants.AUTOPILOT_PATH)
     # Special handling of pid.
@@ -448,7 +431,7 @@
 
 
 def _make_proxy_object_async(
-        data_source, emulator_base, reply_handler, error_handler):
+        data_source, proxy_class, reply_handler, error_handler):
     """Make a proxy object for a dbus backend.
 
     Similar to :meth:`_make_proxy_object` except this method runs
@@ -471,20 +454,20 @@
             introspection_xml
         )
 
-        cpo_base = _po._get_applicable_class_name(emulator_base, path)
+        cpo_base = _po._get_applicable_class_name(proxy_class, path)
 
         if not _po._is_cpo_class(cpo_base):
-            proxy_class = _po._get_default_proxy_class(
+            actual_proxy_class = _po._get_default_proxy_class(
                 cpo_base,
                 extension_classes
             )
         else:
             # It's actually a CPO class.
             _po._apply_mixin_bases(cpo_base, extension_classes)
-            proxy_class = cpo_base
+            actual_proxy_class = cpo_base
 
         reply_handler(
-            proxy_class(cls_state, path, backends.Backend(data_source))
+            actual_proxy_class(cls_state, path, backends.Backend(data_source))
         )
 
     # Phase 2: We recieve the introspection string, and make an asynchronous
@@ -538,16 +521,6 @@
         subprocess.call(["kill", "%d" % self._process.pid])
 
 
-def _extend_proxy_bases_with_emulator_base(proxy_bases, emulator_base):
-    if emulator_base is None:
-        emulator_base = type(
-            'DefaultEmulatorBase',
-            (ap_dbus.CustomEmulatorBase,),
-            {}
-        )
-    return proxy_bases + (emulator_base, )
-
-
 def _get_dbus_address_object(connection_name, object_path, bus):
     return backends.DBusAddress(bus, connection_name, object_path)
 

=== modified file 'autopilot/introspection/dbus.py'
--- autopilot/introspection/dbus.py	2015-07-21 03:40:37 +0000
+++ autopilot/introspection/dbus.py	2015-07-21 03:40:37 +0000
@@ -180,8 +180,8 @@
         necessarily be immediate children), use :meth:`select_single` and
         :meth:`select_many`.
 
-        Note. Any proxy objects return from this call will be generated
-        defaults and will not use any Custom Proxy Object classes.
+        .. note:: Any proxy objects return from this call will be generated
+          defaults and will not use any Custom Proxy Object classes.
 
         """
         # Thomi: 2014-03-20: There used to be a call to 'self.refresh_state()'
@@ -196,8 +196,8 @@
         If this object has no parent (i.e.- it is the root of the introspection
         tree). Then it returns itself.
 
-        Note. Any proxy object return from this call will be generated defaults
-        and will not use any Custom Proxy Object classes.
+        .. note:: Any proxy object return from this call will be generated
+          defaults and will not use any Custom Proxy Object classes.
 
         """
         new_query = self._query.select_parent()
@@ -573,10 +573,10 @@
 
         You can then define a Custom Proxy Object  for this type like so::
 
-        class RedRect(DBusIntrospectionObject):
-            @classmethod
-            def get_type_query_name(cls):
-                return 'QQuickRectangle'
+            class RedRect(DBusIntrospectionObject):
+                @classmethod
+                def get_type_query_name(cls):
+                    return 'QQuickRectangle'
 
         This is due to the qml engine storing 'RedRect' as a QQuickRectangle in
         the UI tree and the xpathquery query needs a node type to query for.
@@ -597,12 +597,12 @@
         For instance a query can return a default generated proxy object and
         then use this method to create a specific CPO from it.
 
-        Note::
-            There is no validation done on the acceptability of the passed
-            proxy object to be instantiated as the calling class.
-            (e.g. validate_dbus_object is not involved.)
-            It is up to the caller to ensure that the passed proxy object is
-            suitable.
+        .. note:: There is no validation done on the acceptability of the
+          passed proxy object to be instantiated as the calling class.
+          (e.g. validate_dbus_object is not involved.)
+          It is up to the caller to ensure that the passed proxy object is
+          suitable or that any potential exceptions raised in the custom
+          methods are caught accordingly.
 
         """
         _, state_dict = proxy_object._get_new_state()

=== modified file 'autopilot/testcase.py'
--- autopilot/testcase.py	2015-07-15 23:31:12 +0000
+++ autopilot/testcase.py	2015-07-21 03:40:37 +0000
@@ -267,8 +267,13 @@
         :keyword capture_output: If set to True (the default), the process
             output will be captured and attached to the test as test detail.
 
-        :keyword emulator_base: If set, specifies the base class to be used for
-            all emulators for this loaded application.
+        Note. prior to 1.6 'emulator_base' used to be a valid argument. This is
+        no longer the case as proxy classes work differently now. Proxy classes
+        are created explicitly using the provided ``proxy_class``. If no class
+        is passed than a generated default is used (a very basic proxy object).
+
+        :keyword proxy_class: If set, specifies the custom proxy class to be
+            created and returned for this application.
 
         :return: A proxy object that represents the application. Introspection
          data is retrievable via this object.
@@ -307,8 +312,13 @@
         :param app_uris: Parameters used to launch the click package. This
             parameter will be left empty if not used.
 
-        :keyword emulator_base: If set, specifies the base class to be used for
-            all emulators for this loaded application.
+        Note. prior to 1.6 'emulator_base' used to be a valid argument. This is
+        no longer the case as proxy classes work differently now. Proxy classes
+        are created explicitly using the provided ``proxy_class``. If no class
+        is passed than a generated default is used (a very basic proxy object).
+
+        :keyword proxy_class: If set, specifies the custom proxy class to be
+            created and returned for this application.
 
         :raises RuntimeError: If the specified package_id cannot be found in
             the click package manifest.
@@ -338,8 +348,14 @@
             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.
+
+        Note. prior to 1.6 'emulator_base' used to be a valid argument. This is
+        no longer the case as proxy classes work differently now. Proxy classes
+        are created explicitly using the provided ``proxy_class``. If no class
+        is passed than a generated default is used (a very basic proxy object).
+
+        :keyword proxy_class: If set, specifies the custom proxy class to be
+            created and returned for this application.
 
         :raises RuntimeError: If the specified application cannot be launched.
         """

=== modified file 'autopilot/tests/functional/test_introspection_features.py'
--- autopilot/tests/functional/test_introspection_features.py	2015-07-21 03:40:37 +0000
+++ autopilot/tests/functional/test_introspection_features.py	2015-07-21 03:40:37 +0000
@@ -60,7 +60,7 @@
 class IntrospectionFeatureTests(AutopilotTestCase):
     """Test various features of the introspection code."""
 
-    def start_mock_app(self, emulator_base):
+    def start_mock_app(self, proxy_class):
         window_spec_file = mktemp(suffix='.json')
         window_spec = {"Contents": "MouseTest"}
         json.dump(
@@ -73,7 +73,7 @@
             'window-mocker',
             window_spec_file,
             app_type='qt',
-            emulator_base=emulator_base,
+            proxy_class=proxy_class,
         )
 
     def test_can_get_custom_proxy_for_app_root(self):
@@ -366,8 +366,8 @@
                 return self.launch_test_application(
                     "/usr/lib/" + arch + "/qt5/bin/qmlscene",
                     qml_path,
-                    extra_args,
-                    emulator_base=EmulatorBase)
+                    extra_args
+                )
 
             def test_custom_emulator(self):
                 app = self.launch_test_qml()

=== modified file 'autopilot/tests/unit/test_application_launcher.py'
--- autopilot/tests/unit/test_application_launcher.py	2014-07-22 02:30:19 +0000
+++ autopilot/tests/unit/test_application_launcher.py	2015-07-21 03:40:37 +0000
@@ -74,21 +74,21 @@
     def test_init_uses_default_values(self):
         launcher = ApplicationLauncher()
         self.assertEqual(launcher.caseAddDetail, launcher.addDetail)
-        self.assertEqual(launcher.proxy_base, None)
+        self.assertEqual(launcher.proxy_class, None)
         self.assertEqual(launcher.dbus_bus, 'session')
 
     def test_init_uses_passed_values(self):
         case_addDetail = self.getUniqueString()
-        emulator_base = self.getUniqueString()
+        proxy_class = self.getUniqueString()
         dbus_bus = self.getUniqueString()
 
         launcher = ApplicationLauncher(
             case_addDetail=case_addDetail,
-            emulator_base=emulator_base,
+            proxy_class=proxy_class,
             dbus_bus=dbus_bus,
         )
         self.assertEqual(launcher.caseAddDetail, case_addDetail)
-        self.assertEqual(launcher.proxy_base, emulator_base)
+        self.assertEqual(launcher.proxy_class, proxy_class)
         self.assertEqual(launcher.dbus_bus, dbus_bus)
 
     @patch('autopilot.application._launcher.fixtures.EnvironmentVariable')
@@ -203,7 +203,7 @@
                 launcher.launch('')
                 gpofep.assert_called_once_with(process=lap.return_value,
                                                pid=lap.return_value.pid,
-                                               emulator_base=None,
+                                               cpo_class=None,
                                                dbus_bus='session')
 
     @patch('autopilot.application._launcher.'
@@ -688,7 +688,7 @@
                 with patch.object(launcher, '_get_glib_loop'):
                     launcher.launch('')
                     gpofep.assert_called_once_with(pid=gp.return_value,
-                                                   emulator_base=None,
+                                                   cpo_class=None,
                                                    dbus_bus='session')
 
     @patch('autopilot.application._launcher.'

=== modified file 'autopilot/tests/unit/test_introspection.py'
--- autopilot/tests/unit/test_introspection.py	2015-07-21 03:40:37 +0000
+++ autopilot/tests/unit/test_introspection.py	2015-07-21 03:40:37 +0000
@@ -18,19 +18,14 @@
 #
 
 from dbus import String
-from unittest.mock import Mock
 from testtools import TestCase
 from testtools.matchers import (
     Equals,
     IsInstance,
     raises,
 )
-from autopilot.introspection import (
-    _proxy_objects as _po,
-    _search as _s
-)
+from autopilot.introspection import _proxy_objects as _po
 from autopilot.introspection.qt import QtObjectProxyMixin
-import autopilot.introspection as _i
 
 
 class GetDetailsFromStateDataTests(TestCase):
@@ -141,24 +136,3 @@
             ),
             Equals((QtObjectProxyMixin,))
         )
-
-
-class ExtendProxyBasesWithEmulatorBaseTests(TestCase):
-
-    def test_default_emulator_base_name(self):
-        bases = _s._extend_proxy_bases_with_emulator_base(tuple(), None)
-        self.assertThat(len(bases), Equals(1))
-        self.assertThat(bases[0].__name__, Equals("DefaultEmulatorBase"))
-        self.assertThat(bases[0].__bases__[0], Equals(_i.CustomEmulatorBase))
-
-    def test_appends_custom_emulator_base(self):
-        existing_bases = ('token',)
-        custom_emulator_base = Mock()
-        new_bases = _s._extend_proxy_bases_with_emulator_base(
-            existing_bases,
-            custom_emulator_base
-        )
-        self.assertThat(
-            new_bases,
-            Equals(existing_bases + (custom_emulator_base,))
-        )

=== modified file 'docs/porting/porting.rst'
--- docs/porting/porting.rst	2015-01-22 16:35:48 +0000
+++ docs/porting/porting.rst	2015-07-21 03:40:37 +0000
@@ -14,6 +14,101 @@
 
 Autopilot versions earlier than 1.2 were not publicly announced, and were only used within Canonical. For that reason, this document assumes that version 1.2 is the lowest version of autopilot present `"in the wild"`.
 
+Porting to Autopilot v1.6.x
+===========================
+
+The 1.6 release contains a number of modifications that change the behaviour of
+:ref:`custom_proxy_classes` Custom Proxy Objects and how they are applied to
+results from the query methods (select_single, get_children etc. see
+:class:`~autopilot.introspection.ProxyBase` for further query method details).
+
+Custom Proxy Objects and Class
+++++++++++++++++++++++++++++++
+
+In the past there was a private registry of CPO classes that was queried and an
+object instantiated from a class that existed there when creating a proxy
+object. The problem with this approach is that it relied on the python import
+mechanism to trigger when this registry was populated. This caused issues where
+the contents of the registry weren't deterministic and running a test in a
+different order could result in a different CPO class being used to create a
+proxy object (causing a test failure.)
+
+Now the use and creation of proxy objects using a Custom Proxy Object class is
+explicit. The CPO that you pass into the query method is the object that you
+get back (assuming the query succeeded). Passing a string (the default is '*')
+will result in a generated default which is an instantiated object of
+:class:`~autopilot.introspection.ProxyBase`.
+
+Default proxy objects
++++++++++++++++++++++
+
+In previous versions an application was launched with an ``emulator_base``
+which ensured that any proxy objects created without a specific CPO were
+created with at least the ``emulator_base`` as a base class. This is no longer
+the case and and 'generated default' proxys created are created from
+:class:`~autopilot.introspection.ProxyBase`.
+
+So if you :meth:`~autopilot.introspection.ProxyBase.select_single`
+passing no type name or CPO (i.e. defaulting to '*') then you will get back a
+default generated proxy object with no extra methods, only those defined in
+:class:`~autopilot.introspection.ProxyBase`.
+
+It's the same if you select by passing a type name string into the method, even
+if you have defined a CPO of the same name and it is imported in this file, you
+will only get back a generated default (there is no more black magic, it's
+always explicit. It's either the CPO that is passed in or a generated default).
+
+Creating instances of Custom Proxy Classes
+++++++++++++++++++++++++++++++++++++++++++
+
+If you need to get an instantiated CPO you need to either pass the class to the
+select method::
+
+    # This will return an object of MyCPOClass
+    app.select_single(MyCPOClass, objectName='example')
+
+or you can create an object using the static/class method
+:meth:`~autopilot.introspection.ProxyBase.from_proxy_object`::
+
+    # proxy will be a default generated proxy (e.g. no special methods) whereas
+    # cpo_proxy is an instance of MyCPOClass.
+    proxy = app.select_single(objectName='example')
+    cpo_proxy = MyCPOClass.from_proxy_object(proxy)
+
+Please see :meth:`~autopilot.introspection.ProxyBase.from_proxy_object` for
+further details.
+
+Removal of emulator_base
+++++++++++++++++++++++++
+
+There is no longer a need to define your own base class to start using CPOs.
+When launching an application the ``emulator_base`` argument is no longer
+required or used (using it will log an error message). If you have a custom
+class you would like to use for the application proxy use ``proxy_class`` to
+instantiate a proxy object using that.
+
+Also note that because there is no longer an emulator_base or object
+registry. This means that the generated default proxy objects will not inherit
+from anything that you the author have defined, they will be just
+:class:`~autopilot.introspection.ProxyBase`.
+
+Clarification of generated vs. custom proxy in logs
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+In the past it was possible that a test would fail due to an incorrect CPO
+being loaded into the registry and used. Even though there is no more registry
+there has been logging added to help determine if a helper is returning/using a
+generic or custom proxy.
+
+Check the logs for error messages, for attribute errors you will see either::
+
+  'Generated Class <class> does not have attribute: . . .'
+
+if it is a generated default class, For custom proxy classes you will see::
+
+  'Class <class> does not have attribute: . . .'
+
+
 Porting to Autopilot v1.4.x
 ===========================
 

=== modified file 'docs/tutorial/advanced_autopilot.rst'
--- docs/tutorial/advanced_autopilot.rst	2015-05-07 21:46:35 +0000
+++ docs/tutorial/advanced_autopilot.rst	2015-07-21 03:40:37 +0000
@@ -521,22 +521,36 @@
 
 However, sometimes you want to customize the class used to create these objects. The most common reason to want to do this is to provide methods that make it easier to inspect or interact with these objects. Autopilot allows test authors to provide their own custom classes, through a couple of simple steps:
 
-1. First, you must define your own base class, to be used by all custom proxy objects in your test suite. This base class can be empty, but must derive from :class:`~autopilot.introspection.ProxyBase`. An example class might look like this::
-
-    from autopilot.introspection import ProxyBase
-
-
-    class CustomProxyObjectBase(ProxyBase):
-        """A base class for all custom proxy objects within this test suite."""
-
+.. note:: Prior to autopilot version 1.6 you were required to define your own
+          base class that would be the basis of all your subsequent custom
+          proxy classes, this is no longer needed.
+
+.. note:: The previous behaviour was that an application was launched with an
+          'emulator_base' (i.e. your own base class) that was applied to any
+          non-custom proxy objects created. This is no longer the case. The use
+          of emualtor_base has been removed and all non-custom proxys returned
+          are generic.
+
+
+1. You must define your class that derives from :class:`~autopilot.introspection.ProxyBase`.
 For Ubuntu applications using Ubuntu UI Toolkit objects, you should derive your custom proxy object from UbuntuUIToolkitCustomProxyObjectBase. This base class is also derived from :class:`~autopilot.introspection.ProxyBase` and is used for all Ubuntu UI Toolkit custom proxy objects. So if you are introspecting objects from Ubuntu UI Toolkit then this is the base class to use.
 
-2. Define the classes you want autopilot to use, instead of the default. The simplest method is to give the class the same name as the type you wish to override. For example, if you want to define your own custom class to be used every time autopilot generates an instance of a 'QLabel' object, the class definition would look like this::
-
-    class QLabel(CustomProxyObjectBase):
+.. note:: The Ubuntu UI Toolkit provides a large number of very useful custom proxy classes and helpers for the toolkit. It is recommended that you check there to see if there is a CPO suitable for your needs before writing your own.
+
+2. Define the classes you want autopilot to use, instead of the default. The simplest method is to give the class the same name as the type you wish to override. For example, if you want to define your own custom class to be used when selecting an instance of a 'QLabel' object, the class definition would look like this::
+
+    class QLabel(ProxyBase):
 
         # Add custom methods here...
 
+As of version 1.6 it is possible to name your custom class something different to the underlying type name. To do this you need to override the get_type_query_name method to return a string to use in the generated query.  For example this is a class that backs onto a QLabel type::
+
+    class MyCoolLabel(ProxyBase):
+        def get_type_query_name():
+            # This will result in a query looking for QLabels but create a
+            # MyCoolLabel object.
+            return 'QLabel'
+
 If you wish to implement more specific selection criteria, your class can override the validate_dbus_object method, which takes as arguments the dbus path and state.  For example::
 
     class SpecificQLabel(CustomProxyObjectBase):
@@ -545,7 +559,7 @@
             return (path.endswith('object_we_want') or
                     state['some_property'] == 'desired_value')
 
-This method should return True if the object matches this custom proxy class, and False otherwise.  If more than one custom proxy class matches an object, a :exc:`ValueError` will be raised at runtime.
+This method should return True if the object matches this custom proxy class, and False otherwise.
 
 An example using Ubuntu UI Toolkit which would be used to swipe up a PageWithBottomEdge object to reveal it's bottom edge menu could look like this::
 
@@ -559,29 +573,12 @@
             """Swipe up from the bottom edge of the Page
                to reveal it's bottom edge menu."""
 
-3. Pass the custom proxy base class as an argument to the launch_test_application method on your test class. This base class should be the same base class that is used to write all of your custom proxy objects::
-
-    from autopilot.testcase import AutopilotTestCase
-
-    class TestCase(AutopilotTestCase):
-
-        def setUp(self):
-            super().setUp()
-            self.app = self.launch_test_application(
-                '/path/to/the/application',
-                emulator_base=CustomProxyObjectBase)
-
-For applications using objects from Ubuntu UI Toolkit, the emulator_base parameter should be::
-
-    emulator_base=ubuntuuitoolkit.UbuntuUIToolkitCustomProxyObjectBase
-
-
-4. You can pass the custom proxy class to methods like :meth:`~autopilot.introspection.ProxyBase.select_single` instead of a string. So, for example, the following is a valid way of selecting the QLabel instances in an application::
+3. You can pass the custom proxy class to methods like :meth:`~autopilot.introspection.ProxyBase.select_single` instead of a string. So, for example, the following is a valid way of selecting the QLabel instances in an application::
 
     # Get all QLabels in the applicaton:
     labels = self.app.select_many(QLabel)
 
-If you are introspecting an application that already has a custom proxy base class defined, then this class can simply be imported and passed to the appropriate application launcher method. See :ref:`launching applications <launching_applications>` for more details on launching an application for introspection. This will allow you to call all of the public methods of the application's proxy base class directly in your test.
+When launching an application you can pass ``proxy_class`` to create an instance of that custom proxy object for the launched application.
 
 This example will run on desktop and uses the webbrowser application to navigate to a url using the base class go_to_url() method::
 
@@ -593,7 +590,7 @@
         def test_go_to_url(self):
             app = self.launch_test_application(
                 'webbrowser-app',
-                emulator_base=browser.Webbrowser)
+                cpo_class=browser.Webbrowser)
             # main_window is a property of the Webbrowser class
             app.main_window.go_to_url('http://www.ubuntu.com')
 
@@ -641,12 +638,12 @@
         launcher = self.useFixture(ClickApplicationLauncher())
         app_proxy = launcher.launch('com.ubuntu.calculator')
 
-Additional options can also be specified to set a custom addDetail method, a custom proxy base, or a custom dbus bus with which to patch the environment::
+Additional options can also be specified to set a custom addDetail method, use a custom proxy class, or a custom dbus bus with which to patch the environment::
 
         launcher = self.useFixture(NormalApplicationLauncher(
             case_addDetail=self.addDetail,
             dbus_bus='some_other_bus',
-            proxy_base=my_proxy_class,
+            proxy_class=my_proxy_class,
         ))
 
 .. note:: You must pass the test case's 'addDetail' method to these application launch fixtures if you want application logs to be attached to the test result. This is due to the way fixtures are cleaned up, and is unavoidable.