From 7d0d76f3a8170ddb5a3b07fd46fce835bb631cef Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang-solutions.com>
Date: Tue, 20 Sep 2011 15:42:54 +0200
Subject: Add documentation for cth_log_redirect and built-in hooks

OTP-9564
---
 lib/common_test/doc/src/ct_hooks_chapter.xml | 32 ++++++++++++++++++++++++++++
 lib/common_test/doc/src/run_test_chapter.xml | 10 ++++++++-
 lib/common_test/src/ct.erl                   |  2 +-
 3 files changed, 42 insertions(+), 2 deletions(-)

(limited to 'lib/common_test')

diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index dbb4310040..3b9620d0f2 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -405,6 +405,38 @@ terminate(State) ->
     ok.</code>
   </section>
 
+  <marker id="builtin_cths"/>
+  <section>
+    <title>Built-in CTHs</title>
+    <p>Common Test is delivered with a couple of general purpose CTHs that
+    can be enabled by the user to provide some generic testing functionality.
+    Some of these are enabled by default when starting running common_test,
+    they can be disabled by setting <c>enable_builtin_hooks</c> to
+    <c>false</c> on the command line or in the test specification. In the
+    table below there is a list of all current CTHs which are delivered with
+    Common Test.</p>
+
+    <table>
+      <row>
+	<cell><em>CTH Name</em></cell>
+	<cell><em>Is Built-in</em></cell>
+	<cell><em>Description</em></cell>
+      </row>
+      <row>
+	<cell>cth_log_redirect</cell>
+	<cell>yes</cell>
+	<cell>Captures all error_logger and SASL logging events and prints them
+	to the current test case log. If an event can not be associated with a
+	testcase it will be printed in the common test framework log. This will
+	happen for testcases which are run in parallel and events which occur
+	inbetween testcases. You can configure the level of
+	<seealso marker="sasl:sasl_app">SASL</seealso> events report
+	using the normal SASL mechanisms. </cell>
+      </row>
+    </table>
+
+  </section>
+
 </chapter>
 
 
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index e668568795..816aa5b1eb 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -150,6 +150,8 @@
         <seealso marker="event_handler_chapter#event_handling">event handlers</seealso> including start arguments.</item>
       <item><c><![CDATA[-ct_hooks <ct_hooks>]]></c>, to install
         <seealso marker="ct_hooks_chapter#installing">Common Test Hooks</seealso> including start arguments.</item>
+      <item><c><![CDATA[-enable_builtin_hooks <bool>]]></c>, to enable/disable
+        <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[-multiply_timetraps <n>]]></c>, extends <seealso marker="write_test_chapter#timetraps">timetrap
@@ -450,6 +452,8 @@
 
       {ct_hooks, CTHModules}.
       {ct_hooks, NodeRefs, CTHModules}.
+
+      {enable_builtin_hooks, Bool}.
     </pre>
       <p>Test terms:</p>
     <pre>
@@ -631,7 +635,11 @@
       <p>The minor log file contain full details of every single test
 	case, each one in a separate file. This way the files should
 	be easy to compare with previous test runs, even if the set of
-	test cases change.</p>
+	test cases change. If SASL is running those logs will also be
+        printed there by the
+	<seealso marker="common_test:ct_hooks_chapter#builtin_cths">
+	  cth_log_redirect built-in hook</seealso>.
+        </p>
       
       <p>Which information goes where is user configurable via the
 	test server controller. Three threshold values determine what
diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index 66da3ef742..3a96190256 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -149,7 +149,7 @@ run(TestDirs) ->
 %%%               {repeat,N} | {duration,DurTime} | {until,StopTime} |
 %%%               {force_stop,Bool} | {decrypt,DecryptKeyOrFile} |
 %%%               {refresh_logs,LogDir} | {basic_html,Bool} | 
-%%%               {ct_hooks, CTHs}
+%%%               {ct_hooks, CTHs} | {enable_builtin_hooks,Bool}
 %%%   TestDirs = [string()] | string()
 %%%   Suites = [string()] | string()
 %%%   Cases = [atom()] | atom()
-- 
cgit v1.2.3