From f6c1c3127f027cd717d01613cd356c5ada35041c Mon Sep 17 00:00:00 2001
From: Siri Hansen <siri@erlang.org>
Date: Mon, 22 Oct 2012 16:06:32 +0200
Subject: [common_test] Add option cover_stop

By default, test_server will always stop cover (and thus load back the
non cover compiled original beam files) after a test with code
coverage analysis is completed. The new option allows the common_test
user to specify that cover shall not be stopped. This can be useful if
there are processes still running old code, i.e. processes that have
not done any fully qualified function call after the cover
compilation, since loading the original code then will kill those
processes. This is only recommended if the erlang node is to be
stopped after the test run, or if cover can be manually stopped.
---
 lib/common_test/doc/src/cover_chapter.xml    | 27 +++++++++++++++++++++++++++
 lib/common_test/doc/src/ct_run.xml           |  2 ++
 lib/common_test/doc/src/run_test_chapter.xml |  5 +++++
 3 files changed, 34 insertions(+)

(limited to 'lib/common_test/doc/src')

diff --git a/lib/common_test/doc/src/cover_chapter.xml b/lib/common_test/doc/src/cover_chapter.xml
index 803a71de07..b2e64bfff0 100644
--- a/lib/common_test/doc/src/cover_chapter.xml
+++ b/lib/common_test/doc/src/cover_chapter.xml
@@ -108,6 +108,33 @@
       specifications</seealso>).</p>
   </section>
 
+  <section>
+    <marker id="cover_stop"></marker>
+    <title>Stopping the cover tool when tests are completed</title>
+    <p>By default the Cover tool is automatically stopped when the
+      tests are completed. This causes the original (non cover
+      compiled) modules to be loaded back in to the test node. If a
+      process at this point is still running old code of any of the
+      modules that are cover compiled, meaning that it has not done
+      any fully qualified function call after the cover compilation,
+      the process will now be killed. To avoid this it is possible to
+      set the value of the <c>cover_stop</c> option to
+      <c>false</c>. This means that the modules will stay cover
+      compiled, and it is therefore only recommended if the erlang
+      node(s) under test is terminated after the test is completed
+      or if cover can be manually stopped.</p>
+
+    <p>The option can be set by using the <c>-cover_stop</c> flag with
+      <c>ct_run</c>, by adding <c>{cover_stop,true|false}</c> to the
+      Opts argument to <c><seealso
+      marker="ct#run_test-1">ct:run_test/1</seealso></c>, or by adding
+      a <c>cover_stop</c> term in your test specification (see chapter
+      about <seealso
+      marker="run_test_chapter#test_specifications">test
+      specifications</seealso>).</p>
+
+  </section>
+
   <section>
     <title>The cover specification file</title>
     <p>These are the terms allowed in a cover specification file:</p>
diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index 9cc5495af7..da18640df7 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -104,6 +104,7 @@
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
+	[-cover_stop Bool]
 	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
         [-event_handler_init EvHandler1 InitArg1 and
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
@@ -138,6 +139,7 @@
 	[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
 	[-stylesheet CSSFile]
 	[-cover CoverCfgFile]
+	[-cover_stop Bool]
 	[-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
         [-event_handler_init EvHandler1 InitArg1 and
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index ea62df27cc..b5b914d506 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -153,6 +153,8 @@
       <item><c><![CDATA[-stylesheet <css_file>]]></c>, points out a user HTML style sheet (see below).</item>
       <item><c><![CDATA[-cover <cover_cfg_file>]]></c>, to perform code coverage test (see 
 	<seealso marker="cover_chapter#cover">Code Coverage Analysis</seealso>).</item>
+      <item><c><![CDATA[-cover_stop <bool>]]></c>, to specify if the cover tool shall be stopped after the test is completed (see
+	<seealso marker="cover_chapter#cover_stop">Code Coverage Analysis</seealso>).</item>
       <item><c><![CDATA[-event_handler <event_handlers>]]></c>, to install 
         <seealso marker="event_handler_chapter#event_handling">event handlers</seealso>.</item>
       <item><c><![CDATA[-event_handler_init <event_handlers>]]></c>, to install
@@ -495,6 +497,9 @@
       {cover, CoverSpecFile}.
       {cover, NodeRefs, CoverSpecFile}.
       
+      {cover_stop, Bool}.
+      {cover_stop, NodeRefs, Bool}.
+
       {include, IncludeDirs}.
       {include, NodeRefs, IncludeDirs}.
 
-- 
cgit v1.2.3