Merge branch 'master' of super:otp into bmk/inets/inets58_integration

6 files changed, 303 insertions, 19 deletions

diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index 57b032b3fd..f58b2ab0a9 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -133,9 +133,15 @@
 	    {require,Name,Required} | {userdata,UserData} |
 	    {silent_connections,Conns} | {stylesheet,CSSFile} | 
 	    {ct_hooks, CTHs}</v>
-	<v> Time = MilliSec | {seconds,integer()} | {minutes,integer()}
-	  | {hours,integer()}</v>
+	<v> Time = TimeVal | TimeFunc</v>
+	<v> TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
+	    {hours,integer()}</v>
+	<v> TimeFunc = {Mod,Func,Args} | Fun</v>
 	<v> MilliSec = integer()</v>
+	<v> Mod = atom()</v>
+	<v> Func = atom()</v>
+	<v> Args = list()</v>
+	<v> Fun = fun()</v>
 	<v> Required = Key | {Key,SubKeys}</v>
 	<v> Key = atom()</v>
 	<v> SubKeys = SubKey | [SubKey]</v>
@@ -161,7 +167,9 @@
 	  test case is allowed to take (including <c>init_per_testcase/2</c>
 	  and <c>end_per_testcase/2</c>). If the timetrap time is
 	  exceeded, the test case fails with reason
-	  <c>timetrap_timeout</c>.</p>
+	  <c>timetrap_timeout</c>. If a <c>TimeFunc</c> function is specified,
+	  it will be called initially and must return a value on
+	  <c>TimeVal</c> format.</p>
 	
 	<p>The <c>require</c> tag specifies configuration variables
 	  that are required by test cases in the suite. If the required
@@ -248,7 +256,7 @@
 	</type>
 	<desc>	
 	  
-	  <p> MANDATORY (only if one or more groups are defined) </p>
+	  <p> OPTIONAL </p>
 	  
 	  <p>This function is called before execution of a test case group.
 	  It typically contains initialization which is common for
@@ -279,7 +287,7 @@
 	</type>
 	
 	<desc>	
-	  <p> MANDATORY (only if one or more groups are defined) </p>
+	  <p> OPTIONAL </p>
 	  
 	  <p>This function is called after the execution of a test case group is finished.
 	    It is meant to be used for cleaning up after <c>init_per_group/2</c>.
@@ -353,9 +361,15 @@
 	<v> Info = {timetrap,Time} | {require,Required} | 
 	    {require,Name,Required} | {userdata,UserData} |
 	    {silent_connections,Conns}</v>
-	<v> Time = MilliSec | {seconds,integer()} | {minutes,integer()}
-	  | {hours,integer()}</v>
+	<v> Time = TimeVal | TimeFunc</v>
+	<v> TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
+	    {hours,integer()}</v>
+	<v> TimeFunc = {Mod,Func,Args} | Fun</v>
 	<v> MilliSec = integer()</v>
+	<v> Mod = atom()</v>
+	<v> Func = atom()</v>
+	<v> Args = list()</v>
+	<v> Fun = fun()</v>
 	<v> Required = Key | {Key,SubKeys}</v>
 	<v> Key = atom()</v>
 	<v> SubKeys = SubKey | [SubKey]</v>
@@ -378,7 +392,9 @@
 	  exceeded, the test case fails with reason
 	  <c>timetrap_timeout</c>. <c>init_per_testcase/2</c>
 	  and <c>end_per_testcase/2</c> are included in the
-	  timetrap time.</p>
+	  timetrap time. If a <c>TimeFunc</c> function is specified,
+	  it will be called before the test case (or <c>init_per_testcase/2</c>)
+	  and must return a value on <c>TimeVal</c> format.</p>
 	
 	<p>The <c>require</c> tag specifies configuration variables
 	  that are required by the test case. If the required
diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml
index 59151a73ec..6fc6638bf7 100644
--- a/lib/common_test/doc/src/config_file_chapter.xml
+++ b/lib/common_test/doc/src/config_file_chapter.xml
@@ -285,7 +285,7 @@
           <c>{ok, Config}</c> - if the configuration variables are read successfully,
         </item>
         <item>
-          <c>{error, Error, ErrorDetails}</c> - if the callback module fails to
+          <c>{error, {Error, ErrorDetails}}</c> - if the callback module fails to
           proceed with the given configuration parameters.
         </item>
       </list>
@@ -422,14 +422,14 @@ stop()->
 call(Client, Request)->
     case whereis(?REGISTERED_NAME) of
         undefined->
-            {error, not_started, Request};
+            {error, {not_started, Request}};
         Pid->
             Pid ! {Client, Request},
             receive
                 Reply->
                     {ok, Reply}
             after 4000->
-                {error, timeout, Request}
+                {error, {timeout, Request}}
             end
     end.
 
diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index 1ab563d74f..9045646733 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -83,7 +83,7 @@
     <title>Run tests from command line</title>
     <pre>
 	ct_run [-dir TestDir1 TestDir2 .. TestDirN] |
-	[-suite Suite1 Suite2 .. SuiteN
+	[[-dir TestDir] -suite Suite1 Suite2 .. SuiteN
 	 [[-group Group1 Group2 .. GroupN] [-case Case1 Case2 .. CaseN]]]
 	[-step [config | keep_inactive]]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
@@ -92,6 +92,7 @@
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-label Label]
 	[-logdir LogDir]
+	[-logopts LogOpts]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
@@ -117,6 +118,7 @@
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-label Label]
 	[-logdir LogDir]
+	[-logopts LogOpts]
 	[-allow_user_terms]
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
@@ -138,10 +140,11 @@
     <pre>
         ct_run -vts [-browser Browser]
         [-dir TestDir1 TestDir2 .. TestDirN] |
-        [-suite Suite [[-group Group] [-case Case]]]
+        [[dir TestDir] -suite Suite [[-group Group] [-case Case]]]
 	[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
 	[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
          ConfigString2 and .. and CallbackModuleN ConfigStringN]
+	[-logopts LogOpts]
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
diff --git a/lib/common_test/doc/src/notes.xml b/lib/common_test/doc/src/notes.xml
index 826b3c598d..af96ef621f 100644
--- a/lib/common_test/doc/src/notes.xml
+++ b/lib/common_test/doc/src/notes.xml
@@ -32,6 +32,229 @@
     <file>notes.xml</file>
     </header>
 
+<section><title>Common_Test 1.5.5</title>
+
+    <section><title>Fixed Bugs and Malfunctions</title>
+      <list>
+        <item>
+          <p>
+	    An error in how comments are colored in the test suite
+	    overview html log file has been corrected. As result, a
+	    new framework callback function, format_comment/1, has
+	    been introduced.</p>
+          <p>
+	    Own Id: OTP-9237</p>
+        </item>
+        <item>
+          <p>
+	    Automatically generated init- and end-configuration
+	    functions for test case groups caused incorrect execution
+	    order of test cases. This has been corrected.</p>
+          <p>
+	    Own Id: OTP-9369</p>
+        </item>
+        <item>
+          <p>
+	    If multiple directories were specified with the 'logdir'
+	    flag/option, Common Test would crash. This has been fixed
+	    so that an error is properly reported instead.</p>
+          <p>
+	    Own Id: OTP-9370</p>
+        </item>
+        <item>
+          <p>
+	    If ct:log/2 was called with bad arguments, this could
+	    cause the Common Test IO handling process to crash. This
+	    fault has been corrected.</p>
+          <p>
+	    Own Id: OTP-9371 Aux Id: OTP-8933 </p>
+        </item>
+        <item>
+          <p>
+	    A bug has been fixed that made Test Server call the
+	    end_tc/3 framework function with an incorrect module name
+	    as first argument.</p>
+          <p>
+	    Own Id: OTP-9379 Aux Id: seq11863 </p>
+        </item>
+        <item>
+          <p>
+	    If a timetrap timeout occured during execution of of a
+	    function in a lib module (i.e. a function called directly
+	    or indirectly from a test case), the Suite argument in
+	    the end_tc/3 framework callback function would not
+	    correctly contain the name of the test suite, but the lib
+	    module. (This would only happen if the lib module was
+	    compiled with ct.hrl included). This error has been
+	    solved.</p>
+          <p>
+	    Own Id: OTP-9398</p>
+        </item>
+        <item>
+          <p>
+	    Corrections of the vts mode. It will now report errors
+	    (about e.g. incorrect config files) instead of crashing
+	    or hanging. Furthermore, the requirement that the test
+	    directory name must have a "_test" suffix has been
+	    removed. Also, a workaround has been implemented for the
+	    limitation that the file browser (in many web browsers)
+	    will only return the basic file name, not the full
+	    directory path (which made it impossible to have config
+	    files in other directories than the main test directory).</p>
+          <p>
+	    Own Id: OTP-9429</p>
+        </item>
+        <item>
+          <p>
+	    Add a proplist() type</p>
+          <p>
+	    Recently I was adding specs to an API and found that
+	    there is no canonical proplist() type defined. (Thanks to
+	    Ryan Zezeski)</p>
+          <p>
+	    Own Id: OTP-9499</p>
+        </item>
+        <item>
+          <p>
+	    It is now possible to use the 'step' flag/option to run
+	    the debugger for test suites that contain test case
+	    groups. This previously caused Common Test to crash. If
+	    'step config' is specified, breakpoints are now also
+	    automatically set on init_per_group and end_per_group.
+	    Note that breakpoints are always set automatically on
+	    test case functions and this is true also for grouped
+	    cases.</p>
+          <p>
+	    Own Id: OTP-9518 Aux Id: OTP-8933 </p>
+        </item>
+        <item>
+          <p>
+	    The test index page was not refreshed at the start of
+	    each test suite which made it impossible to follow test
+	    execution by means of refreshing the browser window (no
+	    links to follow). This has been fixed.</p>
+          <p>
+	    Own Id: OTP-9520 Aux Id: OTP-8933 </p>
+        </item>
+        <item>
+          <p>
+	    If a test suite would start with a test case group
+	    defined without the init_per_group/2 and end_per_group/2
+	    function, init_per_suite/1 would not execute initially
+	    and logging of the test run would fail. This error has
+	    been fixed.</p>
+          <p>
+	    Own Id: OTP-9584</p>
+        </item>
+        <item>
+          <p>
+	    The "Missing Suites" link from the top level index page
+	    was incorrect and has been fixed.</p>
+          <p>
+	    Own Id: OTP-9592</p>
+        </item>
+      </list>
+    </section>
+
+
+    <section><title>Improvements and New Features</title>
+      <list>
+        <item>
+          <p>
+	    Various corrections and updates to improve the handling
+	    and reporting of errors.</p>
+          <p>
+	    Own Id: OTP-8933</p>
+        </item>
+        <item>
+          <p>
+	    The dir and suite start option can now be used in
+	    combination. E.g. executing my_SUITE in directory
+	    my_tests can either be specified as "ct_run -suite
+	    my_tests/my_SUITE" or as "ct_run -dir my_tests -suite
+	    my_SUITE". Furthermore, the specification:
+	    ct:run_test([{suite,["./my_SUITE"]},{testcase,t1}]) is
+	    now interpreted as
+	    ct:run_test([{suite,"./my_SUITE"},{testcase,t1}]), i.e.
+	    only testcase t1 in test suite my_SUITE - not all cases -
+	    will be executed.</p>
+          <p>
+	    Own Id: OTP-9155</p>
+        </item>
+        <item>
+          <p>
+	    A new option, 'logopts', has been introduced, to make it
+	    possible to modify some aspects of the logging behaviour
+	    in Common Test (or Test Server). For example, whenever an
+	    io printout is made, test_server adds newline (\n) to the
+	    end of the output string. This may not always be a
+	    preferred action and can therefore be disabled by means
+	    of "ct_run ... -logopts no_nl" (or ct:run_test([...,
+	    {logopts,[no_nl]}])). A new framework callback function,
+	    get_logopts/0, has been introduced (see the ct_framework
+	    module for details).</p>
+          <p>
+	    Own Id: OTP-9372 Aux Id: OTP-9396 </p>
+        </item>
+        <item>
+          <p>
+	    A new option, 'logopts', has been introduced, to make it
+	    possible to modify some aspects of the logging behaviour
+	    in Common Test (or Test Server). For example, if the html
+	    version of the test suite source code should not be
+	    generated during the test run (and consequently be
+	    unavailable in the log file system), the feature may be
+	    disabled by means of "ct_run ... -logopts no_src" (or
+	    ct:run_test([..., {logopts,[no_src]}])). A new framework
+	    callback function, get_logopts/0, has been introduced
+	    (see the ct_framework module for details).</p>
+          <p>
+	    Own Id: OTP-9396 Aux Id: seq11869, OTP-9372 </p>
+        </item>
+        <item>
+          <p>
+	    CT Hooks can now be assigned a priority. The priority of
+	    a CTH determines when it should execute in relation to
+	    other CTHs. The CTH with the lowest priority will be
+	    executed first, CTHs with equal priority will be executed
+	    in the order which they were installed.</p>
+          <p>
+	    Own Id: OTP-9445</p>
+        </item>
+        <item>
+          <p>
+	    It is now possible to use a tuple {M,F,A}, or a fun, as
+	    timetrap specification in the suite info function or test
+	    case info functions. The function must return a valid
+	    timeout value, as documented in the common_test man page
+	    and in the User's Guide.</p>
+          <p>
+	    Own Id: OTP-9501 Aux Id: seq11894 </p>
+        </item>
+        <item>
+          <p>
+	    A new built-in common test hook has been added which
+	    captures error_logger and SASL event and prints them in
+	    the testcase log. To disable this (and any other built-in
+	    hooks) pass 'enable_builtin_hooks false' to common test.</p>
+          <p>
+	    Own Id: OTP-9543</p>
+        </item>
+        <item>
+          <p>
+	    Common Test now has the possibility to have built-in
+	    hooks which are started by default when any test is run.
+	    To disable built-in hooks pass 'enable_builtin_hooks
+	    false' to common test. See the common test hooks
+	    documentation for more details.</p>
+          <p>
+	    Own Id: OTP-9564</p>
+        </item>
+      </list>
+    </section>
+
+</section>
+
 <section><title>Common_Test 1.5.4</title>
 
     <section><title>Fixed Bugs and Malfunctions</title>
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index 816aa5b1eb..57059f0ba2 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -128,6 +128,15 @@
     <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -case start stop</c></p>
     <p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -group installation -case start stop</c></p>
     
+    <p>It is also possible to combine the <c>dir</c>, <c>suite</c> and <c>group/case</c> flags. E.g, to run
+    <c>x_SUITE</c> and <c>y_SUITE</c> in directory <c>testdir</c>:</p>
+
+    <p><c>$ ct_run -dir ./testdir -suite x_SUITE y_SUITE</c></p>
+
+    <p>This has the same effect as calling:</p>
+
+    <p><c>$ ct_run -suite ./testdir/x_SUITE ./testdir/y_SUITE</c></p>
+
     <p>Other flags that may be used with <c>ct_run</c>:</p>
     <list>
       <item><c><![CDATA[-logdir <dir>]]></c>, specifies where the HTML log files are to be written.</item>
@@ -167,6 +176,8 @@
       <item><c><![CDATA[-decrypt_file <key_file>]]></c>, points out a file containing a decryption key for 
         <seealso marker="config_file_chapter#encrypted_config_files">encrypted configuration files</seealso>.</item>
       <item><c><![CDATA[-basic_html]]></c>, switches off html enhancements that might not be compatible with older browsers.</item>
+      <item><c><![CDATA[-logopts <opts>]]></c>, makes it possible to modify aspects of the logging behaviour, see
+        <seealso marker="run_test_chapter#logopts">Log options</seealso> below.</item>
     </list>
 
     <note><p>Directories passed to Common Test may have either relative or absolute paths.</p></note>
@@ -324,8 +335,9 @@
        are to be executed by Common Test, and those functions only. If
        the step option <c>config</c> is specified, breakpoints will 
        also be initially set on the configuration functions in the suite, i.e.
-       <c>init_per_suite/1</c>, <c>end_per_suite/1</c>, <c>init_per_testcase/2</c> 
-       and <c>end_per_testcase/2</c>.</p>
+       <c>init_per_suite/1</c>, <c>end_per_suite/1</c>,
+       <c>init_per_group/2</c>, <c>end_per_group/2</c>,
+       <c>init_per_testcase/2</c> and <c>end_per_testcase/2</c>.</p>
     <p>Common Test enables the Debugger auto attach feature, which means
        that for every new interpreted test case function that starts to execute, 
        a new trace window will automatically pop up. (This is because each test 
@@ -652,6 +664,30 @@
 	to follow test progress simply by refreshing pages in the HTML browser.
 	Statistics totals are not presented until a test is complete however.</p>
 
+	<section>
+	  <marker id="logopts"></marker>
+	  <title>Log options</title>
+	  <p>With the <c>logopts</c> start flag, it's possible to specify
+	  options that modify some aspects of the logging behaviour.
+	  Currently, the following options are available:</p>
+	  <list>
+	    <item><c>no_src</c></item>
+	    <item><c>no_nl</c></item>
+	  </list>
+	  <p>With <c>no_src</c>, the html version of the test suite source
+	  code will not be generated during the test run (and consequently
+	  not be available in the log file system).</p>
+	  <p>With <c>no_nl</c>, Common Test will not add a newline character
+	  (\n) to the end of an output string that it receives from a call to e.g.
+	  <c>io:format/2</c>, and which it prints to the test case log.</p>
+	  <p>For example, if a test is started with:</p>
+	  <p><c>$ ct_run -suite my_SUITE -logopts no_src</c></p>
+	  <p>then printouts during the test made by successive calls to <c>io:format("x")</c>,
+	  will appear in the test case log as:</p>
+	  <p><c>xxx</c></p>
+	  <p>instead of each <c>x</c> printed on a new line, which is the default behaviour.</p>
+	</section>
+
       </section>
   
       <section>
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 3f9fdb7121..e35888e68f 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -280,6 +280,8 @@
 	    the timetrap time is exceeded, the test case fails with
 	    reason <c>timetrap_timeout</c>. Note that <c>init_per_testcase</c> 
 	    and <c>end_per_testcase</c> are included in the timetrap time.
+	    Please see the <seealso marker="write_test_chapter#timetraps">Timetrap</seealso>
+	    section for more details.
 	  </p>
 	</item>
 	<tag><em><c>userdata</c></em></tag>
@@ -699,8 +701,8 @@
   </section>
 
   <section>
-    <title>Timetrap timeouts</title>
     <marker id="timetraps"></marker>
+    <title>Timetrap timeouts</title>
     <p>The default time limit for a test case is 30 minutes, unless a
       <c>timetrap</c> is specified either by the suite info function
       or a test case info function. The timetrap timeout value defined
@@ -723,6 +725,13 @@
       multipled by <c>multiply_timetraps</c>, and possibly scaled up if
       <c>scale_timetraps</c> is enabled, the function <c>ct:sleep/1</c>
       may be called.</p>
+    <p>A function (<c>fun</c> or <c>MFA</c>) may be specified as timetrap value
+      in the suite- and test case info function, e.g:</p>
+      <p><c>{timetrap,{test_utils,get_timetrap_value,[?MODULE,system_start]}}</c></p>
+      <p>The function will be called initially by Common Test (before execution
+	of the suite or the test case) and must return a time value such as an
+	integer (millisec), or a <c>{SecMinOrHourTag,Time}</c> tuple. More
+	information can be found in the <c>common_test</c> reference manual.</p>
   </section>
 
   <section>
@@ -818,6 +827,3 @@
     </list>
   </section>
 </chapter>
-
-
-