Document that CTHs can get fail/skip as Config

OTP-10077

2 files changed, 20 insertions, 7 deletions

diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml
index b98c04a850..b3e713c77f 100644
--- a/lib/common_test/doc/src/ct_hooks.xml
+++ b/lib/common_test/doc/src/ct_hooks.xml
@@ -5,7 +5,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2010</year><year>2011</year>
+      <year>2010</year><year>2012</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -111,11 +111,12 @@
     </func>
 
     <func>
-      <name>Module:pre_init_per_suite(SuiteName, Config, CTHState) -&gt; 
+      <name>Module:pre_init_per_suite(SuiteName, InitData, CTHState) -&gt;
               Result</name>
       <fsummary>Called before init_per_suite</fsummary>
       <type>
 	<v>SuiteName = atom()</v>
+	<v>InitData = Config | SkipOrFail</v>
 	<v>Config = NewConfig = [{Key,Value}]</v>
 	<v>CTHState = NewCTHState = term()</v>
 	<v>Result = {Return, NewCTHState}</v>
@@ -140,7 +141,8 @@
 	
 	<p><c>SuiteName</c> is the name of the suite to be run.</p>
 
-	<p><c>Config</c> is the original config list of the test suite.</p>
+	<p><c>InitData</c> is the original config list of the test suite, or
+	a <c>SkipOrFail</c> tuple if a previous CTH has returned this.</p>
 
 	<p><c>CTHState</c> is the current internal state of the CTH.</p>
 
@@ -212,11 +214,12 @@
     </func>
     
     <func>
-      <name>Module:pre_init_per_group(GroupName, Config, CTHState) -&gt; 
+      <name>Module:pre_init_per_group(GroupName, InitData, CTHState) -&gt;
               Result</name>
       <fsummary>Called before init_per_group</fsummary>
       <type>
 	<v>GroupName = atom()</v>
+	<v>InitData = Config | SkipOrFail</v>
 	<v>Config = NewConfig = [{Key,Value}]</v>
 	<v>CTHState = NewCTHState = term()</v>
 	<v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
@@ -269,11 +272,12 @@
     </func>
 
     <func>
-      <name>Module:pre_init_per_testcase(TestcaseName, Config, CTHState) -&gt; 
+      <name>Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) -&gt;
               Result</name>
       <fsummary>Called before init_per_testcase</fsummary>
       <type>
 	<v>TestcaseName = atom()</v>
+	<v>InitData = Config | SkipOrFail</v>
 	<v>Config = NewConfig = [{Key,Value}]</v>
 	<v>CTHState = NewCTHState = term()</v>
 	<v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
@@ -330,11 +334,12 @@
     </func>
 
     <func>
-      <name>Module:pre_end_per_group(GroupName, Config, CTHState) -&gt; 
+      <name>Module:pre_end_per_group(GroupName, EndData, CTHState) -&gt;
               Result</name>
       <fsummary>Called before end_per_group</fsummary>
       <type>
 	<v>GroupName = atom()</v>
+	<v>EndData = Config | SkipOrFail</v>
 	<v>Config = NewConfig = [{Key,Value}]</v>
 	<v>CTHState = NewCTHState = term()</v>
 	<v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
@@ -387,11 +392,12 @@
     </func>
 
     <func>
-      <name>Module:pre_end_per_suite(SuiteName, Config, CTHState) -&gt; 
+      <name>Module:pre_end_per_suite(SuiteName, EndData, CTHState) -&gt;
               Result</name>
       <fsummary>Called before end_per_suite</fsummary>
       <type>
 	<v>SuiteName = atom()</v>
+	<v>EndData = Config | SkipOrFail</v>
 	<v>Config = NewConfig = [{Key,Value}]</v>
 	<v>CTHState = NewCTHState = term()</v>
 	<v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index c938851e0e..86237f5fc1 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -252,6 +252,13 @@
     {ok, Handle} -&gt;
       {[{db_handle, Handle} | Config], CTHState#state{ handle = Handle }}
   end.</code>
+  <note>If using multiple CTHs, the first part of the return tuple will be
+  used as input for the next CTH. So in the case above the next CTH might
+  get <c>{fail,Reason}</c> as the second parameter. If you have many CTHs
+  which interact, it might be a good idea to not let each CTH return
+  <c>fail</c> or <c>skip</c>. Instead return that an action should be taken
+  through the <c>Config</c> list and implement a CTH which at the end takes
+  the correct action. </note>
 	
     </section>