Merge branch 'peppe/common_test/cth_improvements_docs' into maint

* peppe/common_test/cth_improvements_docs:
  Document new CT Hook functions

2 files changed, 81 insertions, 12 deletions

diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml
index 9c959945d2..12ec3bcec3 100644
--- a/lib/common_test/doc/src/ct_hooks.xml
+++ b/lib/common_test/doc/src/ct_hooks.xml
@@ -293,6 +293,63 @@
     </func>
 
     <func>
+      <name>Module:post_init_per_testcase(TestcaseName, Config, Return, CTHState) -&gt; Result</name>
+      <fsummary>Called after init_per_testcase.</fsummary>
+      <type>
+        <v>TestcaseName = atom()</v>
+        <v>Config = [{Key,Value}]</v>
+        <v>Return = NewReturn = Config | SkipOrFail | term()</v>
+        <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+        <v>CTHState = NewCTHState = term()</v>
+        <v>Result = {NewReturn, NewCTHState}</v>
+        <v>Key = atom()</v>
+        <v>Value = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>	
+        <p>OPTIONAL</p>
+
+        <p>This function is called after
+          <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso>
+          if it exists. It behaves the same way as
+          <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>,
+          but for function
+          <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso>
+          instead.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:pre_end_per_testcase(TestcaseName, InitData, CTHState) -&gt; Result</name>
+      <fsummary>Called before end_per_testcase.</fsummary>
+      <type>
+        <v>TestcaseName = atom()</v>
+        <v>InitData = Config</v>
+        <v>Config = NewConfig = [{Key,Value}]</v>
+        <v>CTHState = NewCTHState = term()</v>
+        <v>Result = {NewConfig, NewCTHState}</v>
+        <v>Key = atom()</v>
+        <v>Value = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>	
+        <p>OPTIONAL</p>
+
+        <p>This function is called before
+          <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso>
+          if it exists. It behaves the same way as
+          <seealso marker="ct_hooks#Module:pre_end_per_suite-3"><c>pre_end_per_suite</c></seealso>,
+          but for function
+          <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso>
+          instead.</p>
+
+        <p>This function can not change the result of the test case by returning skip or fail
+	tuples, but it may insert items in <c>Config</c> that can be read in
+	<c>end_per_testcase/2</c> or in <c>post_end_per_testcase/4</c>.</p>
+      </desc>
+    </func>
+
+    <func>
       <name>Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState) -&gt; Result</name>
       <fsummary>Called after end_per_testcase.</fsummary>
       <type>
@@ -312,7 +369,7 @@
         <p>This function is called after
           <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso>
           if it exists. It behaves the same way as
-          <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>,
+          <seealso marker="ct_hooks#Module:post_end_per_suite-4"><c>post_end_per_suite</c></seealso>,
           but for function
           <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso>
           instead.</p>
diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index 8f48756ada..6f722cb7db 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -237,10 +237,11 @@
 
      <list type="bulleted">
        <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_group</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_testcase</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>end_per_group</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>end_per_suite</c></seealso></item>
+       <item><seealso marker="common_test#Module:init_per_group-1"><c>init_per_group</c></seealso></item>
+       <item><seealso marker="common_test#Module:init_per_testcase-1"><c>init_per_testcase</c></seealso></item>
+       <item><seealso marker="common_test#Module:end_per_testcase-1"><c>end_per_testcase</c></seealso></item>
+       <item><seealso marker="common_test#Module:end_per_group-1"><c>end_per_group</c></seealso></item>
+       <item><seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso></item>
      </list>
 
         <p>
@@ -280,10 +281,11 @@
       <p>In a CTH, behavior can be hooked in after the following functions:</p>
       <list type="bulleted">
        <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>init_per_group</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>end_per_testcase</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>end_per_group</c></seealso></item>
-       <item><seealso marker="common_test#Module:init_per_suite-1"><c>end_per_suite</c></seealso></item>
+       <item><seealso marker="common_test#Module:init_per_group-1"><c>init_per_group</c></seealso></item>
+       <item><seealso marker="common_test#Module:init_per_testcase-1"><c>init_per_testcase</c></seealso></item>
+       <item><seealso marker="common_test#Module:end_per_testcase-1"><c>end_per_testcase</c></seealso></item>
+       <item><seealso marker="common_test#Module:end_per_group-1"><c>end_per_group</c></seealso></item>
+       <item><seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso></item>
      </list>
 
      <p>
@@ -393,6 +395,8 @@
  -export([post_end_per_group/4]).
 
  -export([pre_init_per_testcase/3]).
+ -export([post_init_per_testcase/4]).
+ -export([pre_end_per_testcase/3]).
  -export([post_end_per_testcase/4]).
 
  -export([on_tc_fail/3]).
@@ -438,7 +442,7 @@
  post_init_per_group(Group,Config,Return,State) ->
      {Return, State}.
 
- %% @doc Called after each end_per_group. 
+ %% @doc Called before each end_per_group. 
  pre_end_per_group(Group,Config,State) ->
      {Config, State}.
 
@@ -446,11 +450,19 @@
  post_end_per_group(Group,Config,Return,State) ->
      {Return, State}.
 
- %% @doc Called before each test case.
+ %% @doc Called before each init_per_testcase.
  pre_init_per_testcase(TC,Config,State) ->
      {Config, State#state{ ts = now(), total = State#state.suite_total + 1 } }.
 
- %% @doc Called after each test case.
+ %% Called after each init_per_testcase (immediately before the test case).
+ post_init_per_testcase(TC,Config,Return,State) ->
+     {Return, State}
+
+%% @doc Called before each end_per_testcase (immediately after the test case).
+ pre_end_per_testcase(TC,Config,State) ->
+     {Config, State}.
+
+ %% @doc Called after each end_per_testcase.
  post_end_per_testcase(TC,Config,Return,State) ->
      TCInfo = {testcase, TC, Return, timer:now_diff(now(), State#state.ts)},
      {Return, State#state{ ts = undefined, tcs = [TCInfo | State#state.tcs] } }.