Document changes in the CT hooks API and the event message protocol

OTP-11732

4 files changed, 56 insertions, 36 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/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/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/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>