From 6a5c264882058cf0786aba4418079b8552eea1cb Mon Sep 17 00:00:00 2001
From: Peter Andersson <peppe@erlang.org>
Date: Wed, 2 Apr 2014 02:11:43 +0200
Subject: Document changes in the CT hooks API and the event message protocol

OTP-11732
---
 lib/common_test/doc/src/ct_hooks.xml | 50 +++++++++++++++++++++---------------
 1 file changed, 30 insertions(+), 20 deletions(-)

(limited to 'lib/common_test/doc/src/ct_hooks.xml')

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
-- 
cgit v1.2.3