Merge branch 'peppe/common_test_r14_dev_2' into dev

* peppe/common_test_r14_dev_2:
  Misc documentation updates
  Add documentation for run_test program
  Step vsn for test_server to 3.4
  Make {repeat*,N} property in group execute the group N times exactly
  Fix so that ct_run converts relative diretories in the code path to absolute
  Fix bug in handling framework:end_tc timeouts
  Fix bug that prevents the interactive shell mode to start properly
  Fix failing multiply timetrap test case
  Minor fixes in code and test suites
  Add support for executing pre-loaded suites (e.g. modules loaded as binaries)
  Add test suite for remote loading of binary suites
  Fix error with {repeat,0} property in groups causing double iterations
  Add support for config info functions (e.g. init_per_suite/0)
  Add support for dynamic timetrap handling
  Have end_per_testcase run even after timetrap_timeout and abort_testcase
  Flush old DOWN messages in demonitor
  Add groups in test specifications
  Add new tests for test case groups and test specifications
  Improve and fix various test suites
  Add event_handler_init start flag that can pass init arguments to event handlers
  ...

OTP-8703 peppe/common_test_r14_dev_2

1 files changed, 37 insertions, 7 deletions

diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 212e3d85be..5afec6de6a 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2009</year>
+      <year>2003</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>Writing Test Suites</title>
@@ -157,6 +157,15 @@
       <c>{skipped,Reason}</c> (where Reason is a user specific term).
     </p>
 
+    <p>The <c>end_per_testcase/2</c> function is called even after a
+      test case terminates due to a call to <c>ct:abort_current_testcase/1</c>,
+      or after a timetrap timeout. However, <c>end_per_testcase</c>
+      will then execute on a different process than the test case
+      function, and in this situation, <c>end_per_testcase</c> will
+      not be able to change the reason for test case termination by
+      returning <c>{fail,Reason}</c>, nor will it be able to save data with
+      <c>{save_config,Data}</c>.</p>
+
     <p>If <c>init_per_testcase</c> crashes, the test case itself is skipped 
     automatically (so called <em>auto skipped</em>). If <c>init_per_testcase</c>
     returns a <c>skip</c> tuple, also then will the test case be skipped (so
@@ -682,12 +691,33 @@
       <c>end_per_suite</c> execute, like test cases, on dedicated Erlang
       processes.
     </p>
+  </section>
 
+  <section>
+    <title>Timetrap timeouts</title>
+    <marker id="timetraps"></marker>
     <p>The default time limit for a test case is 30 minutes, unless a
-      <c>timetrap</c> is specified either by the test case info function
-      or the <c>suite/0</c> function.
-    </p>
-
+      <c>timetrap</c> is specified either by the suite info function
+      or a test case info function. The timetrap timeout value defined
+      in <c>suite/0</c> is the value that will be used for each test case
+      in the suite (as well as for the configuration functions
+      <c>init_per_suite/1</c> and <c>end_per_suite</c>). A timetrap timeout
+      value set with the test case info function will override the value set
+      by <c>suite/0</c>, but only for that particular test case.</p>
+    <p>It is also possible to set/reset a timetrap during test case (or
+      configuration function) execution. This is done by calling
+      <c>ct:timetrap/1</c>. This function will cancel the current timetrap
+      and start a new one.</p>
+    <p>Timetrap values can be extended with a multiplier value specified at
+      startup with the <c>multiply_timetraps</c> option. It is also possible
+      to let Test Server decide to scale up timetrap timeout values
+      automatically, e.g. if tools such as cover or trace are running during
+      the test. This feature is disabled by default and can be enabled with
+      the <c>scale_timetraps</c> start option.</p>
+    <p>If a test case needs to suspend itself for a time that also gets
+      multipled by <c>multiply_timetraps</c>, and possibly scaled up if
+      <c>scale_timetraps</c> is enabled, the function <c>ct:sleep/1</c>
+      may be called.</p>
   </section>
 
   <section>