Autopilot

Merge lp:~thomir/autopilot/trunk-add-troubleshooting-docs into lp:autopilot

trunk-add-troubleshooting-docs
Merge into trunk

Proposed by Thomi Richards on 2015-01-21

Status:	Merged
Approved by:	Christopher Lee on 2015-01-21
Approved revision:	531
Merged at revision:	531
Proposed branch:	lp:~thomir/autopilot/trunk-add-troubleshooting-docs
Merge into:	lp:autopilot
Prerequisite:	lp:~thomir/autopilot/trunk-fix-vis-section
Diff against target:	46 lines (+34/-3) 1 file modified docs/faq/troubleshooting.rst (+34/-3)
To merge this branch:	bzr merge lp:~thomir/autopilot/trunk-add-troubleshooting-docs
Related bugs:	Link a bug report

Reviewer	Review Type	Date Requested	Status
PS Jenkins bot	continuous-integration	2015-01-21	Approve on 2015-01-22
Christopher Lee (community)			Approve on 2015-01-21
Richard Huddie (community)			Needs Fixing on 2015-01-21
Leo Arias	build the docs, read them.	2015-01-21	Approve on 2015-01-21
Review via email: mp+247093@code.launchpad.net

This proposal supersedes a proposal from 2015-01-21.

Commit Message

Document various debugging techniques.

Description of the Change

Add some information around debugging techniques.

Leo Arias (elopio) wrote on 2015-01-21:

Thanks.

review: Approve (build the docs, read them.)

PS Jenkins bot (ps-jenkins) wrote on 2015-01-21: Posted in a previous version of this proposal

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

review: Approve (continuous-integration)

PS Jenkins bot (ps-jenkins) wrote on 2015-01-21:

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

review: Approve (continuous-integration)

Richard Huddie (rhuddie) wrote on 2015-01-21:

Looks good, only a couple of minor points.

review: Needs Fixing

lp:~thomir/autopilot/trunk-add-troubleshooting-docs updated on 2015-01-21

529. By Thomi Richards on 2015-01-21: Clean up code from review.
530. By Thomi Richards on 2015-01-21: Fix english.

Christopher Lee (veebers) wrote on 2015-01-21:

Looking good, just one minor question there.

review: Needs Fixing

lp:~thomir/autopilot/trunk-add-troubleshooting-docs updated on 2015-01-21

531. By Thomi Richards on 2015-01-21: Fix english.

Christopher Lee (veebers) wrote on 2015-01-21:

sweet, LGTM.

review: Approve

PS Jenkins bot (ps-jenkins) wrote on 2015-01-21:

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

review: Approve (continuous-integration)

PS Jenkins bot (ps-jenkins) on 2015-01-22:

review: Approve (continuous-integration)

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk

Subscribers

People subscribed via source and target branches

to all changes:

Autopilot Hackers

Chris Gagnon

Thomi Richards

 === modified file 'docs/faq/troubleshooting.rst'
 --- docs/faq/troubleshooting.rst	2015-01-21 05:28:45 +0000
 +++ docs/faq/troubleshooting.rst	2015-01-21 22:08:49 +0000
@@ -4,9 +4,40 @@
  .. contents::
---------------
--Failing Tests
---------------
++.. _troubleshooting_general_techniques:
++
++------------------
++General Techniques
++------------------
++
++The single hardest thing to do while writing autopilot tests is to understand the state of the application's object tree. This is especially important for applications that change their object tree during the lifetime of the test. There are three techniques you can use to discover the state of the object tree:
++
++**Using Autopilot Vis**
++
++The :ref:`Autopilot vis tool <visualise_introspection_tree>` is a useful tool for exploring the entire structure of an application, and allows you to search for a particular node in the object tree. If you want to find out what parts of the application to select to gain access to certain information, the vis tool is probably the best way to do that.
++
++**Using print_tree**
++
++The :meth:`~autopilot.introspection.ProxyBase.print_tree` method is available on every proxy class. This method will print every child of the proxy object recursively, either to ``stdout`` or a file on disk. This technique can be useful when:
++
++* The application cannot easily be put into the state required before launching autopilot vis, so the vis tool is no longer an option.
++* The application state that has to be captured only exists for a short amount of time.
++* The application only runs on platforms where the vis tool isn't available.
++
++The :meth:`~autopilot.introspection.ProxyBase.print_tree` method often produces a lot of output. There are two ways this information overload can be handled:
++
++#. Specify a file path to write to, so the console log doesn't get flooded. This log file can then be searched with tools such as ``grep``.
++#. Specify a ``maxdepth`` limit. This controls how many levels deep the recursive search will go.
++
++Of course, these techniques can be used in combination.
++
++**Using get_properties**
++
++The :meth:`~autopilot.introspection.ProxyBase.get_properties` method can be used on any proxy object, and will return a python dictionary containing all the properties of that proxy object. This is useful when you want to explore what information is provided by a single proxy object. The information returned by this method is exactly the same as is shown in the right-hand pane of ``autopilot vis``.
++
++----------------------------------------
++Common Questions regarding Failing Tests
++----------------------------------------
  .. _failing_tests: