Merge lp:~pitti/autopilot/print-tree into lp:autopilot

[Martin Pitt]

Add print_tree() introspection method for writing a textual representation of the object and all of its children to stdout, a file object, or a file name.

When writing autopilot tests, finding the type and exact properties of the
exact widget that I'm seeing somewhere on the screen is one of the biggest
challenges. Many widgets can get an explicit identifier (objectName in QML or
GtkBuilder ID in Gtk), but often this doesn't help: For example the actually
visible labels in a QML list view are hidden many layers benath some
unintelligible nested QtQuickItem, HandlerDelegate, and other bits, which makes
finding anything in vis hard.

This adds a print_tree() method which gives a textual dump to stdout, a file
object, or a file name which is much easier to use in above cases, or where vis
is not available (ssh to phone). It supports depth-limiting, too.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:354
http://jenkins.qa.ubuntu.com/job/autopilot-ci/270/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/198/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/198/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-i386-ci/42/console

Click here to trigger a rebuild:
http://10.97.0.26:8080/job/autopilot-ci/270/rebuild

review: Needs Fixing (continuous-integration)

[lp:~pitti/autopilot/print-tree]

355. By Martin Pitt on 2013-10-22

fix docstring format

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:355
http://jenkins.qa.ubuntu.com/job/autopilot-ci/271/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/199/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/199/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-i386-ci/43/console

Click here to trigger a rebuild:
http://10.97.0.26:8080/job/autopilot-ci/271/rebuild

review: Needs Fixing (continuous-integration)

[Martin Pitt (pitti)]

Erk, why don't I get these pep8 errors in a local build and when running "pep8 ."? Fixing..

[lp:~pitti/autopilot/print-tree]

356. By Martin Pitt on 2013-10-22

Fix PEP-8

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:356
http://jenkins.qa.ubuntu.com/job/autopilot-ci/272/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/200
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/200
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-i386-ci/44

Click here to trigger a rebuild:
http://10.97.0.26:8080/job/autopilot-ci/272/rebuild

review: Approve (continuous-integration)

[Thomi Richards (thomir-deactivatedaccount)]

Hi,

Nice branch! I have a few suggestions though:

1)

16 + def print_tree(self, output=None, maxdepth=None, _curdepth=0):

Instead of making the default value for 'output' be 'None', why not make it 'sys.stdout' ? That way, you can delete this:

39 + if output is None:
40 + output = sys.stdout

And the docs should say that output should be a "file-like object that supports the 'write' method. That way you can delete these lines as well:

41 + elif isinstance(output, six.string_types):
42 + output = open(output, 'w')

I'm not sure that using four spaces as an indentation is a good idea - trees can get pretty large... have you tried this one a bug tree like Unity 7? Perhaps 2 spaces would be better? I'm really not sure either way - but I 'd like to see some larger output....

review: Needs Fixing

[lp:~pitti/autopilot/print-tree]

357. By Martin Pitt on 2013-10-25

reduce indentation to 2 characters

[Martin Pitt (pitti)]

> 1)
>
> 16 + def print_tree(self, output=None, maxdepth=None, _curdepth=0):
>
> Instead of making the default value for 'output' be 'None', why not make it
> 'sys.stdout' ? That way, you can delete this:
>
> 39 + if output is None:
> 40 + output = sys.stdout

Python has a rather unintuitive semantics when trying to provide non-trivial values as default argument values (First time I ran into that I actually understood it, and just avoid it ever since). In this case as well, if you actually do the change you'll notice that the tests will fail and you'll get the test tree literally dumped to stdout during the tests (although it's supposed to go into a StringIO).

> And the docs should say that output should be a "file-like object that
> supports the 'write' method. That way you can delete these lines as well:
>
> 41 + elif isinstance(output, six.string_types):
> 42 + output = open(output, 'w')

This is a debugging-only function, so it ought to be as convenient as possible. Thus I would also like to support

  mywidget.print_tree("/tmp/dump.txt")

instead of requiring the user to write something like

  with open("/tmp/dump.txt", "w") as f:
     mywidget.print_tree(f)

> I'm not sure that using four spaces as an indentation is a good idea - trees
> can get pretty large... have you tried this one a bug tree like Unity 7?

I didn't, but I suppose it would take half an hour to do that :-) It already takes several seconds for relatively small trees.

> Perhaps 2 spaces would be better? I'm really not sure either way - but I 'd
> like to see some larger output....

Yes, good point. I reduced it.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:357
http://jenkins.qa.ubuntu.com/job/autopilot-ci/277/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-amd64-ci/3/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-armhf-ci/3/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-i386-ci/3/console

Click here to trigger a rebuild:
http://10.97.0.26:8080/job/autopilot-ci/277/rebuild

review: Needs Fixing (continuous-integration)

[Martin Pitt (pitti)]

I seeded trusty in the autopilot PPA, should work now.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:357
http://jenkins.qa.ubuntu.com/job/autopilot-ci/278/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-amd64-ci/4
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-armhf-ci/4
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-trusty-i386-ci/4

Click here to trigger a rebuild:
http://10.97.0.26:8080/job/autopilot-ci/278/rebuild

review: Approve (continuous-integration)

[Thomi Richards (thomir-deactivatedaccount)]

LGTM

review: Approve

=== modified file 'autopilot/introspection/dbus.py'
--- autopilot/introspection/dbus.py	2013-10-13 21:49:49 +0000
+++ autopilot/introspection/dbus.py	2013-10-25 05:07:27 +0000
@@ -28,6 +28,7 @@
 from __future__ import absolute_import
 
 from contextlib import contextmanager
+import sys
 import logging
 import re
 import six
@@ -583,6 +584,46 @@
             class_type = type(str(name), (base_class,), {})
         return class_type(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.
+
+        When writing new tests, this can be called when it is too difficult to
+        find the widget or property that you are interested in in "vis".
+
+        .. warning:: Do not use this in production tests, this is expensive and
+            not at all appropriate for actual testing. Only call this
+            temporarily and replace with proper select_single/select_many
+            calls.
+
+        :param output: A file object or path name where the output will be
+            written to. If not given, write to stdout.
+
+        :param maxdepth: If given, limit the maximum recursion level to that
+            number, i. e. only print children which have at most maxdepth-1
+            intermediate parents.
+
+        """
+        if maxdepth is not None and _curdepth > maxdepth:
+            return
+
+        indent = "  " * _curdepth
+        if output is None:
+            output = sys.stdout
+        elif isinstance(output, six.string_types):
+            output = open(output, 'w')
+
+        # print path
+        if _curdepth > 0:
+            output.write("\n")
+        output.write("%s== %s ==\n" % (indent, self._path))
+        # print properties
+        for p in sorted(self.get_properties()):
+            output.write("%s%s: %s\n" % (indent, p, repr(getattr(self, p))))
+        # print children
+        if maxdepth is None or _curdepth < maxdepth:
+            for c in self.get_children():
+                c.print_tree(output, maxdepth, _curdepth + 1)
+
     @contextmanager
     def no_automatic_refreshing(self):
         """Context manager function to disable automatic DBus refreshing when

=== modified file 'autopilot/tests/functional/test_introspection_features.py'
--- autopilot/tests/functional/test_introspection_features.py	2013-09-29 22:45:15 +0000
+++ autopilot/tests/functional/test_introspection_features.py	2013-10-25 05:07:27 +0000
@@ -24,8 +24,9 @@
 import subprocess
 import tempfile
 from tempfile import mktemp
-from testtools.matchers import Equals, IsInstance, Not
+from testtools.matchers import Equals, IsInstance, Not, Contains
 from textwrap import dedent
+from six import StringIO
 
 from autopilot.matchers import Eventually
 from autopilot.testcase import AutopilotTestCase
@@ -119,6 +120,49 @@
             Not(IsInstance(type(generic_window)))
         )
 
+    def test_print_tree_full(self):
+        """Print tree of full application"""
+
+        app = self.start_mock_app(EmulatorBase)
+        win = app.select_single("QMainWindow")
+
+        stream = StringIO()
+        win.print_tree(stream)
+        out = stream.getvalue()
+
+        # starts with root node
+        self.assertThat(out.startswith("== /Root/QMainWindow ==\nChildren:"),
+                        Equals(True))
+        # has root node properties
+        self.assertThat(out, Contains("windowTitle: 'Default Window Title'\n"))
+        # has level-1 widgets with expected indent
+        self.assertThat(out,
+                        Contains("  == /Root/QMainWindow/QRubberBand ==\n"))
+        self.assertThat(out, Contains("  objectName: 'qt_rubberband'\n"))
+        # has level-2 widgets with expected indent
+        self.assertThat(out, Contains("    == /Root/QMainWindow/QMenuBar/"
+                                      "QToolButton =="))
+        self.assertThat(out, Contains("    objectName: "
+                                      "'qt_menubar_ext_button'"))
+
+    def test_print_tree_depth_limit(self):
+        """Print depth-limited tree for a widget"""
+
+        app = self.start_mock_app(EmulatorBase)
+        win = app.select_single("QMainWindow")
+
+        stream = StringIO()
+        win.print_tree(stream, 1)
+        out = stream.getvalue()
+
+        # has level-0 (root) node
+        self.assertThat(out, Contains("== /Root/QMainWindow =="))
+        # has level-1 widgets
+        self.assertThat(out, Contains("/Root/QMainWindow/QMenuBar"))
+        # no level-2 widgets
+        self.assertThat(out, Not(Contains(
+            "/Root/QMainWindow/QMenuBar/QToolButton")))
+
 
 class QMLCustomEmulatorTestCase(AutopilotTestCase):
     """Test the introspection of a QML application with a custom emulator."""

=== modified file 'autopilot/tests/unit/test_introspection_features.py'
--- autopilot/tests/unit/test_introspection_features.py	2013-10-07 03:14:09 +0000
+++ autopilot/tests/unit/test_introspection_features.py	2013-10-25 05:07:27 +0000
@@ -17,11 +17,17 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+import sys
+import tempfile
+import shutil
+import os.path
 
 from mock import patch, Mock
+from textwrap import dedent
 from testtools import TestCase
 from testtools.matchers import Equals, NotEquals
 from testscenarios import TestWithScenarios
+from six import StringIO
 
 
 from autopilot.introspection.dbus import (
@@ -166,3 +172,70 @@
         fake_object.get_state_by_path('some_query')
 
         self.assertThat(mock_logger.warning.called, Equals(False))
+
+    def _print_test_fake_object(self):
+        """common fake object for print_tree tests"""
+
+        fake_object = DBusIntrospectionObject(
+            dict(id=[0, 123], path=[0, '/some/path'], text=[0, 'Hello']),
+            '/some/path',
+            Mock()
+        )
+        # get_properties() always refreshes state, so can't use
+        # no_automatic_refreshing()
+        fake_object.refresh_state = lambda: None
+        fake_object.get_state_by_path = lambda query: []
+        return fake_object
+
+    def test_print_tree_stdout(self):
+        """print_tree with default output (stdout)"""
+
+        fake_object = self._print_test_fake_object()
+        orig_sys_stdout = sys.stdout
+        sys.stdout = StringIO()
+        try:
+            fake_object.print_tree()
+            result = sys.stdout.getvalue()
+        finally:
+            sys.stdout = orig_sys_stdout
+
+        self.assertEqual(result, dedent("""\
+            == /some/path ==
+            id: 123
+            path: '/some/path'
+            text: 'Hello'
+            """))
+
+    def test_print_tree_fileobj(self):
+        """print_tree with file object output"""
+
+        fake_object = self._print_test_fake_object()
+        out = StringIO()
+
+        fake_object.print_tree(out)
+
+        self.assertEqual(out.getvalue(), dedent("""\
+            == /some/path ==
+            id: 123
+            path: '/some/path'
+            text: 'Hello'
+            """))
+
+    def test_print_tree_path(self):
+        """print_tree with file path output"""
+
+        fake_object = self._print_test_fake_object()
+        workdir = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, workdir)
+        outfile = os.path.join(workdir, 'widgets.txt')
+
+        fake_object.print_tree(outfile)
+
+        with open(outfile) as f:
+            result = f.read()
+        self.assertEqual(result, dedent("""\
+            == /some/path ==
+            id: 123
+            path: '/some/path'
+            text: 'Hello'
+            """))