Merge lp:~thomir-deactivatedaccount/autopilot/trunk-object-ordering-docs into lp:autopilot

[Thomi Richards]

Add more documentation around object ordering.

Add more documentation around object ordering.

[Christopher Lee (veebers)]

Looks good to me.

review: Approve

[Leo Arias (elopio)]

Thank you!

review: Approve

[PS Jenkins bot (ps-jenkins)]

review: Approve (continuous-integration)

=== modified file 'autopilot/introspection/dbus.py'
--- autopilot/introspection/dbus.py	2013-11-05 22:24:38 +0000
+++ autopilot/introspection/dbus.py	2013-11-07 03:21:29 +0000
@@ -396,7 +396,11 @@
             # returns a list of QAction objects who appear below file_menu in
             # the object tree.
 
-        .. note:: The order in which objects are returned is not guaranteed.
+        .. warning::
+            The order in which objects are returned is not guaranteed. It is
+            bad practise to write tests that depend on the order in which
+            this method returns objects. (see :ref:`object_ordering` for more
+            information).
 
         If you only want to get one item, use :meth:`select_single` instead.
 

=== modified file 'docs/tutorial/good_tests.rst'
--- docs/tutorial/good_tests.rst	2013-05-28 00:52:21 +0000
+++ docs/tutorial/good_tests.rst	2013-11-07 03:21:29 +0000
@@ -504,3 +504,29 @@
  As a general rule, tests shouldn't have assert statements inside an if statement unless there's a very good reason for doing so.
 
 Scenarios can be useful, but we must be careful not to abuse them. It is far better to spend more time typing and end up with clear, readable tests than it is to end up with fewer, less readable tests. Like all code, tests are read far more often than they're written.
+
+.. _object_ordering:
+
+Do Not Depend on Object Ordering
+++++++++++++++++++++++++++++++++
+
+Calls such as :meth:`~autopilot.introspection.dbus.DBusIntrospectionObject.select_many` return several objects at once. These objects are explicitly unordered, and test authors must take care not to make assumptions about their order.
+
+**Bad Example:**
+
+.. code-block:: python
+
+    buttons = self.select_many('Button')
+    save_button = buttons[0]
+    print_button = buttons[1]
+
+This code may work initially, but there's absolutely no guarantee that the order of objects won't change in the future. A better approach is to select the individual components you need:
+
+**Good Example:**
+
+.. code-block:: python
+
+    save_button = self.select_single('Button', objectName='btnSave')
+    print_button = self.select_single('Button', objectName='btnPrint')
+
+This code will continue to work in the future.