Merge branch 'peppe/common_test/otp_17_doc'

* peppe/common_test/otp_17_doc:
  Document the abort_if_missing_suites functionality
  Document changes in the CT hooks API and the event message protocol
  Document new ct_telnet logging features

11 files changed, 171 insertions, 129 deletions

diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml
index 859ff9df14..cab6dfea51 100644
--- a/lib/common_test/doc/src/ct_hooks.xml
+++ b/lib/common_test/doc/src/ct_hooks.xml
@@ -450,12 +450,15 @@
     </func>
 
     <func>
-      <name>Module:on_tc_fail(TestcaseName, Reason, CTHState) -&gt; 
+      <name>Module:on_tc_fail(TestName, Reason, CTHState) -&gt; 
               NewCTHState</name>
       <fsummary>Called after the CTH scope ends</fsummary>
       <type>
-	<v>TestcaseName = init_per_suite | end_per_suite | 
-	                  init_per_group | end_per_group | atom()</v>
+	<v>TestName = init_per_suite | end_per_suite |
+                      {init_per_group,GroupName} | {end_per_group,GroupName} |
+                      {FuncName,GroupName} | FuncName</v>
+	<v>FuncName = atom()</v>
+	<v>GroupName = atom()</v>
 	<v>Reason = term()</v>
 	<v>CTHState = NewCTHState = term()</v>
       </type>
@@ -463,14 +466,16 @@
       <desc>	
 	<p> OPTIONAL </p>
 
-	<p>This function is called whenever a testcase fails. 
-	It is called after the post function has been called for 
-	the testcase which failed. i.e. 
-	if init_per_suite fails this function is called after 
+	<p>This function is called whenever a test case (or config function)
+	  fails. It is called after the post function has been called for 
+	  the failed test case. I.e. if init_per_suite fails, this function
+	  is called after 
 	<seealso marker="#Module:post_init_per_suite-4">
-	  post_init_per_suite</seealso>, and if a testcase fails it is called 
+	  post_init_per_suite</seealso>, and if a test case fails, it is called 
 	  after <seealso marker="#Module:post_end_per_testcase-4">
-	  post_end_per_testcase</seealso>.</p>
+	  post_end_per_testcase</seealso>. If the failed test case belongs
+	  to a test case group, the first argument is a tuple
+	  <c>{FuncName,GroupName}</c>, otherwise simply the function name.</p>
 
 	<p>The data which comes with the Reason follows the same format as the
 	<seealso marker="event_handler_chapter#failreason">FailReason
@@ -481,12 +486,14 @@
     </func>
 
     <func>
-      <name>Module:on_tc_skip(TestcaseName, Reason, CTHState) -&gt; 
+      <name>Module:on_tc_skip(TestName, Reason, CTHState) -&gt; 
               NewCTHState</name>
       <fsummary>Called after the CTH scope ends</fsummary>
       <type>
-	<v>TestcaseName = end_per_suite | {init_per_group,GroupName} | 
-                          {end_per_group,GroupName} | atom()</v>
+	<v>TestName = init_per_suite | end_per_suite |
+                      {init_per_group,GroupName} | {end_per_group,GroupName} |
+                      {FuncName,GroupName} | FuncName</v>
+	<v>FuncName = atom()</v>
 	<v>GroupName = atom()</v>
 	<v>Reason = {tc_auto_skip | tc_user_skip, term()}</v>
 	<v>CTHState = NewCTHState = term()</v>
@@ -495,14 +502,17 @@
       <desc>	
 	<p> OPTIONAL </p>
 
-	<p>This function is called whenever a testcase is skipped. 
-	It is called after the post function has been called for the 
-	testcase which was skipped. 
-	i.e. if init_per_group is skipped this function is called after 
-	<seealso marker="#Module:post_init_per_suite-4">post_init_per_group
-	</seealso>, and if a testcase is skipped it is called after 
-	<seealso marker="#Module:post_end_per_testcase-4">post_end_per_testcase
-	</seealso>.</p>
+	<p>This function is called whenever a test case (or config function)
+	  is skipped. It is called after the post function has been called
+	  for the skipped test case. I.e. if init_per_group is skipped, this
+	  function is called after 
+	  <seealso marker="#Module:post_init_per_group-4">
+	    post_init_per_group</seealso>, and if a test case is skipped,
+	  it is called after 
+	<seealso marker="#Module:post_end_per_testcase-4">
+	  post_end_per_testcase</seealso>. If the skipped test case belongs to a
+	test case group, the first argument is a tuple <c>{FuncName,GroupName}</c>,
+	otherwise simply the function name.</p>
 
 	<p>The data which comes with the Reason follows the same format as 
 	<seealso marker="event_handler_chapter#tc_auto_skip">tc_auto_skip
diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index 39259b092a..d8e79ca80e 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -108,6 +108,7 @@
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-abort_if_missing_suites]
 	[-muliply_timetraps Multiplier]
 	[-scale_timetraps]
 	[-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
@@ -144,6 +145,7 @@
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-abort_if_missing_suites]
 	[-muliply_timetraps Multiplier]
 	[-scale_timetraps]
 	[-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
@@ -171,6 +173,7 @@
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-abort_if_missing_suites]
 	[-muliply_timetraps Multiplier]
 	[-scale_timetraps]
 	[-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml
index 47d0ba59fb..45f01c12ec 100644
--- a/lib/common_test/doc/src/event_handler_chapter.xml
+++ b/lib/common_test/doc/src/event_handler_chapter.xml
@@ -227,11 +227,13 @@
 
       <item>
 	<marker id="tc_auto_skip"></marker>
-        <c>#event{name = tc_auto_skip, data = {Suite,Func,Reason}}</c>
+        <c>#event{name = tc_auto_skip, data = {Suite,TestName,Reason}}</c>
         <p><c>Suite = atom()</c>, the name of the suite.</p>
-        <p><c>Func = atom() | {end_per_group,GroupName}</c>, the name of the test case
-	  or configuration function.</p>
-        <p><c>GroupName = atom()</c>, name of the group.</p>
+        <p><c>TestName = init_per_suite | end_per_suite |
+	                 {init_per_group,GroupName} | {end_per_group,GroupName} |
+	                 {FuncName,GroupName} | FuncName</c></p>
+	<p><c>FuncName = atom()</c>, the name of the test case or configuration function.</p>
+        <p><c>GroupName = atom()</c>, the name of the test case group.</p>
         <p><c>Reason = {failed,FailReason} |
 	               {require_failed_in_suite0,RequireInfo}</c>, 
 	      reason for auto skipping <c>Func</c>.</p>
@@ -252,21 +254,26 @@
 	<c>init_per_group</c>, a failed <c>require</c> in <c>suite/0</c>, or a failed test case
 	in a sequence. Note that this event is never received as a result of a test case getting
 	skipped because of <c>init_per_testcase</c> failing, since that information is carried with
-	the <c>tc_done</c> event.
+	the <c>tc_done</c> event. If a failed test case belongs	to a test case group, the second
+	data element is a tuple <c>{FuncName,GroupName}</c>, otherwise simply the function name.
 	</p></item>
-	
+
       <item>
 	<marker id="tc_user_skip"></marker>
-        <c>#event{name = tc_user_skip, data = {Suite,Func,Comment}}</c>
+        <c>#event{name = tc_user_skip, data = {Suite,TestName,Comment}}</c>
         <p><c>Suite = atom()</c>, the name of the suite.</p>
-        <p><c>Func = atom() | {end_per_group,GroupName}</c>, the name of the test case
-	  or configuration function.</p>
-        <p><c>GroupName = atom()</c>, name of the group.</p>
+        <p><c>TestName = init_per_suite | end_per_suite |
+	                 {init_per_group,GroupName} | {end_per_group,GroupName} |
+	                 {FuncName,GroupName} | FuncName</c></p>
+	<p><c>FuncName = atom()</c>, the name of the test case or configuration function.</p>
+        <p><c>GroupName = atom()</c>, the name of the test case group.</p>
         <p><c>Comment = string()</c>, reason for skipping the test case.</p>
         <p>This event specifies that a test case has been skipped by the user. 
 	It is only ever received if the skip was declared in a test specification. 
 	Otherwise, user skip information is received as a <c>{skipped,SkipReason}</c> 
-	result in the <c>tc_done</c> event for the test case.
+	result in the <c>tc_done</c> event for the test case. If a skipped test case belongs
+	to a test case group, the second data element is a tuple <c>{FuncName,GroupName}</c>,
+	otherwise simply the function name.
 	</p></item>
 
       <item><c>#event{name = test_stats, data = {Ok,Failed,Skipped}}</c>
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index ef21948f89..864f82cb63 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -59,7 +59,15 @@
     <p>If compilation should fail for one or more suites, the compilation errors
       are printed to tty and the operator is asked if the test run should proceed
       without the missing suites, or be aborted. If the operator chooses to proceed, 
-      it is noted in the HTML log which tests have missing suites.</p>
+      it is noted in the HTML log which tests have missing suites. If Common Test is
+      unable to prompt the user after compilation failure (if Common Test doesn't
+      control stdin), the test run will proceed automatically without the missing
+      suites. This behaviour can however be modified with the
+      <c><![CDATA[ct_run]]></c> flag <c><![CDATA[-abort_if_missing_suites]]></c>, 
+      or the <c><![CDATA[ct:run_test/1]]></c> option
+      <c><![CDATA[{abort_if_missing_suites,TrueOrFalse}]]></c>. If 
+      <c><![CDATA[abort_if_missing_suites]]></c> is set (to true), the test run
+      will stop immediately if some suites fail to compile.</p>
 
     <p>Any help module (i.e. regular Erlang module with name not ending with
       "_SUITE") that resides in the same test object directory as a suite 
@@ -167,6 +175,7 @@
         <seealso marker="ct_hooks_chapter#builtin_cths">Built-in Common Test Hooks</seealso>. Default is <c>true</c>.</item>
       <item><c><![CDATA[-include]]></c>, specifies include directories (see above).</item>
       <item><c><![CDATA[-no_auto_compile]]></c>, disables the automatic test suite compilation feature (see above).</item>
+      <item><c><![CDATA[-abort_if_missing_suites]]></c>, aborts the test run if one or more suites fail to compile (see above).</item>
       <item><c><![CDATA[-multiply_timetraps <n>]]></c>, extends <seealso marker="write_test_chapter#timetraps">timetrap
 	  timeout</seealso> values.</item>
       <item><c><![CDATA[-scale_timetraps <bool>]]></c>, enables automatic <seealso marker="write_test_chapter#timetraps">timetrap
@@ -744,6 +753,9 @@
 	{auto_compile, Bool},
 	{auto_compile, NodeRefs, Bool},
 	
+	{abort_if_missing_suites, Bool},
+	{abort_if_missing_suites, NodeRefs, Bool},
+
 	{config, ConfigFiles}.
 	{config, ConfigDir, ConfigBaseNames}.
 	{config, NodeRefs, ConfigFiles}.
diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index e6732f7fc7..241cd928b7 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -150,7 +150,8 @@ run(TestDirs) ->
 %%%               {silent_connections,Conns} | {stylesheet,CSSFile} |
 %%%               {cover,CoverSpecFile} | {cover_stop,Bool} | {step,StepOpts} |
 %%%               {event_handler,EventHandlers} | {include,InclDirs} |
-%%%               {auto_compile,Bool} | {create_priv_dir,CreatePrivDir}  |
+%%%               {auto_compile,Bool} | {abort_if_missing_suites,Bool} |
+%%%               {create_priv_dir,CreatePrivDir}  |
 %%%               {multiply_timetraps,M} | {scale_timetraps,Bool} |
 %%%               {repeat,N} | {duration,DurTime} | {until,StopTime} |
 %%%               {force_stop,ForceStop} | {decrypt,DecryptKeyOrFile} |
diff --git a/lib/common_test/src/ct_framework.erl b/lib/common_test/src/ct_framework.erl
index 7d577462b0..9ef917a507 100644
--- a/lib/common_test/src/ct_framework.erl
+++ b/lib/common_test/src/ct_framework.erl
@@ -1274,7 +1274,7 @@ report(What,Data) ->
 	    ct_util:set_testdata({What,Data}),
 	    ok;
 	tc_start ->
-	    %% Data = {Suite,{Func,GroupName}},LogFileName}
+	    %% Data = {{Suite,{Func,GroupName}},LogFileName}
 	    Data1 = case Data of
 			{{Suite,{Func,undefined}},LFN} -> {{Suite,Func},LFN};
 			_ -> Data
diff --git a/lib/common_test/src/ct_telnet.erl b/lib/common_test/src/ct_telnet.erl
index bc22a99741..c9dc2338cd 100644
--- a/lib/common_test/src/ct_telnet.erl
+++ b/lib/common_test/src/ct_telnet.erl
@@ -46,100 +46,80 @@
 %%
 %% == Logging ==
 %%
-%% `ct_telnet' can be configured to uses the `error_logger' for logging telnet
-%% traffic. A special purpose error handler is implemented in
-%% `ct_conn_log_h'. To use this error handler, add the `cth_conn_log'
-%% hook in your test suite, e.g:
-%%
+%% The default logging behaviour of `ct_telnet' is to print information
+%% to the test case HTML log about performed operations and commands
+%% and their corresponding results. What won't be printed to the HTML log
+%% are text strings sent from the telnet server that are not explicitly
+%% received by means of a `ct_telnet' function such as `expect/3'.
+%% `ct_telnet' may however be configured to use a special purpose event handler,
+%% implemented in `ct_conn_log_h', for logging <b>all</b> telnet traffic.
+%% To use this handler, you need to install a Common Test hook named
+%% `cth_conn_log'. Example (using the test suite info function):
 %%
 %% ```
 %% suite() ->
-%%    [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
-%%'''
+%%     [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
+%% '''
 %%
 %% `conn_mod()' is the name of the common_test module implementing
 %% the connection protocol, i.e. `ct_telnet'.
 %%
-%% The hook option `log_type' specifies the type of logging:
-%%
-%% <dl>
-%%   <dt>`raw'</dt>
-%%   <dd>The sent and received telnet data is logged to a separate
-%%   text file as is, without any formatting. A link to the file is
-%%   added to the test case HTML log.</dd>
+%% The `cth_conn_log' hook performs unformatted logging of telnet data to
+%% a separate text file. All telnet communication is captured and printed,
+%% including arbitrary data sent from the server. The link to this text file
+%% can be found on the top of the test case HTML log.
 %%
-%%   <dt>`html (default)'</dt>
-%%   <dd>The sent and received telnet traffic is pretty printed
-%%   directly in the test case HTML log.</dd>
-%%
-%%   <dt>`silent'</dt>
-%%   <dd>Telnet traffic is not logged.</dd>
-%% </dl>
-%%
-%% By default, all telnet traffic is logged in one single log
-%% file. However, it is possible to have different connections logged
-%% in separate files. To do this, use the hook option `hosts' and
-%% list the names of the servers/connections that will be used in the
-%% suite. Note that the connections must be named for this to work
+%% By default, data for all telnet connections is logged in one common
+%% file (named `default'), which might get messy e.g. if multiple telnet
+%% sessions are running in parallel. It is therefore possible to create a
+%% separate log file for each connection. To configure this, use the hook
+%% option `hosts' and list the names of the servers/connections that will be
+%% used in the suite. Note that the connections must be named for this to work
 %% (see the `open' function below).
 %%
-%% The `hosts' option has no effect if `log_type' is set to `html' or
-%% `silent'.
+%% The hook option named `log_type' may be used to change the `cth_conn_log'
+%% behaviour. The default value of this option is `raw', which results in the
+%% behaviour described above. If the value is set to `html', all telnet
+%% communication is printed to the test case HTML log instead.
 %%
-%% The hook options can also be specified in a configuration file with
-%% the configuration variable `ct_conn_log':
+%% All `cth_conn_log' hook options described above can also be specified in
+%% a configuration file with the configuration variable `ct_conn_log'. Example:
 %%
 %% ```
-%% {ct_conn_log,[{conn_mod(),hook_options()}]}.
-%% '''
-%%
-%% For example:
-%%
-%% ```
-%% {ct_conn_log,[{ct_telnet,[{log_type,raw},
-%%                           {hosts,[key_or_name()]}]}]}
+%% {ct_conn_log, [{ct_telnet,[{log_type,raw},
+%%                            {hosts,[key_or_name()]}]}]}
 %% '''
 %%
 %% <b>Note</b> that hook options specified in a configuration file
-%% will overwrite any hardcoded hook options in the test suite.
+%% will overwrite any hardcoded hook options in the test suite!
 %%
-%% === Logging example 1 ===
+%% === Logging example ===
 %%
-%% The following `ct_hooks' statement will cause raw printing of
-%% telnet traffic to separate logs for the connections named
-%% `server1' and `server2'. Any other connections will be logged
-%% to default telnet log.
+%% The following `ct_hooks' statement will cause printing of telnet traffic
+%% to separate logs for the connections named `server1' and `server2'.
+%% Traffic for any other connections will be logged in the default telnet log.
 %%
 %% ```
 %% suite() ->
-%%    [{ct_hooks, [{cth_conn_log, [{ct_telnet,[{log_type,raw}},
-%%                                             {hosts,[server1,server2]}]}
-%%                                ]}]}].
+%%     [{ct_hooks,
+%%       [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].
 %%'''
 %%
-%% === Logging example 2 ===
-%%
-%% The following configuration file will cause raw logging of all
-%% telnet traffic into one single text file.
+%% As previously explained, the above specification could also be provided
+%% by means of an entry like this in a configuration file:
 %%
 %% ```
-%% {ct_conn_log,[{ct_telnet,[{log_type,raw}]}]}.
+%% {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.
 %% '''
 %%
-%% The `ct_hooks' statement must look like this:
+%% in which case the `ct_hooks' statement in the test suite may simply look
+%% like this:
 %%
 %% ```
 %% suite() ->
-%%    [{ct_hooks, [{cth_conn_log, []}]}].
+%%     [{ct_hooks, [{cth_conn_log, []}]}].
 %% '''
 %%
-%% The same `ct_hooks' statement without the configuration file would
-%% cause HTML logging of all telnet connections into the test case
-%% HTML log.
-%%
-%% <b>Note</b> that if the `cth_conn_log' hook is not added, telnet
-%% traffic is still logged in the test case HTML log file (on the legacy
-%% `ct_telnet' format).
 %% @end
 
 %% @type connection_type() = telnet | ts1 | ts2
@@ -205,6 +185,7 @@ open(Name) ->
 %%%      Name = target_name()
 %%%      ConnType = ct_telnet:connection_type()
 %%%      Handle = ct_telnet:handle()
+%%%      Reason = term()
 %%%
 %%% @doc Open a telnet connection to the specified target host.
 open(Name,ConnType) ->
@@ -234,6 +215,7 @@ open(KeyOrName,ConnType,TargetMod) ->
 %%%      TargetMod = atom()
 %%%      Extra = term()
 %%%      Handle = handle()
+%%%      Reason = term()
 %%%
 %%% @doc Open a telnet connection to the specified target host.
 %%%
@@ -295,7 +277,8 @@ open(KeyOrName,ConnType,TargetMod,Extra) ->
 
 %%%-----------------------------------------------------------------
 %%% @spec close(Connection) -> ok | {error,Reason}
-%%%       Connection = ct_telnet:connection()
+%%%      Connection = ct_telnet:connection()
+%%%      Reason = term()
 %%%
 %%% @doc Close the telnet connection and stop the process managing it.
 %%% 
@@ -330,6 +313,7 @@ cmd(Connection,Cmd) ->
 %%%      Cmd = string()
 %%%      Timeout = integer()
 %%%      Data = [string()]
+%%%      Reason = term()
 %%% @doc Send a command via telnet and wait for prompt.
 cmd(Connection,Cmd,Timeout) ->
     case get_handle(Connection) of
@@ -350,6 +334,7 @@ cmdf(Connection,CmdFormat,Args) ->
 %%%      Args = list()
 %%%      Timeout = integer()
 %%%      Data = [string()]
+%%%      Reason = term()
 %%% @doc Send a telnet command and wait for prompt 
 %%%      (uses a format string and list of arguments to build the command).
 cmdf(Connection,CmdFormat,Args,Timeout) when is_list(Args) ->
@@ -360,6 +345,7 @@ cmdf(Connection,CmdFormat,Args,Timeout) when is_list(Args) ->
 %%% @spec get_data(Connection) -> {ok,Data} | {error,Reason}
 %%%      Connection = ct_telnet:connection()
 %%%      Data = [string()]
+%%%      Reason = term()
 %%% @doc Get all data which has been received by the telnet client
 %%% since last command was sent.
 get_data(Connection) ->
@@ -374,6 +360,7 @@ get_data(Connection) ->
 %%% @spec send(Connection,Cmd) -> ok | {error,Reason}
 %%%      Connection = ct_telnet:connection()
 %%%      Cmd = string()
+%%%      Reason = term()
 %%% @doc Send a telnet command and return immediately.
 %%%
 %%% <p>The resulting output from the command can be read with
@@ -391,6 +378,7 @@ send(Connection,Cmd) ->
 %%%      Connection = ct_telnet:connection()
 %%%      CmdFormat = string()
 %%%      Args = list()
+%%%      Reason = term()
 %%% @doc Send a telnet command and return immediately (uses a format
 %%% string and a list of arguments to build the command).
 sendf(Connection,CmdFormat,Args) when is_list(Args) ->
@@ -765,8 +753,8 @@ check_if_prompt_was_reached(Data,_) when is_list(Data) ->
 check_if_prompt_was_reached(_,_) ->
     false.
 
-%%% @hidden
-%% Functions for logging ct_telnet reports and telnet data 
+%%%-----------------------------------------------------------------
+%%% Functions for logging ct_telnet reports and telnet data 
 
 heading(Action,undefined) ->
     io_lib:format("~w ~w",[?MODULE,Action]);
@@ -776,6 +764,8 @@ heading(Action,Name) ->
 force_log(State,Action,String,Args) ->
     log(State,Action,String,Args,true).
 
+%%%-----------------------------------------------------------------
+%%% @hidden
 log(State,Action,String,Args) when is_record(State, state) ->
     log(State,Action,String,Args,false);
 log(Name,Action,String,Args) when is_atom(Name) ->
@@ -783,6 +773,8 @@ log(Name,Action,String,Args) when is_atom(Name) ->
 log(TelnPid,Action,String,Args) when is_pid(TelnPid) ->
     log(#state{teln_pid=TelnPid},Action,String,Args,false).
 
+%%%-----------------------------------------------------------------
+%%% @hidden
 log(undefined,String,Args) ->
     log(#state{},undefined,String,Args,false);
 log(Name,String,Args) when is_atom(Name) ->
@@ -790,6 +782,8 @@ log(Name,String,Args) when is_atom(Name) ->
 log(TelnPid,String,Args) when is_pid(TelnPid) ->
     log(#state{teln_pid=TelnPid},undefined,String,Args).
 
+%%%-----------------------------------------------------------------
+%%% @hidden
 log(#state{name=Name,teln_pid=TelnPid,host=Host,port=Port},
     Action,String,Args,ForcePrint) ->
     Name1 = if Name == undefined -> get({ct_telnet_pid2name,TelnPid});
@@ -839,6 +833,8 @@ log(#state{name=Name,teln_pid=TelnPid,host=Host,port=Port},
 	    end
     end.
 
+%%%-----------------------------------------------------------------
+%%% @hidden
 start_gen_log(Heading) ->
     %% check if output is suppressed
     case ct_util:is_silenced(telnet) of
@@ -846,6 +842,8 @@ start_gen_log(Heading) ->
 	false -> ct_gen_conn:start_log(Heading)
     end.
 
+%%%-----------------------------------------------------------------
+%%% @hidden
 end_gen_log() -> 
     %% check if output is suppressed
     case ct_util:is_silenced(telnet) of
diff --git a/lib/common_test/src/cth_conn_log.erl b/lib/common_test/src/cth_conn_log.erl
index 0e6c877c5d..1e60f2751e 100644
--- a/lib/common_test/src/cth_conn_log.erl
+++ b/lib/common_test/src/cth_conn_log.erl
@@ -91,12 +91,15 @@ merge_log_info([{Mod,ConfOpts}|ConfList],HookList) ->
 	    {value,{_,HookOpts},HL1} ->
 		{ConfOpts ++ HookOpts, HL1} % ConfOpts overwrites HookOpts!
 	end,
-    [{Mod,get_log_opts(Opts)} | merge_log_info(ConfList,HookList1)];
+    [{Mod,get_log_opts(Mod,Opts)} | merge_log_info(ConfList,HookList1)];
 merge_log_info([],HookList) ->
-    [{Mod,get_log_opts(Opts)} || {Mod,Opts} <- HookList].
+    [{Mod,get_log_opts(Mod,Opts)} || {Mod,Opts} <- HookList].
 
-get_log_opts(Opts) ->
-    LogType = proplists:get_value(log_type,Opts,html),
+get_log_opts(Mod,Opts) ->
+    DefaultLogType = if Mod == ct_telnet -> raw;
+			true -> html
+		     end,
+    LogType = proplists:get_value(log_type,Opts,DefaultLogType),
     Hosts = proplists:get_value(hosts,Opts,[]),
     {LogType,Hosts}.
 
diff --git a/lib/common_test/src/unix_telnet.erl b/lib/common_test/src/unix_telnet.erl
index b05386a5ab..10666b979d 100644
--- a/lib/common_test/src/unix_telnet.erl
+++ b/lib/common_test/src/unix_telnet.erl
@@ -17,8 +17,8 @@
 %% %CopyrightEnd%
 %%
 
-%%% @doc Callback module for ct_telnet for talking telnet
-%%% to a unix host.
+%%% @doc Callback module for ct_telnet, for connecting to a telnet
+%%% server on a unix host.
 %%% 
 %%% <p>It requires the following entry in the config file:</p>
 %%% <pre>
@@ -28,15 +28,15 @@
 %%%        {password,Password},
 %%%        {keep_alive,Bool}]}.            % optional</pre>
 %%%
-%%% <p>To talk telnet to the host specified by
+%%% <p>To communicate via telnet to the host specified by
 %%% <code>HostNameOrIpAddress</code>, use the interface functions in
-%%% <code>ct</code>, e.g. <code>open(Name), cmd(Name,Cmd), ...</code>.</p>
+%%% <code>ct_telnet</code>, e.g. <code>open(Name), cmd(Name,Cmd), ...</code>.</p>
 %%%
 %%% <p><code>Name</code> is the name you allocated to the unix host in
 %%% your <code>require</code> statement. E.g.</p>
-%%% <pre>   suite() -> [{require,Name,{unix,[telnet,username,password]}}].</pre>
+%%% <pre>   suite() -> [{require,Name,{unix,[telnet]}}].</pre>
 %%% <p>or</p>
-%%% <pre>   ct:require(Name,{unix,[telnet,username,password]}).</pre>
+%%% <pre>   ct:require(Name,{unix,[telnet]}).</pre>
 %%%
 %%% <p>The "keep alive" activity (i.e. that Common Test sends NOP to the server
 %%% every 10 seconds if the connection is idle) may be enabled or disabled for one 
@@ -62,20 +62,18 @@
 -define(prx,"login: |Password: |\\\$ |> ").
 
 %%%-----------------------------------------------------------------
-%%% @hidden
 %%% @spec get_prompt_regexp() -> PromptRegexp
 %%%      PromptRegexp = ct_telnet:prompt_regexp()
 %%%
 %%% @doc Callback for ct_telnet.erl.
 %%%
-%%% <p>Return the prompt regexp for telnet connections to the
-%%% interwatch instrument.</p>
+%%% <p>Return a suitable regexp string that will match common
+%%% prompts for users on unix hosts.</p>
 get_prompt_regexp() ->
     ?prx.
 
 
 %%%-----------------------------------------------------------------
-%%% @hidden
 %%% @spec connect(ConnName,Ip,Port,Timeout,KeepAlive,Extra) -> 
 %%%   {ok,Handle} | {error,Reason}
 %%%      ConnName = ct:target_name()
@@ -83,14 +81,15 @@ get_prompt_regexp() ->
 %%%      Port = integer()
 %%%      Timeout = integer()
 %%%      KeepAlive = bool()
-%%%      Extra = {Username,Password}
+%%%      Extra = ct:target_name() | {Username,Password}
 %%%      Username = string()
 %%%      Password = string()
 %%%      Handle = ct_telnet:handle()
+%%%      Reason = term()
 %%%
 %%% @doc Callback for ct_telnet.erl.
 %%%
-%%% <p>Setup telnet connection to a UNIX host.</p>
+%%% <p>Setup telnet connection to a unix host.</p>
 connect(ConnName,Ip,Port,Timeout,KeepAlive,Extra) ->
     case Extra of
 	{Username,Password} -> 
diff --git a/lib/common_test/test/ct_telnet_SUITE.erl b/lib/common_test/test/ct_telnet_SUITE.erl
index f5cff76fd1..84e69c2b54 100644
--- a/lib/common_test/test/ct_telnet_SUITE.erl
+++ b/lib/common_test/test/ct_telnet_SUITE.erl
@@ -180,14 +180,20 @@ telnet_config(unix_telnet, legacy) ->
      {ct_conn_log,[]}];
 %% LogType same as GroupName
 telnet_config(unix_telnet, LogType) ->
+    LogTypeTerm = if LogType == raw -> [];
+		     true -> [{log_type,LogType}]
+		  end,
     [{unix, ct:get_config(unix)},
      {ct_conn_log,
-      [{ct_telnet,[{log_type,LogType},
-		   {hosts,[telnet_server_conn1,
-			   telnet_server_conn2,
-			   telnet_server_conn3,
-			   telnet_server_conn4]}]}]}];
+      [{ct_telnet, LogTypeTerm ++
+	    [{hosts,[telnet_server_conn1,
+		     telnet_server_conn2,
+		     telnet_server_conn3,
+		     telnet_server_conn4]}]}]}];
 telnet_config(_, LogType) ->
+    LogTypeTerm = if LogType == raw -> [];
+		     true -> [{log_type,LogType}]
+		  end,
     [{unix,[{telnet,"localhost"},
 	    {port, ?erl_telnet_server_port},
 	    {username,?erl_telnet_server_user},
@@ -202,11 +208,11 @@ telnet_config(_, LogType) ->
 	     [{ct_conn_log,[]}];
 	true ->
 	     [{ct_conn_log,
-	       [{ct_telnet,[{log_type,LogType},
-			    {hosts,[telnet_server_conn1,
-				    telnet_server_conn2,
-				    telnet_server_conn3,
-				    telnet_server_conn4]}]}]}]
+	       [{ct_telnet, LogTypeTerm ++
+		     [{hosts,[telnet_server_conn1,
+			      telnet_server_conn2,
+			      telnet_server_conn3,
+			      telnet_server_conn4]}]}]}]
      end].
 
 %%%-----------------------------------------------------------------
diff --git a/lib/test_server/doc/src/test_server_ctrl.xml b/lib/test_server/doc/src/test_server_ctrl.xml
index f4aae724e0..0cda531716 100644
--- a/lib/test_server/doc/src/test_server_ctrl.xml
+++ b/lib/test_server/doc/src/test_server_ctrl.xml
@@ -773,11 +773,14 @@ test_server_ctrl:cross_cover_analyse(Level,[{s1,S1LogDir},{s2,S2LogDir}])
         <p><c>What = tests_start, Data = {Name,NumCases}</c><br></br>
 	   <c>What = loginfo, Data = [{topdir,TestRootDir},{rundir,CurrLogDir}]</c><br></br>
 	   <c>What = tests_done, Data = {Ok,Failed,{UserSkipped,AutoSkipped}}</c><br></br>
-	   <c>What = tc_start, Data = {{Mod,Func},TCLogFile}</c><br></br>
-	   <c>What = tc_done, Data = {Mod,Func,Result}</c><br></br>
-	   <c>What = tc_user_skip, Data = {Mod,Func,Comment}</c><br></br>
-	   <c>What = tc_auto_skip, Data = {Mod,Func,Comment}</c><br></br>
+	   <c>What = tc_start, Data = {{Mod,{Func,GroupName}},TCLogFile}</c><br></br>
+	   <c>What = tc_done, Data = {Mod,{Func,GroupName},Result}</c><br></br>
+	   <c>What = tc_user_skip, Data = {Mod,{Func,GroupName},Comment}</c><br></br>
+	   <c>What = tc_auto_skip, Data = {Mod,{Func,GroupName},Comment}</c><br></br>
 	   <c>What = framework_error, Data = {{FWMod,FWFunc},Error}</c></p>
+	<p>Note that for a test case function that doesn't belong to a group,
+	  <c>GroupName</c> has value <c>undefined</c>, otherwise the name of the test
+	  case group.</p>
       </desc>
     </func>
     <func>