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, 69 insertions, 39 deletions

diff --git a/lib/common_test/doc/src/run_test.xml b/lib/common_test/doc/src/run_test.xml
index d9dd22d411..d609c4287f 100644
--- a/lib/common_test/doc/src/run_test.xml
+++ b/lib/common_test/doc/src/run_test.xml
@@ -4,7 +4,7 @@
 <comref>
   <header>
     <copyright>
-      <year>2007</year><year>2009</year>
+      <year>2007</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,62 +13,87 @@
       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>The run_test shell script</title>
+    <title>The run_test program</title>
     <prepared>Peter Andersson</prepared>
     <responsible>Peter Andersson</responsible>
     <docno></docno>
     <approved></approved>
     <checked></checked>
-    <date>2007-07-04</date>
-    <rev>PA1</rev>
+    <date>2010-04-01</date>
+    <rev>PA2</rev>
     <file>run_test.xml</file>
   </header>
-  <com>run_test</com> 
-  <comsummary>Shell script used for starting
-  Common Test from the Unix command line.
+  <com>run_test</com>
+  <comsummary>Program used for starting Common Test from the
+    OS command line.
   </comsummary>
 
   <description>
-  <p>The <c>run_test</c> script is automatically generated as Common
-  Test is installed (please see the Installation chapter in the Common
-  Test User's Guide for more information). The script accepts a number 
-  of different start flags. Some flags trigger <c>run_test</c>
-  to start the Common Test application and pass on data to it. Some
-  flags start an Erlang node prepared for running Common Test in a
-  particular mode.</p>
-  <p><c>run_test</c> also accepts Erlang emulator
-  flags. These are used when <c>run_test</c> calls <c>erl</c> to
-  start the Erlang node (making it possible to e.g. add directories to
-  the code server path, change the cookie on the node, start
-  additional applications, etc).</p>
-  <p>If <c>run_test</c> is called without parameters, it prints all valid
-  start flags to stdout.</p>
+  <p>The <c>run_test</c> program is automatically installed with Erlang/OTP
+    and Common Test (please see the Installation chapter in the Common
+    Test User's Guide for more information). The program accepts a number
+    of different start flags. Some flags trigger <c>run_test</c>
+    to start the Common Test application and pass on data to it. Some
+    flags start an Erlang node prepared for running Common Test in a
+    particular mode.</p>
+
+  <p><c>run_test</c> also accepts Erlang emulator flags. These are used
+    when <c>run_test</c> calls <c>erl</c> to start the Erlang node
+    (making it possible to e.g. add directories to the code server path,
+    change the cookie on the node, start additional applications, etc).</p>
+
+  <p>With the optional flag:</p>
+  <pre>-erl_args</pre>
+  <p>it's possible to divide the options on the <c>run_test</c> command line into
+    two groups, one that Common Test should process (those preceding <c>-erl_args</c>),
+    and one it should completely ignore and pass on directly to the emulator
+    (those following <c>-erl_args</c>). Options preceding <c>-erl_args</c> that Common Test
+    doesn't recognize, also get passed on to the emulator untouched.
+    By means of <c>-erl_args</c> the user may specify flags with the same name, but
+    with different destinations, on the <c>run_test</c> command line.</p>
+  <p>If <c>-pa</c> or <c>-pz</c> flags are specified in the Common Test group of options
+    (preceding <c>-erl_args</c>), relative directories will be converted to
+    absolute and re-inserted into the code path by Common Test (to avoid
+    problems loading user modules when Common Test changes working directory
+    during test runs). Common Test will however ignore <c>-pa</c> and <c>-pz</c> flags
+    following <c>-erl_args</c> on the command line. These directories are added
+    to the code path normally (i.e. on specified form)</p>
+
+  <p>If <c>run_test</c> is called with option:</p>
+    <pre>-help</pre>
+    <p>it prints all valid start flags to stdout.</p>
   </description>
 
   <section>
     <title>Run tests from command line</title>
     <pre>
-    	run_test [-dir TestDir1 TestDir2 .. TestDirN] |	
-	[-suite Suite1 Suite2 .. SuiteN 
+	run_test [-dir TestDir1 TestDir2 .. TestDirN] |
+	[-suite Suite1 Suite2 .. SuiteN
 	 [[-group Group1 Group2 .. GroupN] [-case Case1 Case2 .. CaseN]]]
 	[-step [config | keep_inactive]]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+	 ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
-	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN]
+	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
+        [-event_handler_init EvHandler1 InitArg1 and
+	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
         [-repeat N [-force_stop]] |
         [-duration HHMMSS [-force_stop]] |
         [-until [YYMoMoDD]HHMMSS [-force_stop]]
@@ -79,15 +104,21 @@
     <pre>
 	run_test -spec TestSpec1 TestSpec2 .. TestSpecN
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-logdir LogDir]
 	[-allow_user_terms]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
-	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN]
+	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
+        [-event_handler_init EvHandler1 InitArg1 and
+	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
         [-repeat N [-force_stop]] |
         [-duration HHMMSS [-force_stop]] |
         [-until [YYMoMoDD]HHMMSS [-force_stop]]
@@ -98,11 +129,15 @@
     <pre>
         run_test -vts [-browser Browser]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
         [-dir TestDir1 TestDir2 .. TestDirN] |
         [-suite Suite [[-group Group] [-case Case]]]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
 	[-basic_html]</pre>
   </section>
   <section>
@@ -113,28 +148,23 @@
   <section>
     <title>Run CT in interactive mode</title>
     <pre>
-	run_test -shell 
+	run_test -shell
 	[-config ConfigFile1 ConfigFile2 ... ConfigFileN]
+	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+         ConfigString2 and .. and CallbackModuleN ConfigStringN]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]</pre>
   </section>
   <section>
-    <title>Start an Erlang node with a given name</title>
-    <pre>
-	run_test -ctname NodeName</pre>
-  </section>
-  <section>
     <title>Start a Common Test Master node</title>
     <pre>
 	run_test -ctmaster</pre>
   </section>
 
   <section>
-  <title>See also</title>
-  <p>Please read the <seealso marker="run_test_chapter">Running Test Suites</seealso>
-  chapter in the Common Test User's Guide for information about the meaning of the
-  different start flags.</p>
+    <title>See also</title>
+    <p>Please read the <seealso marker="run_test_chapter">Running Test Suites</seealso>
+      chapter in the Common Test User's Guide for information about the meaning of the
+      different start flags.</p>
   </section>
 
 </comref>
-
-