From ebcab814cabc74407f48aba1b41327df80586fcd Mon Sep 17 00:00:00 2001
From: Andrey Pampukha <andrey@erlang.org>
Date: Thu, 15 Apr 2010 12:57:04 +0200
Subject: Document ct_slave and 'eval' terms

---
 lib/common_test/doc/src/ct_master_chapter.xml | 31 +++++++++++++++++++++++++++
 lib/common_test/doc/src/run_test_chapter.xml  | 16 +++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

(limited to 'lib/common_test')

diff --git a/lib/common_test/doc/src/ct_master_chapter.xml b/lib/common_test/doc/src/ct_master_chapter.xml
index 79288cfe4c..1622b5b29c 100644
--- a/lib/common_test/doc/src/ct_master_chapter.xml
+++ b/lib/common_test/doc/src/ct_master_chapter.xml
@@ -194,6 +194,37 @@
     current working directory settings are not important.</p></note>
   </section>
 
+  <section>
+    <title>Automatic startup of the test target nodes</title>
+    <marker id="ct_slave"></marker>
+    <p>Is is possible to start nodes acting like a test targets automatically
+    using a new term in the test specification, <c>node_start</c>:</p>
+    <pre>
+     {node, node1, node1@host1}.
+     {node, node2, node1@host2}.
+     {node, node3, node2@host2}.
+     {node_start, node1, [{callback_module, my_slave_callback}]}.
+     {node_start, [node2, node3], [{username, "ct_user"}, {password, "ct_password"}]}.
+    </pre>
+    <p>This test specification declares that <c>node1@host1</c> is to be started using
+    user's callback <c>my_slave_callback</c> with no parameters, and nodes <c>node1@host2</c> and
+    <c>node2@host2</c> will be started with the default callback module <c>ct_slave</c>,
+    using the given user name and password to log into remote host <c>host2</c>.</p>
+    <p>Default <seealso marker="ct_slave">ct_slave</seealso> callback module delivered with the Common Test has the following features:
+    <list>
+     <item>Starting the Erlang nodes or local or remote hosts (ssh is used for remote ones);</item>
+     <item>Ability to start Erlang emulator with the additional flags (any flags supported by <c>erl</c> are supported);</item>
+     <item>Supervision of the node being start using internal callback functions. Used to prevent hanging of started nodes. Configurable;</item>
+     <item>Monitoring of the master node by the slaves. Slave node may be stopped in case of master node termination. Configurable;</item>
+     <item>Execution of the user's functions after slave node is started. Functions can be given as a list of {Module, Function, Arguments} tuples.</item>
+    </list>
+    </p>
+    <p>If any <c>eval</c> term is specified for a node which has <c>node_start</c> term
+    defined for it, the evaluation of the functions will be deferred until the node is started.
+    The functions to be evaluated are simply added to the end of the <c>startup_functions</c> list
+    (see <seealso marker="ct_slave">ct_slave</seealso> chapter in the Reference Manual).</p>
+  </section>
+
 </chapter>
 
 
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index 00cf4adf52..f5dc477c6f 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -383,6 +383,9 @@
       {event_handler, NodeRefs, EventHandlers}.
       {event_handler, EventHandlers, InitArgs}.
       {event_handler, NodeRefs, EventHandlers, InitArgs}.
+
+      {eval, [{Module, Function, Arguments}]}.
+      {eval, [NodeAlias], [{Module, Function, Arguments}]}.
     </pre>
       <p>Test terms:</p>
     <pre>
@@ -455,9 +458,20 @@
       <item>Secondly, the test for system t2 should run. The included suites are
 	t2B and t2C. Included are also test cases test4, test1 and test7 in suite
 	t2A. Note that the test cases will be executed in the specified order.</item>
-      <item>Lastly, all suites for systems t3 are to be completely skipped and this 
+      <item>Lastly, all suites for systems t3 are to be completely skipped and this
 	should be explicitly noted in the log files.</item>
     </list>
+    <p>It is possible to evaluate any function(s) during processing of the test
+      specification. This feature may be used e.g. to add some directories to
+      the code path, initialise some ETS table etc. New <c>eval</c> terms can be
+      used for this purpose.
+      If only a list of functions is given, then all functions from the list
+      will be consequently applied on the current node. If at least one node
+      alias is given, then the functions will be called remotely on all nodes
+      specified. Please note that in case when node is defined to be started by
+      the CT Master, the evaluation will be deferred.
+      See the <seealso marker="ct_master_chapter#ct_slave">Automatic startup of
+      the test target nodes</seealso> chapter for details.</p>
     <p>It is possible for the user to provide a test specification that
       includes (for Common Test) unrecognizable terms. If this is desired,
       the <c>-allow_user_terms</c> flag should be used when starting tests with
-- 
cgit v1.2.3