From aef5c74eba885b7c28d310b4a2522de854012e33 Mon Sep 17 00:00:00 2001
From: Peter Andersson <peppe@erlang.org>
Date: Tue, 8 Jun 2010 12:41:57 +0200
Subject: Add documentation for run_test program

---
 lib/common_test/doc/src/run_test.xml | 33 ++++++++++++++++++++++++++-------
 lib/common_test/src/ct_run.erl       | 10 ++++++----
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/lib/common_test/doc/src/run_test.xml b/lib/common_test/doc/src/run_test.xml
index f98cefd0ee..feef18fe33 100644
--- a/lib/common_test/doc/src/run_test.xml
+++ b/lib/common_test/doc/src/run_test.xml
@@ -50,8 +50,26 @@
     (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>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>
@@ -74,6 +92,8 @@
 	 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]]
@@ -97,6 +117,8 @@
 	 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]]
@@ -114,6 +136,8 @@
         [-suite Suite [[-group Group] [-case Case]]]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-muliply_timetraps Multiplier]
+	[-scale_timetraps]
 	[-basic_html]</pre>
   </section>
   <section>
@@ -130,11 +154,6 @@
          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>
diff --git a/lib/common_test/src/ct_run.erl b/lib/common_test/src/ct_run.erl
index 9dc0bff26a..6a9c42d1b9 100644
--- a/lib/common_test/src/ct_run.erl
+++ b/lib/common_test/src/ct_run.erl
@@ -164,7 +164,9 @@ script_start1(Parent, Args) ->
     MultTT = get_start_opt(multiply_timetraps,
 			   fun([MT]) -> list_to_integer(MT) end, 1, Args),
     ScaleTT = get_start_opt(scale_timetraps,
-			    fun([CT]) -> list_to_atom(CT) end, false, Args),
+			    fun([CT]) -> list_to_atom(CT);
+			       ([]) -> true
+			    end, false, Args),
     EvHandlers = event_handler_args2opts(Args),
 
     %% check flags and set corresponding application env variables
@@ -478,7 +480,7 @@ script_usage() ->
 	      "\n\t[-suite Suite [-case Case]]"
 	      "\n\t[-include InclDir1 InclDir2 .. InclDirN]"
 	      "\n\t[-no_auto_compile]"
-	      "\n\t[-multiply_timetraps]"
+	      "\n\t[-multiply_timetraps N]"
 	      "\n\t[-scale_timetraps]"
 	      "\n\t[-basic_html]\n\n"),
     io:format("Run tests from command line:\n\n"
@@ -495,7 +497,7 @@ script_usage() ->
 	      "\n\t[-event_handler EvHandler1 EvHandler2 .. EvHandlerN]"
 	      "\n\t[-include InclDir1 InclDir2 .. InclDirN]"
 	      "\n\t[-no_auto_compile]"
-	      "\n\t[-multiply_timetraps]"
+	      "\n\t[-multiply_timetraps N]"
 	      "\n\t[-scale_timetraps]"
 	      "\n\t[-basic_html]"
 	      "\n\t[-repeat N [-force_stop]] |"
@@ -513,7 +515,7 @@ script_usage() ->
 	      "\n\t[-event_handler EvHandler1 EvHandler2 .. EvHandlerN]"
 	      "\n\t[-include InclDir1 InclDir2 .. InclDirN]"
 	      "\n\t[-no_auto_compile]"
-	      "\n\t[-multiply_timetraps]"
+	      "\n\t[-multiply_timetraps N]"
 	      "\n\t[-scale_timetraps]"
 	      "\n\t[-basic_html]"
 	      "\n\t[-repeat N [-force_stop]] |"
-- 
cgit v1.2.3