Merge lp:~joetalbott/utah/document_reboot into lp:utah

[Joe Talbott]

Add some notes to the documentation regarding reboot testcases.

[Javier Collado (javier.collado)]

I see the same issues as in the other documentation review. I think we should
agree on when to use markup and when to use single quotes. I prefer markup, but
I'm fine with whatever is consistent.

[lp:~joetalbott/utah/document_reboot]

715. By Joe Talbott on 2012-10-19

Fix markup

[Joe Talbott (joetalbott)]

Should be fixed. I can't confirm locally.

review: Needs Resubmitting

[Javier Collado (javier.collado)]

@Joe

Looks good to me now. Thanks

Well, still there's /etc/rc.local that could be between double backquotes, but I leave it to your criteria.

review: Approve

[lp:~joetalbott/utah/document_reboot]

716. By Joe Talbott on 2012-10-19

Double backquote file name.

=== modified file 'docs/source/introduction.rst'
--- docs/source/introduction.rst	2012-09-26 14:14:13 +0000
+++ docs/source/introduction.rst	2012-10-19 19:31:22 +0000
@@ -53,7 +53,7 @@
 UTAH is very simple in terms of testing reliably and being able to reproduce a
 test run in a consistent manner. A command line specifies the test
 environment, type of machine to test on and a runlist. Then wait for it to finish and
-analyse the results:
+analyze the results:
 
 .. image:: img/utah.jpg
    :align: center
@@ -62,7 +62,7 @@
 by provisioning it with a particular provisioning method.
 
 **WARNING: Your machine will be modified, not to interfere with your current
-set-up or virtualised environment, so UTAH will create a new user called utah
+set-up or virtualized environment, so UTAH will create a new user called utah
 with sudo privileges to run the tests and have an inventory of existing VMs
 that you could be interested in for running tests.**
 
@@ -135,4 +135,17 @@
        /usr/share/utah/client/examples/master.run \
        'http://people.canonical.com/~max/max_test.run'
 
+Running tests that need to reboot
+=================================
+
+In a situation where a reboot is required.  This is handled in UTAH by marking a testcase (in the ``tc_control`` file) with::
+
+    reboot: <always, pass, never>
+
+This will make the **utah client** reboot the system under test at the **end** of the testcase after any  ``tc_cleanup`` command has finished.  Any thing that needs to be tested after the reboot should be in the testcase immediately following the testcase marked for reboot.
+
+The possible choices are ``always``, ``pass``, and ``never``.  ``never`` is the default and simply means the system under test will not reboot.  ``pass`` means the reboot will only happen if the testcase passes.  ``always``, means just that, the reboot will happen even if the test fails.
+
+Some things to keep in mind.  The **utah-client** resumes by replacing ``/etc/rc.local`` with a file that will resume the current run and will resume with the testcase following the one that triggered the reboot.  Also note that in order to have both pre- and post-reboot logging the ``-o`` flag should be used so that post-reboot output will be appended to the pre-reboot output.
+
 .. _Ubuntu Test Automation Harness: https://launchpad.net/utah