Merge branch 'peppe/common_test_r14_dev_2' into dev

* peppe/common_test_r14_dev_2:
  Misc documentation updates
  Add documentation for run_test program
  Step vsn for test_server to 3.4
  Make {repeat*,N} property in group execute the group N times exactly
  Fix so that ct_run converts relative diretories in the code path to absolute
  Fix bug in handling framework:end_tc timeouts
  Fix bug that prevents the interactive shell mode to start properly
  Fix failing multiply timetrap test case
  Minor fixes in code and test suites
  Add support for executing pre-loaded suites (e.g. modules loaded as binaries)
  Add test suite for remote loading of binary suites
  Fix error with {repeat,0} property in groups causing double iterations
  Add support for config info functions (e.g. init_per_suite/0)
  Add support for dynamic timetrap handling
  Have end_per_testcase run even after timetrap_timeout and abort_testcase
  Flush old DOWN messages in demonitor
  Add groups in test specifications
  Add new tests for test case groups and test specifications
  Improve and fix various test suites
  Add event_handler_init start flag that can pass init arguments to event handlers
  ...

OTP-8703 peppe/common_test_r14_dev_2

1 files changed, 57 insertions, 5 deletions

diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml
index 79288cfe4c..01f8e61d36 100644
--- a/lib/common_test/doc/src/ct_master_chapter.xml
+++ b/lib/common_test/doc/src/ct_master_chapter.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2006</year><year>2009</year>
+      <year>2006</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>Using Common Test for Large Scale Testing</title>
@@ -30,6 +30,7 @@
   </header>
 
   <section>
+    <marker id="general"></marker>
     <title>General</title>
     <p>Large scale automated testing requires running multiple independent 
       test sessions in parallel. This is accomplished by running
@@ -102,9 +103,10 @@
       <p><c>ct_master:abort()</c> (stop all) or <c>ct_master:abort(Nodes)</c></p>
 
       <p>For detailed information about the <c>ct_master</c> API, please see the 
-      manual page for this module.</p>
+      <seealso marker="ct_master">manual page</seealso> for this module.</p>
   </section>
   <section>
+    <marker id="test_specifications"></marker>
     <title>Test Specifications</title>
     <p>The test specifications used as input to CT Master are fully compatible with the
     specifications used as input to the regular CT server. The syntax is described in the 
@@ -186,7 +188,7 @@
     <seealso marker="run_test_chapter#test_specifications">Running Test Suites</seealso>
     chapter). The result is that any test specified to run on a node with the same
     name as the Common Test node in question (typically <c>ct@somehost</c> if started
-    with the <c>run_test</c> script), will be performed. Tests without explicit
+    with the <c>run_test</c> program), will be performed. Tests without explicit
     node association will always be performed too of course!</p>
 
     <note><p>It is recommended that absolute paths are used for log directories,
@@ -194,6 +196,56 @@
     current working directory settings are not important.</p></note>
   </section>
 
+  <section>
+    <title>Automatic startup of test target nodes</title>
+    <marker id="ct_slave"></marker>
+    <p>Is is possible to automatically start, and perform initial actions, on
+      test target nodes by using the test specification term <c>init</c>.</p>
+    <p>Currently, two sub-terms are supported, <c>node_start</c> and <c>eval</c>.</p>
+    <p>Example:</p>
+    <pre>
+     {node, node1, node1@host1}.
+     {node, node2, node1@host2}.
+     {node, node3, node2@host2}.
+     {node, node4, node1@host3}.
+     {init, node1, [{node_start, [{callback_module, my_slave_callback}]}]}.
+     {init, [node2, node3], {node_start, [{username, "ct_user"}, {password, "ct_password"}]}}.
+     {init, node4, {eval, {module, function, []}}}.</pre>
+
+    <p>This test specification declares that <c>node1@host1</c> is to be started using
+      the user callback function <c>callback_module:my_slave_callback/0</c>, and nodes
+      <c>node1@host2</c> and <c>node2@host2</c> will be started with the default callback
+      module <c>ct_slave</c>. The given user name and password is used to log into remote
+      host <c>host2</c>. Also, the function <c>module:function/0</c> will be evaluated on
+      <c>node1@host3</c>, and the result of this call will be printed to the log.</p>
+
+    <p>The default <seealso marker="ct_slave">ct_slave</seealso> callback module,
+      which is part of the Common Test application, has the following features:
+    <list>
+     <item>Starting Erlang target nodes on local or remote hosts
+       (ssh is used for communication).
+     </item>
+     <item>Ability to start an Erlang emulator with additional flags
+       (any flags supported by <c>erl</c> are supported).
+     </item>
+     <item>Supervision of a node being started by means of internal callback
+        functions. Used to prevent hanging nodes. (Configurable).
+     </item>
+     <item>Monitoring of the master node by the slaves. A slave node may be
+        stopped in case the master node terminates. (Configurable).
+     </item>
+     <item>Execution of user functions after a slave node is started.
+        Functions can be given as a list of {Module, Function, Arguments} tuples.
+     </item>
+    </list>
+    </p>
+    <p>Note that it is possible to specify an <c>eval</c> term for the node as well
+    as <c>startup_functions</c> in the <c>node_start</c> options list. In this
+    case first the node will be started, then the <c>startup_functions</c> are
+    executed, and finally functions specified with <c>eval</c> are called.
+    </p>
+  </section>
+
 </chapter>