Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Merge branch 'peppe/common_test/otp-10039' into maint

* peppe/common_test/otp-10039:
  Document the new timetrap interface
  • Loading branch information...
commit 7148dea6d94841cc70ff3e38beae51a586f56b5a 2 parents aa257fb + d67b408
Peter Andersson authored
28  lib/common_test/doc/src/common_test_app.xml
@@ -187,9 +187,13 @@
187 187
 	  test case is allowed to execute (including <c>init_per_testcase/2</c>
188 188
 	  and <c>end_per_testcase/2</c>). If the timetrap time is
189 189
 	  exceeded, the test case fails with reason
190  
-	  <c>timetrap_timeout</c>. If a <c>TimeFunc</c> function is specified,
191  
-	  it will be called initially and must return a value on
192  
-	  <c>TimeVal</c> format.</p>
  190
+	  <c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to
  191
+	  set a new timetrap by returning a <c>TimeVal</c>. It may also be
  192
+	  used to trigger a timetrap timeout by, at some point, returning a
  193
+	  value other than a <c>TimeVal</c>. (See the
  194
+	  <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
  195
+	  for details).
  196
+	</p>
193 197
 	
194 198
 	<p>The <c>require</c> tag specifies configuration variables
195 199
 	  that are required by test cases (and/or configuration functions)
@@ -313,9 +317,12 @@
313 317
 	  test case is allowed to execute (including <c>init_per_testcase/2</c>
314 318
 	  and <c>end_per_testcase/2</c>). If the timetrap time is
315 319
 	  exceeded, the test case fails with reason
316  
-	  <c>timetrap_timeout</c>. If a <c>TimeFunc</c> function is specified,
317  
-	  it will be called initially and must return a value on
318  
-	  <c>TimeVal</c> format.</p>
  320
+	  <c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to
  321
+	  set a new timetrap by returning a <c>TimeVal</c>. It may also be
  322
+	  used to trigger a timetrap timeout by, at some point, returning a
  323
+	  value other than a <c>TimeVal</c>. (See the
  324
+	  <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
  325
+	  for details).</p>
319 326
 	
320 327
 	<p>The <c>require</c> tag specifies configuration variables
321 328
 	  that are required by test cases (and/or configuration functions)
@@ -494,9 +501,12 @@
494 501
 	  exceeded, the test case fails with reason
495 502
 	  <c>timetrap_timeout</c>. <c>init_per_testcase/2</c>
496 503
 	  and <c>end_per_testcase/2</c> are included in the
497  
-	  timetrap time. If a <c>TimeFunc</c> function is specified,
498  
-	  it will be called before the test case (or <c>init_per_testcase/2</c>)
499  
-	  and must return a value on <c>TimeVal</c> format.</p>
  504
+	  timetrap time. A <c>TimeFunc</c> function can be used to
  505
+	  set a new timetrap by returning a <c>TimeVal</c>. It may also be
  506
+	  used to trigger a timetrap timeout by, at some point, returning a
  507
+	  value other than a <c>TimeVal</c>. (See the
  508
+	  <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
  509
+	  for details).</p>
500 510
 	
501 511
 	<p>The <c>require</c> tag specifies configuration variables
502 512
 	  that are required by the test case (and/or <c>init/end_per_testcase/2</c>).
81  lib/common_test/doc/src/write_test_chapter.xml
@@ -872,34 +872,63 @@
872 872
     <marker id="timetraps"></marker>
873 873
     <title>Timetrap timeouts</title>
874 874
     <p>The default time limit for a test case is 30 minutes, unless a
875  
-      <c>timetrap</c> is specified either by the suite info function
876  
-      or a test case info function. The timetrap timeout value defined
877  
-      in <c>suite/0</c> is the value that will be used for each test case
878  
-      in the suite (as well as for the configuration functions
879  
-      <c>init_per_suite/1</c> and <c>end_per_suite</c>). A timetrap timeout
880  
-      value set with the test case info function will override the value set
881  
-      by <c>suite/0</c>, but only for that particular test case.</p>
882  
-    <p>It is also possible to set/reset a timetrap during test case (or
883  
-      configuration function) execution. This is done by calling
884  
-      <c>ct:timetrap/1</c>. This function will cancel the current timetrap
885  
-      and start a new one.</p>
  875
+    <c>timetrap</c> is specified either by the suite-, group-,
  876
+    or test case info function. The timetrap timeout value defined by
  877
+    <c>suite/0</c> is the value that will be used for each test case
  878
+    in the suite (as well as for the configuration functions
  879
+    <c>init_per_suite/1</c>, <c>end_per_suite/1</c>, <c>init_per_group/2</c>,
  880
+    and <c>end_per_group/2</c>). A timetrap value defined by
  881
+    <c>group(GroupName)</c> overrides one defined by <c>suite()</c>
  882
+    and will be used for each test case in group <c>GroupName</c>, and any
  883
+    of its sub-groups. If a timetrap value is defined by <c>group/1</c>
  884
+    for a sub-group, it overrides that of its higher level groups. Timetrap
  885
+    values set by individual test cases (by means of the test case info
  886
+    function) overrides both group- and suite- level timetraps.</p>
  887
+    
  888
+    <p>It is also possible to dynamically set/reset a timetrap during the
  889
+    excution of a test case, or configuration function. This is done by calling
  890
+    <c>ct:timetrap/1</c>. This function cancels the current timetrap
  891
+    and starts a new one (that stays active until timeout, or end of the
  892
+    current function).</p>
  893
+    
886 894
     <p>Timetrap values can be extended with a multiplier value specified at
887  
-      startup with the <c>multiply_timetraps</c> option. It is also possible
888  
-      to let Test Server decide to scale up timetrap timeout values
889  
-      automatically, e.g. if tools such as cover or trace are running during
890  
-      the test. This feature is disabled by default and can be enabled with
891  
-      the <c>scale_timetraps</c> start option.</p>
  895
+    startup with the <c>multiply_timetraps</c> option. It is also possible
  896
+    to let the test server decide to scale up timetrap timeout values
  897
+    automatically, e.g. if tools such as cover or trace are running during
  898
+    the test. This feature is disabled by default and can be enabled with
  899
+    the <c>scale_timetraps</c> start option.</p>
  900
+    
892 901
     <p>If a test case needs to suspend itself for a time that also gets
893  
-      multipled by <c>multiply_timetraps</c>, and possibly scaled up if
894  
-      <c>scale_timetraps</c> is enabled, the function <c>ct:sleep/1</c>
895  
-      may be called.</p>
896  
-    <p>A function (<c>fun</c> or <c>MFA</c>) may be specified as timetrap value
897  
-      in the suite- and test case info function, e.g:</p>
898  
-      <p><c>{timetrap,{test_utils,get_timetrap_value,[?MODULE,system_start]}}</c></p>
899  
-      <p>The function will be called initially by Common Test (before execution
900  
-	of the suite or the test case) and must return a time value such as an
901  
-	integer (millisec), or a <c>{SecMinOrHourTag,Time}</c> tuple. More
902  
-	information can be found in the <c>common_test</c> reference manual.</p>
  902
+    multipled by <c>multiply_timetraps</c> (and possibly also scaled up if
  903
+    <c>scale_timetraps</c> is enabled), the function <c>ct:sleep/1</c>
  904
+    may be used (instead of e.g. <c>timer:sleep/1</c>).</p>
  905
+    
  906
+    <p>A function (<c>fun/0</c> or <c>MFA</c>) may be specified as
  907
+    timetrap value in the suite-, group- and test case info function, as
  908
+    well as argument to the <c>ct:timetrap/1</c> function. Examples:</p>
  909
+
  910
+    <p><c>{timetrap,{my_test_utils,timetrap,[?MODULE,system_start]}}</c></p>
  911
+    <p><c>ct:timetrap(fun() -> my_timetrap(TestCaseName, Config) end)</c></p>
  912
+
  913
+    <p>The user timetrap function may be used for two things:</p>
  914
+    <list>
  915
+      <item>To act as a timetrap - the timeout is triggered when the
  916
+      function returns.</item>
  917
+      <item>To return a timetrap time value (other than a function).</item>
  918
+    </list>
  919
+    <p>Before execution of the timetrap function (which is performed
  920
+    on a parallel, dedicated timetrap process), Common Test cancels
  921
+    any previously set timer for the test case or configuration function.    
  922
+    When the timetrap function returns, the timeout is triggered, <em>unless</em>
  923
+    the return value is a valid timetrap time, such as an integer,
  924
+    or a <c>{SecMinOrHourTag,Time}</c> tuple (see the
  925
+    <seealso marker="common_test">common_test reference manual</seealso> for
  926
+    details). If a time value is returned, a new timetrap is started
  927
+    to generate a timeout after the specified time.</p>
  928
+
  929
+    <p>The user timetrap function may of course return a time value after a delay,
  930
+    and if so, the effective timetrap time is the delay time <em>plus</em> the
  931
+    returned time.</p>
903 932
   </section>
904 933
 
905 934
   <section>

0 notes on commit 7148dea

Please sign in to comment.
Something went wrong with that request. Please try again.